    By Limin Fu. Released under the GNU Free Documentation License.
    [NAME]
    ALL.dao.macro

    [TITLE]
    Syntax Macro

    [DESCRIPTION]

    Dao supports a docent macro system which can be used to create new syntax or to
    simplify scripts. A set of markups can be used in a macro definition to control the
    syntax matching and transformation. These markups are similar to what are commonly used
    in Extended Backus-Naur Form (EBNF or simply BNF) representation of syntax. So that
    defining a macro ressembles to write a BNF-like representation of the source syntax to be
    matched, and a BNF-like representation of the target syntax to be applied.

       1  syntax [optional_language_id] {
       2      source_syntax_pattern
       3  } as {
       4      target_syntax_pattern
       5  }

    The following is a simple example to support a customized syntax such as for...in...do...
    end:

       1  syntax {
       2      'for' $ID1 'in' $EXP1 'do'
       3          [ $BL1 ]
       4      'end'
       5  } as {
       6      'for' '(' $ID1 'in' $EXP1 ')' '{'
       7          [ $BL1 ]
       8      '}'
       9  }
      10
      11  for a in {1, 2, 3} do
      12      io.writeln( a )
      13  end

    In the syntax patterns in this example, the tokens (identifiers) prefixed with $ are
    special markers used as special variables to represent identifier tokens, expressions or
    blocks. And, the string tokens with single qutotation marks represents normal tokens if
    they contain single valid tokens. These tokens can be placed between brackets and
    organized into groups to form complex patterns. Normal tokens may not need quotation
    marks, if they are not used as special variables, grouping and repetition markers.

     1  Controlling Markers

    The following control symbols are recognized by the Dao macro system,
      *  (): grouping;
      *  ?: optional (repeat zero or once), must follow ();
      *  *: repeat zero or more times, must follow ();
      *  +: repeat once or more times, must follow ();
      *  !: repeat zero times, ie, the previous group should not appear, must follow ();
      *  []: optional group, equivalent to () ?;
      *  {}: group with zero or more repeats, equivalent to () *;
      *  |: alternative pattern, must be inside paired control tokens such as (), [], {};
    If ?,*,+,! follow the special grouping [] or {}, these special grouping is considered
    the same as ().

     2  Variables

    The following prefixes can be used to define special variables that may also be use in
    the patterns,
      *  $ID : a valid identifier;
      *  $OP : a valid operater;
      *  $EXP : an expression or subexpression;
      *  $BL : a block of code may contain any type of syntax structures;
      *  $VAR : a temporary variable used in the target syntax pattern;
    The Dao parser will generate unique names for each macro application for temporary
    variables represented by $VAR-prefixed literal. $EXP-prefixed variable normally matches
    a whole expression, but in the case that there is a normal token (neither control token,
    nor special variable) following the variable in the defintion, it may match a
    sub-expression. $BL prefixed variable matches a set of statements (code BLock), and
    extend the matching as much as possible, similarly, if there is a normal token following
    the variable in the defintion, this normal token is used to decide the boundary of the
    code block. If $EXP,$BL variables are followed by a grouping pattern, the macro system
    will check the patterns in the grouping to figure out if there is a proper stoping token
    for the special variables.

    For special variables with the same names in the source and targe syntax patterns, it is
    preferable that they appear in the same grouping and repeating patterns in the source and
    target syntax. In this case, the syntax transformation has well defined behaviour.After
    the source pattern is matched and the tokens matching the special variables are
    extracted, the target pattern is scanned, and the extracted tokens are expanded at the
    position of the proper special variables.

     3  Accessibility

    If a syntax macro is defined without a language id, it will be applied strictly locally,
    namely, in the same file where it is defined. If it is defined with a language id, it
    will be applied in files that have extensions that match the language id. To use macros
    with language ids different from the file extension, one can explicitly make them
    applicable by:

       1  use syntax lang_id

     4  Examples

       1  # routine definition
       2  syntax dao_v1_syntax {
       3      'routine' $ID1 { '::' $ID2 } '(' [ $BL1 ] ')' ( ';' ) !
       4          ( '{' $BL2 '}' ) !
       5          [ $BL3 ]
       6      'end'
       7  } as {
       8      'routine' $ID1 { '::' $ID2 } '(' [ $BL1 ] ')' '{'
       9          [ $BL3 ]
      10      '}'
      11  }
      12
      13  # class definition
      14  syntax dao_v1_syntax {
      15      'class'   $ID1 { '::' $ID2 } [ '(' [ $BL1 ] ')' ]
      16          [ ':' $ID3 { '::' $ID4 } [ '(' [ $BL2 ] ')' ]
      17          { ',' $ID5 { '::' $ID6 } [ '(' [ $BL3 ] ')' ] } ]
      18          ( '{' $BL5 '}' ) !
      19          [ $BL4 ]
      20      'end'
      21  } as {
      22      'class' $ID1 { '::' $ID2 }
      23          [ ':' $ID3 { '::' $ID4 } [ '(' [ $BL2 ] ')' ]
      24          { ',' $ID5 { '::' $ID6 } [ '(' [ $BL3 ] ')' ] } ]
      25      '{'
      26          [ $BL4 ]
      27      '}'
      28  }
      29
      30  syntax dao_v1_syntax {
      31      'my' $ID1
      32  } as {
      33      'var' $ID1
      34  }
      35
      36  use syntax dao_v1_syntax;
      37
      38  class Klass
      39      public
      40
      41      my name = "Klass";
      42
      43      routine test( a :float ) io.writeln( "by test():", a ) end
      44      routine test( b :string ) io.writeln( "by test():", b ) end
      45  end
      46
      47  obj = Klass();
      48
      49  io.writeln( obj.name );
      50
      51  obj.test( 123 );
      52  obj.test( "abc" );