CGScript - Coding guideline

Objects

Objects in cgscript can be created by doing following this guideline.

First an object must be created. The normal name for this is xxxCGO where xxx is the name of the object in cgscript.

This object must inherit from CgScriptObject and it must have a CgAttribute.

For example, here is the absolute minimal class:

[Cg(OBJECT_TYPE_NAME, "write the documentation for the class here")]
internal class MyObjectCGO : CgScriptObject
{
   private const string OBJECT_TYPE_NAME = "MyObject";
   public override string ObjectTypeName
   {
      get { return OBJECT_TYPE_NAME; }
   }
}

The class must be internal or public, and non-abstract, and must not play with generics. The exception is that it may inherit from a generic baseclass (which then inherits from CgScriptObject), or implement a generic interface.

Object functions

Functions are exposed as cgscript functions by marking them with the CgAttribute and also marking all the parameters with the CgAttribute (see #Parameters).

The function must be internal or public, and non-abstract, and must not play with generics.

Overloads are supported, so the same name can be defined multiple times with different parameters. The rules for this is similar to C#s overload resolution (but not identical). If in doubt, don't use fancy parameters.

Example:

[Cg("ContainsKey", "Determines whether the dictionary contains the specified key with type is a string.")]
public bool ContainsKey([Cg("key", "Check with specific key")]string key)
{
   return _dict.ContainsKey(key);
}

Object properties

Properties have almost the same requirements as methods.

Example:

[Cg("Count", "Gets the number of key/value pairs contained in the dictionary.")]
public int Count
{
   get { return _dict.Count; }
}

The getter and setter may have different visibility, e.g. the getter may be public and the setter may be private. In that case, only the getter is accessible from CgScript.

However, note that this alternative marking of the getter/setter may not do what you expect:

public int Count
{
   [Cg("Count", "Gets the number of key/value pairs contained in the dictionary.")]
   get { return _dict.Count; }
}

This will register the getter as a function (ie. from cgscript you would have to call o.Count() instead of o.Count)

Object indexer

Indexers are a special construction in C# (and VB). They look a little bit like both Properties and Methods. So the syntax for registering them in CgScript is a little special.

The indexer must be marked with a CgAttribute, and the getter/setter must be marked with a CgAttribute also, the name must be get_Item/set_Item respectively in order to use it as an indexer inside CgScript. Furthermore the setter must use the very special "param:" prefix on the CgAttribute to document the value.

Example:

public IConstant this[[Cg("key", "The key used to lookup the value.")] string key]
{
   [Cg("get_Item", "Get an item based on a key.")]
   get { return _dict[key]; }
   [Cg("set_Item", "Set an item based on a key and a value.")]
   [param:Cg("value", "The value to set.")]
   set { _dict[key] = value; }
}

Parameters

CgScript objects support a number of types, that are automatically converted when calling the function and returning from the function:

• Void (For return values only) - Constant.Empty is returned
• string - Automatically converted to and from a StringConstant
• double - Automatically converted to and from a NumberConstant
• int - Automatically converted to and from a NumberConstant
• bool - Automatically converted to and from a BooleanConstant
• CGDateTime - Automatically converted to and from a DateTimeConstant
• Any type that implement IConstant - No conversion is done

Example:

[Cg("Add", "Adds the specified key and value to the dictionary with type of key is a string.")]
public bool Add([Cg("key", "Add with specific key")] string key,
                [Cg("value", "Add with specific value")] IConstant constant)

There are some special parameter types, that must all NOT be marked with a CgAttribute:

• Interpreter - If you require the interpreter to do something, you can get it by adding a Interpreter parameter.
• IList<IConstant> - This is roughly equivalent to a normal C# method that takes a "params object[]". This enables you to do advanced scenarios where the parameters from cgscript cannot be predicted.
• other - If a parameter is not marked with a CgAttribute, it is presumed it is a IoC type that must be resolved when calling the function. This works for Constructors, Methods and Properties.

Functions

Normal non-object functions - Yet to be written