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

[TITLE]
Syntax Macro (Removed)

[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 matchin
g and transformation. These markups are similar to what are commonly used in Extended Bac
kus-Naur Form (EBNF or simply BNF) representation of syntax. So that defining a macro res
sembles 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 spec
ial markers used as special variables to represent identifier tokens, expressions or bloc
ks.  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 in
to groups to form complex patterns. Normal tokens may not need quotation marks, if they a
re not used as special variables, grouping and repetition markers.

 1  Controlling Markers    
 1  Controlling 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    
 2  Variables    
 2  Variables    

The following prefixes can be used to define special variables  that may also be use in t
he 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 variab
les 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 spec
ial 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 mu
ch as possible, similarly, if there is a normal token following the variable in the defin
tion, this normal token is used to decide the boundary of the code block. If $EXP,$BL var
iables are followed by a grouping pattern, the macro system will check the patterns in th
e 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    
 3  Accessibility    
 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 wil
l 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 b
y:
     
   1  use syntax lang_id
     

 4  Examples    
 4  Examples    
 4  Examples    

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