    [NAME]
    ALL.dao.routine.section

    [TITLE]
    Code Section Methods

    [DESCRIPTION]

    Code section/block method is an alternative to functional methods in other languages
    such as Python. Dao code section is syntactically very similar to the code block in Ruby.
    Unlike Ruby code blocks which are compiled as closure and passed as parameter (so it's
    essentially a syntax sugar), Dao code section is really a code section in its host
    function, no closure is created a runtime. When needed, the method locate the code
    section 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
    and 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
    parameters 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
    implicitly 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
    prototype,

       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
    comparison. The code section return type int indicates that the code section is expected
    to return an integer as the comparison result. So this sort() can be use in the
    following ways,

       1  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  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 example 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      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  }