[NAME]
ALL.dao.routine.section

[TITLE]
Code Section Methods

[DESCRIPTION]

Code section/block method is an alternative to functional methods in other languages suc
h as Python. Dao code section is syntactically very similar to the code block in Ruby. Un
like Ruby code blocks  which are compiled as closure and passed as an implicit parameter 
(so it's essentially a syntax sugar), Dao code section is really a code section in its ho
st function, no closure is created a runtime.  When needed, the method locate the code se
ction in the host function  and run that section of codes.

To define a code section method, it will be necessary to specify two set of parameters an
d return types: one for the normal routine, and the other for the code section. 
     
   1  routine meth_name( meth_params ) [sect_params => sect_return] => meth_return
   2  {
   3      ...
   4  }
     
The parameter list prototype sect_params for the code section specifies what kind of para
meters this method will pass to the code section; and the section return type sect_return
indicates what type of value this method expects the code section to return.

Code section method can be called in the following way: 
     
   1  returned = meth_name( meth_params ) {
   2      code_block
   3  }
     
If there is no method parameter, it can be simply written as: 
     
   1  returned = meth_name {
   2      code_block
   3  }
     
By default, the code section receives the parameters passed in by the method through impl
icitly defined variables named X and Y. User can choose to use more meaningful names by, 
     
   1  returned = meth_name { [index, item]
   2      code_block
   3  }
     


For example, list type has a code section method for sorting with  the following prototyp
e, 
     
   1  sort( self :list<@T>, k=0 ) [X :@T, Y :@T => int] => list<@T>
     
Here the code section parameters X and Y are used to pass two items of the list for compa
rison. The code section return type int indicates that the code section is expected to re
turn an integer as the comparison result. So this sort() can be use in the following ways
, 
     
   1  var numlist = { 11, 44, 21, 32, 56, 67, 25 }
   2  
   3  # Sort all by ascend order:
   4  numlist.sort { X < Y }
   5  
   6  # Sort by descend order until the largest 3 items are sorted:
   7  numlist.sort( 3 ) { X > Y }
   8  # Now the first 3 items of the list is the largest 3 items;
   9  
  10  var tuplist = { ( 2, 'ghi' ), ( 1, 'def' ), ( 2, 'abc' ), ( 1, 'abc' ) }
  11  tuplist.sort {
  12      # First sort by the first items of the tuples;
  13      if( X[0] != Y[0] ) return X[0] < Y[0];
  14      # Then sort by the second items;
  15      return X[1] < Y[1];
  16  }
     


In a user defined code section method, the yield statement can be used to pass parameters
and invoke the execution of the code section that is attached to the call. Here is an exa
mple for user defined code section method, 
     
   1  # A function that can be called with a code section.
   2  # The code section is expected to take an integer as parameter,
   3  # and return a string.
   4  routine Test() [X :int => string] => string
   5  {
   6      io.writeln( 'In functional method!' );
   7      var s = yield( 123 ); # execute the code section;
   8      io.writeln( 'Yielded value:', s );
   9      return s;
  10  }
  11  
  12  Test {
  13      io.writeln( 'In code section:', X );
  14      return 'abc';
  15  }