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" );