Write initial standards document

CSCZ.Standard.md

@@ -0,0 +1,125 @@
+# CSCZ
+> v0.4
+
+## Table of Contents
+[TOC]
+
+## Overview
+CSCZ aims to be a compressed C# class definition file format. This document formally defines the language, documenting all features. Each CSCZ file may, as of the current time, SHALL only contain the definition for a single class.
+
+The format is intended to be parsed line by line. Each line is read in one after the next, with later lines overwriting earlier lines, should a conflict occur. A generator MAY NOT give a warning about detected conflicts, choosing instead to handle them silently.
+
+Whitespace MUST be trimmed from both ends of every line, and in other stages of the parsing process, should the need arise. This allows whitespace to be used for layout purposes in examples, and prevents confusion due to automatic conversion by various editors.
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
+
+## Glossary
+ - `definition` - A single instruction, for example `# ClassName`. Only only one definition may be specified per line. This makes the format easy to parse.
+ - `field signature` - A type followed by a variable name, for example `List<string> destinations`.
+
+
+### Syntax
+
+#### Class name
+The name of the class may be specified by prefixing a line with a hash symbol (`#`), followed by the name of the class:
+
+```cscz
+# ClassName
+```
+
+An arbitrary number of spaces MAY be inserted (or indeed none at all) between the hash symbol and the beginning of the class name:
+
+```cscz
+#    SpritePacker
+```
+
+The class name MUST NOT contain spaces. The following is not valid and MUST throw an informative error:
+
+```cscz
+# My Class Name
+```
+
+##### Namespaces
+Additionally, The class name may contain one or more dots (`.`). Such dots are assumed to be a namespace declaration. The generated C&sharp; class MUST be wrapped in the appropriate `namespace` declaration.
+
+```cscz
+# SBRLUtilities.Imagetools
+```
+
+Would result in:
+
+```csharp
+using System;
+
+namespace SBRLUtilities
+{
+	class Imagetools 
+	{
+		public Imagetools()
+		{
+		}
+	}
+}
+```
+
+#### Using Statements
+Using statements may be specified by prefixing a line with a dash (`-`). The namespace will then be added to the beginning of the generated output. Similarly to the class name definition, an arbitrary number of spaces MAY be inserted (or indeed none at all) between the dash and the beginning of the using statement namespace.
+
+```cscz
+- OpenTk
+```
+
+```cscz
+ -     SBRLUtilties
+```
+
+The `System` namespace SHOULD be included by default.
+
+##### Shortcuts
+To save on typing, a number of shortcuts MAY be used instead of a full namespace name. These shortcuts SHALL be expanded by the generator. Shortcuts SHOULD NOT use more than 3 letters, and MUST NOT contain whitespace. Here is a list of all the official shortcuts:
+
+Shortcut	| Expansion
+------------|---------------------
+`c`			| `System.Collections.Generic`
+`cc`		| `System.Collections.Concurrent`
+`r`			| `System.Text.RegularExpressions`
+`n`			| `System.Net`
+`s`			| `System.Net.Sockets`
+`x`			| `Microsoft.Xna.Framework`
+`xg`		| `Microsoft.Xna.Framework.Graphics`
+`xs`		| `Microsoft.Xna.Framework.Storage`
+`xi`		| `Microsoft.Xna.Framework.Input`
+`oo`		| `OpenTK.Graphics.OpenGL`
+
+Additional shortcuts may be added by opening an issue on this repository or sending a pull request. Generators MAY support other shortcuts that are not listed here. Such shortcuts SHOULD be listed in the help for the generator.
+
+#### Fields
+Fields in the class can be specified by putting a field signature on a line by itself. For example:
+
+```cscz
+int radius
+float height
+List<string> buildingNames
+```
+
+To ease parsing, neither the type nor the variable name may contain spaces. The following are all incorrect:
+
+```cscz
+Dictionary<string, int> inventory
+List <int> carrotSizes
+```
+
+The above should read:
+
+```cscz
+Dictionary<string,int> inventory
+List<int> carrotSizes
+```
+
+Fields, upon code generation, can be converted into C# code in 2 ways:
+
+ - Public variables
+ - Private variables with public accessors
+
+The method that is used SHOULD be configurable by the user. For example, the official generator supports the command line flags `--public` and `--private`.
+