TIScript: classes, decorators and events.

One of differences of TIScript from JavaScript is that it has classes and namespaces.

Declaration of a class in source code looks like this:

class Baz
{
  function foo() { ... }
  property bar(v) { ... }
  // ... other functions, properties, variables,
  // constants and decorator calls ...
}

As you see class declartion in TIScript is pretty similar to the ones in Java or in C++. The only difference is that in TIScript class declaration is an executable (in runtime) entity. While parsing the class declaration above the compiler produces bytecode that is equivalent of this:

const Baz = new Class();
      Baz.foo = function() { .... }
      Baz.bar = property(v) { .... }
...

So while loading bytecodes produced by the compiler TIScript VM will execute sequence of commands to build such class object.

As class construction is an executable chunk of code then, in principle, we can modify/synthesize class declarations in runtime. And decorators in TIScript are just about this – they allow to execute decorator functions in context of class that is being declared.

Decorator is an ordinary function with the name starting from ‘@’ character. It should have at least one parameter that will receive reference to the object being decorated.

Example of the decorator function, the @returns decorator creates proxy function around call of declarating function and verifies its return value:

function @returns(func, returnType)
{
   return function(params..)
   {
      var r = func.apply(this,params);
      assert typeof r == returnType;
      return r;
   }
}

Having such decorator in place we can declare methods of classes with checks of their return values:

class Zum
{
   @returns #integer
     function Add(i1,i2) {...}
}

The @returns #int function()...  here is a decorator function invocation. Under the hood all this will produce following code:

const Zum = new Class();
      Zum.Add = @returns( function(i1,i2) {...}, #integer );

Call of the @returns() creates proxy for its parameter function. The result (the proxy function) will be assigned to the Add field of the class object. As you may see decorators are pretty much syntax sugar that if properly used may increase expressiveness of your code a lot.

The this environment variable inside the decorator function is getting reference to the context object of the decorator call. E.g. inside class declaration this inside decorator function body will contain reference to the class object.

TIScript supports three types of decorators in total:

1. Function decorators:  @decorator [...params..] function() { ... }
2. Class (or namespace) decorators: @decorator [...params..] class { ... }
3. Empty decorators: @decorator [...params..] ;

Last one – empty decorator – is used in cases when it is a need to synthesize some properties or functions.

Here is practical example of empty decorators used to declare events in class VGrid (Sciter SDK/samples/ideas/virtual-grid/. Virtual Grid is created by Dmitrii Yakimov from http://activekitten.com).

class VGrid: Behavior
{
    const BUF_ROWS = 64;
    ...

   // Events supported by VGrid instances:

   // onCurrentRowChanged( this_grid, row )
   @DECLARE_EVENT #onCurrentRowChanged;

   // onHeaderClick( this_grid, evt, colNo, th )
   @DECLARE_EVENT #onHeaderClick;

   // onCellClick( this_grid, evt, colNo, rowNo, td)
   @DECLARE_EVENT #onCellClick;

   // onRowClick( this_grid, evt, rowNo, tr)
   @DECLARE_EVENT #onRowClick;
}

Each @DECLARE_EVENT eventName; decorator call here creates in the class these three fields:

• property eventName(v) – that represents list of event handlers assigned to the grid instance by users of the class,
• function notify_eventName() – function used internally by the class to "raise the event" and
• var _eventName = [] – variable that holds a list (array) of event handlers (functions) attached to the event by users of the grid.

And here is the implementation of the @DECLARE_EVENT decorator function:

function @DECLARE_EVENT(dummy, eventName)
{
  // create symbols for the fields:
  var notify_sym = symbol( "notify_" + eventName.toString());
  var list_sym = symbol( "_" + eventName.toString());
  var prop_sym = eventName;

  // generate 'notify_' function:
  this[ notify_sym ] = // 'this' here is a class being decorated
    function(params..)
    {
      // 'this' here is VGrid *instance*
      var list = this[list_sym];
      if(typeof list == #array)
      {
        // invoke each function in subscriptions list:
        for( var f in list )
          f.apply(this, this, params); // always pass 'this' in the
                                       // first param - source element
      }
    }
  // adding property  that allows to push
  this[prop_sym] = // 'this' here is a class being decorated,
                   // generating computable property for it.
    property(v)
    {
      get { return this[list_sym] || (this[list_sym] = []); }
      set { throw String.$(Use element.{ list_sym }.push(func) 
                                             to subscribe to this event); }
    }
}

The decorator function above is a bit cryptic but defintions like:

@DECLARE_EVENT #onCurrentRowChanged;
@DECLARE_EVENT #onHeaderClick;
...

allow to declare and see the whole event set in compact and convenient form.