cscz/CSCZ.Standard.md

CSCZ

The C♯ Class Generator

Version 0.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.

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:

# 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:

#    SpritePacker

The class name MUST NOT contain spaces. The following is not valid and MUST throw an informative error:

# 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♯ class MUST be wrapped in the appropriate namespace declaration.

# SBRLUtilities.Imagetools

Would result in:

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.

- OpenTk

 -     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:

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:

Dictionary<string, int> inventory
List <int> carrotSizes

The above should read:

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.