sbuilder-ethereum 0.0.6

data/lib/sbuilder/generate/tla_element_generator.rb

@@ -0,0 +1,1206 @@
+module Sbuilder
+  module Ethereum
+
+    ###
+    # Api to create TLA generate elements i.e. data SEXPs defining TLA
+    # language elements, and mustache partials to render  data
+    # SEXPs to TLA language.
+    #
+    #
+    class TlaElementGenerator
+
+      PROGNAME = nil       # progname for logger default class name
+      include MyLogger     # mix logger
+
+      # @attr [Hash] partials intialized with #setPartials, cumulated
+      # using #addPartial
+      attr_reader :partials
+
+      # @attr [Hash] partials_duplicateCheck, used only as guarantee
+      # againts redefinition
+      attr_reader :partials_duplicateCheck
+
+      # @attr [Hash] validMetatypes raise exception for unknwon mentateyps
+      attr_reader :validMetatypes
+
+      # @attr [Hash] labeledStmts
+      #
+      # @option labeledStmts [:Symbol] <sTlaType> generate template
+      # map to true is label should be followed
+      attr_reader :labeledStmts
+
+      # text to prefix trace print
+      TRACE_PREFIX="TRACE>"
+
+      # ------------------------------------------------------------------
+      # @!group Construct & configure
+
+      def initialize( options = {} )
+        @options = options
+        @logger = getLogger( nil, options )
+        @logger.info "#{__method__}: initalized"
+
+        # initially no known template requiring labe
+        @labeledStmts = {}
+
+      end
+
+      def setPartials( partials )
+        @partials = partials
+        @partials_duplicateCheck = {}
+      end
+
+      def setValidMetatypes( validMetatypes )
+        @validMetatypes = validMetatypes
+      end
+      # @!endgroup
+      
+      # ------------------------------------------------------------------
+      # @!group Statement labeling
+
+      ##
+      # Configure +sTlaType+ in +labeledStmts+ to require a label
+      #
+      # @see requiresLabelAfter
+      def tlaStatementTypeRequiresLabel( sTlaType )
+        labeledStmts[sTlaType] = true
+      end
+
+      ##
+      # Flag +stmt+ to include label if +hiddenStmt+ requires label.
+      #
+      # @param [Boolean ] labelFollowingStatemaent used return 'true'
+      # for 'isLabedStatement' if within a block. If not within block delegate
+      # to labedStatement
+      #
+      # @see requiresLabelAfter
+      def statementRequiresLabel( stmt, labedStatement=nil )
+        stmt.define_singleton_method( :labelFollowingStatement ) do |inBlock|
+          return true if labedStatement.nil?
+          inBlock ? true : labedStatement
+        end
+      end
+
+      ##
+      # Statement 'stmt' contains a block with 'stmts', which should
+      # also be labeled. Later, use :labelBlockStatements to return
+      # 'stmts' to label.
+      def setLabelBlockStatements( stmt, stmts, methodName = :labelBlockStatements )
+        stmt.define_singleton_method( methodName ) do
+          stmts
+        end
+      end
+
+
+      ##
+      # Check whether +stmt+ with +stmt.sexp_type+ should be followed
+      # by a labeled statement.
+      #
+      # @param [SexpTla] stmt sexp which may respond to ':labelFollowingStatement'
+      #
+      # @return [Boolean] true is +sTlaType+ is found in
+      # +labeledStmts+ hash OR stmt.labelFollowingStatement
+      def requiresLabelAfter( stmt, inBlock=false )
+        return false unless stmt
+        # if s( s(:sym, ..), s(:sym,)) vs. s(:sym, ..)
+        sTlaType = stmt.any? && !stmt[0].is_a?(Symbol) ? stmt.last.sexp_type : stmt.sexp_type
+
+        # static 
+        if labeledStmts[sTlaType] ||
+           ( stmt.respond_to?(:labelFollowingStatement) && stmt.labelFollowingStatement(inBlock))
+           return true
+        end
+        # dynamic recursion to block
+        if stmt.respond_to?(:requiresLabelAfterChecker)
+          stmt.requiresLabelAfterChecker.each do |st|
+            return true if requiresLabelAfter( st, true )
+          end
+        end
+        return false
+      end
+      
+
+
+      # @!endgroup
+
+      # ------------------------------------------------------------------
+      # @!group Create TLA specific generate element SEXPs
+      
+      def gen_label_it( tla )
+        sym = :TLA_label_it
+        tlaStatementTypeRequiresLabel( sym )
+        addPartial(  sym, "{|#EVAL|}tla{|/EVAL|}" )
+        stla( sym, { :tla => tla } )
+      end
+
+      def gen_macro( name, parameters, stmts )
+        
+        sym = :TLA_macro
+        addPartial(
+          sym,
+          "macro {|#EVAL|}name{|/EVAL|}( {|#parameters|}{|#EVAL|}parameter{|/EVAL|}{|_comma|}{|/parameters|} ) {\n"\
+          "{|#EVAL|}stmts{|/EVAL|}"\
+          "}"
+        )
+
+        # allow singleton parameter
+        parameters = parameters.is_a?( Array ) ? parameters : [parameters]
+        
+        stla( sym, {
+                :name => name,
+                :parameters => parameters.any?  ?
+                                 parameters.map.with_index do |p,i|
+                                   { :_comma => (i+1) == parameters.length ? '' : ',',
+                                     :parameter => p.is_a?(String)  ? gen_plainname( p ): p,
+                                   }
+                                 end :
+                                 false,
+                :stmts => stmts,
+              })
+      end
+      
+      def gen_service_procedure( serviceName, interfaceName, localVariables, stmts=gen_stmts(s()) )
+        
+        sym = :TLA_Procedure
+        addPartial(
+          sym,
+          <<-EOS.unindent
+          procedure {|#EVAL|}name{|/EVAL|}( {|#EVAL|}name{|/EVAL|}_input ) 
+             {|#localVariables.length|}variable {|/localVariables.length|}{|#localVariables|} {|#EVAL|}variable{|/EVAL|}{|_comma|}{|/localVariables|}{|#localVariables.length|};{|/localVariables.length|}
+          {
+            {|#EVAL|}name{|/EVAL|}_start:
+              {|#EVAL|}start{|/EVAL|};
+
+              (* body of {|#EVAL|}interfaceName{|/EVAL|} *)
+              {|#EVAL|}stmts{|/EVAL|}
+
+            {|#EVAL|}name{|/EVAL|}_exit:
+              goto {|#EVAL|}name{|/EVAL|}#{TlaElementText::TLA_LABEL_END};
+            {|#EVAL|}name{|/EVAL|}#{TlaElementText::TLA_LABEL_FAIL}:
+               \\* throw command sends here
+               InfrastructureServiceReturn( "{|#EVAL|}interfaceName{|/EVAL|}", FALSE, Nil);
+               goto {|#EVAL|}name{|/EVAL|}_end;
+
+            {|#EVAL|}name{|/EVAL|}#{TlaElementText::TLA_LABEL_ABORT}:
+               \\* should not happen??
+               print <<"ABORT {|#EVAL|}name{|/EVAL|}">>;
+               InfrastructureServiceReturn( "{|#EVAL|}interfaceName{|/EVAL|}", Abort, Nil);
+               \\* schedule_throw( "{|#EVAL|}name{|/EVAL|}_exit" );
+            {|#EVAL|}name{|/EVAL|}#{TlaElementText::TLA_LABEL_END}:
+                ethereum_service_pop( "{|#EVAL|}interfaceName{|/EVAL|}" );
+            {|#EVAL|}return{|/EVAL|};
+          }
+          EOS
+        )
+
+        name = serviceName.is_a?( String)  ? gen_plainname(serviceName) : serviceName
+        entry_exit = s(
+          gen_str(serviceName),
+          TlaElementText::FW_STATE_ACCOUNTS_TEMP, gen_specname(:eth, TlaElementText::FW_STATE_ACCOUNTS_TEMP),
+          TlaElementText::FW_STATE_STORAGE_ROOT_TEMP, gen_specname(:eth, TlaElementText::FW_STATE_STORAGE_ROOT_TEMP),
+          # TlaElementText::FW_STATE_GAS_USED_TEMP, gen_specname(:eth, TlaElementText::FW_STATE_GAS_USED_TEMP),         
+          TlaElementText::FW_STATE_MINED, gen_specname(:eth, TlaElementText::FW_STATE_MINED),
+          "input",  gen_identifier( name, "_input" ),
+        )
+        
+        stla( sym, {
+                :name => name,
+                :localVariables => localVariables.map.with_index do |v,i|
+                  {
+                    :variable => v,
+                    :_comma => (i+1) == localVariables.length ? '' : ',',
+                  }
+                end,
+                :interfaceName => interfaceName.is_a?( String)  ? gen_plainname(interfaceName) : interfaceName,
+                :start => gen_traced_stmt(
+                  gen_skip,
+                  s( "ENTRY:" ) + entry_exit,
+                ),
+                :stmts => stmts,
+                :return =>
+                gen_traced_stmt(
+                  gen_return,
+                  s( "EXIT:", ) + entry_exit, 
+                ),
+              })
+      end
+      
+      
+      
+      ##
+      # @return +specName+
+      def gen_expression2( expr1, op, expr2 )
+        sym = :TLA_expression2
+        addPartial( sym, "{|#EVAL|}expr1{|/EVAL|} {|#EVAL|}op{|/EVAL|} {|#EVAL|}expr2{|/EVAL|}" )
+        stla( sym, {
+                :expr1 => expr1,
+                :op => op,
+                :expr2 => expr2,                                
+              })
+      end
+
+      ##
+      # @return [ f1 |-> type1, f2 |->type2 ]
+      def gen_record_definition( arrOfFields )
+
+        sym = :TLA_record_definition
+        addPartial( sym, "[ {|#fields|}{|#EVAL|}val{|/EVAL|}{|_comma|} {|/fields|}]" )
+
+        # simplify if just one given
+        arrOfFields = arrOfFields[0].is_a?( Symbol ) ? s(arrOfFields) : arrOfFields
+        
+        # last element no comma
+        stla( sym,
+              {
+                :fields => arrOfFields.map.with_index { |f,i|
+                  { :_comma => (i+1) == arrOfFields.length ? '' : ',', :val => f }
+                }
+              })
+        
+      end
+
+
+      ##
+      # +variable+ \in +set+
+      def gen_set_iterate( variable, set )
+
+        sym = :TLA_set_iterate
+        addPartial( sym, "{|#EVAL|}variable{|/EVAL|} \\in {|#EVAL|}set{|/EVAL|} " )
+
+        # last element no comma
+        stla( sym,
+              {
+                :variable => variable.is_a?( String)  ? gen_plainname(variable) : variable,
+                :set => set.is_a?( String)  ? gen_plainname(set) : set,                
+              })
+      end
+
+      ##
+      # { map : S}
+      def gen_set_map( map, set )
+
+        sym = :TLA_set_map
+        addPartial( sym, "{ {|#EVAL|}map{|/EVAL|} : {|#EVAL|}set{|/EVAL|} } " )
+
+        # last element no comma
+        stla( sym,
+              {
+                :map => map.is_a?( String)  ? gen_plainname(map) : map,
+                :set => set.is_a?( String)  ? gen_plainname(set) : set,                
+              })
+      end
+      
+      
+      
+
+      # # @return [ idName |-> idVal, f2 |-> Nil, ... ]
+      def gen_new_record( idVal, arrOfFields )
+
+        sym = :TLA_new_record
+        addPartial(
+          sym,
+          <<-EOS.unindent
+          [ {|#EVAL|}idVal{|/EVAL|}, {|#fields|}{|#EVAL|}val{|/EVAL|}{|_comma|} {|/fields|} ]
+          EOS
+        )
+
+        # last element no comma
+        stla( sym,
+              {
+                :idVal => idVal,
+                :fields => arrOfFields.map.with_index do |f,i|
+                  { :_comma => (i+1) == arrOfFields.length ? '' : ',',
+                    :val => f
+                  }
+                end
+              })
+        
+        
+      end
+
+      def gen_record_field_definition( name, value )
+        # name |-> value (notice spaces)
+        gen_name_op_operand( name, '|->', value )
+      end
+      def gen_record_field( record, field )
+        # A.x 
+        gen_name_op_operand( record, '.', field, "" )        
+      end
+      def gen_record_named_field( record, field )
+        # A[x]
+        sym = :TLA_record_named_field
+        
+        addPartial( sym, "{|#EVAL|}record{|/EVAL|}{|sepl|}{|#EVAL|}field{|/EVAL|}{|sepr|}" )
+        
+        stla( sym,
+              {
+                :record => record.is_a?( String ) ? gen_plainname(record) : record,
+                :sepl => '[',
+                :sepr => ']',                
+                :field => field.is_a?( String ) ? gen_plainname(field) : field,
+              })
+      end
+      
+      
+      
+      def gen_name_op_operand( name, op, operand, sep=" " )
+        
+        sym = :TLA_name_op_operand
+        addPartial( sym, "{|#EVAL|}name{|/EVAL|}{|sep|}{|{op}|}{|sep|}{|#EVAL|}operand{|/EVAL|}" )
+        
+        stla( sym,
+              {
+                :name => name.is_a?( String ) ? gen_plainname(name) : name,
+                :op => op,
+                :sep => sep,
+                :operand => operand.is_a?( String ) ? gen_plainname(operand) : operand,
+              })
+        
+      end
+
+      ##
+      # Map interface to service name e.g./customer(get), Demo()
+      def gen_service_name( interface )
+        gen_identifier( interface )
+      end
+
+      def gen_identifier( identifier, posfix="" )
+
+        sym = :TLA_identifier
+        addPartial( sym, "{|#EVAL|}identifier{|/EVAL|}{|#EVAL|}postfix{|/EVAL|}" )
+        
+        stla( sym, {
+                :identifier => identifier.is_a?( String) ?
+                                 gen_plainname(identifier) :
+                                 identifier,
+                :postfix => posfix.is_a?( String) ? gen_plainname(posfix) : posfix,
+              })
+      end
+
+
+      ##
+      # @return Nil
+      def gen_empty_set()
+        sym = :TLA_emptyset
+
+        addPartial( sym, "{}" )
+        
+        stla(sym, {
+             })
+      end
+
+      def gen_list( elements )
+        sym = :TLA_list
+        addPartial( sym, "{|#elements|}{|#EVAL|}element{|/EVAL|}{|_comma|}{|/elements|}" )
+
+        # allow singleton parameter
+
+        elements = elements.is_a?( String)  ? gen_plainname(elements) : elements
+        elements = elements[0].is_a?( Symbol ) ? s(elements) : elements
+        
+        stla( sym,
+              {
+                :elements => elements.map.with_index { |f,i|
+                  { :_comma => (i+1) == elements.length ? '' : ',', :element => f }
+                }
+              })
+
+                
+      end
+
+      ##
+      # @return Nil
+      def gen_set( element )
+        sym = :TLA_set
+        addPartial( sym, "{ {|#EVAL|}element{|/EVAL|} } " )
+        
+        stla(sym, {
+               :element => element
+             })
+      end
+
+      def gen_TRUE
+        gen_plainname( "TRUE" )
+      end
+
+      def gen_FALSE
+        gen_plainname( "FALSE" )
+      end
+
+      ##
+      # @return Nil
+      def gen_nilElement()
+        sym = :TLA_nil_element
+
+        addPartial( sym, "Nil" )
+        
+        stla( sym, {})
+      end
+
+
+      def gen_op_set_minus()
+        gen_op_operator( "\\" )
+      end
+
+      ## 
+      # Common behavior to output operator +op+
+      def  gen_op_operator( op )
+        sym = :TLA_op_operator
+
+        addPartial( sym, "{|operator|}" )
+        
+        stla( sym, {
+                :operator => op
+              })
+
+      end
+
+      ##
+      # Define state variable +variable+ and initialize
+      # with +initExpr+
+      def gen_state_variable( variable, initExpr )
+        sym = :TLA_state_variable
+        addPartial( sym, "{|#EVAL|}variable{|/EVAL|} = {|#EVAL|}init_expression{|/EVAL|};" )
+        
+        stla( sym, {
+                :variable => variable, 
+                :init_expression => initExpr, 
+              })
+      end
+
+      ##
+      # @param [String] interfaceName e.g. 'Demo()' or 'Demo(set)'
+      #
+      # @return [String] input variable name
+      def gen_interface_input_variable_name( interfaceName, metatype=:solidity_contract_function )
+        gen_identifier( gen_specname( setMetatype( metatype ), interfaceName), "_input" )
+      end
+
+      ##
+      # @param [String] interfaceName e.g. 'Demo()' or 'Demo(set)'
+      #
+      def gen_interface_abort_label( interfaceName, serviceName=nil )
+        serviceName = gen_serviceName( interfaceName ) if serviceName.nil?
+        gen_identifier( serviceName, TlaElementText::TLA_LABEL_ABORT )
+      end
+
+      def gen_interface_end_label( interfaceName, serviceName=nil )
+        serviceName = gen_serviceName( interfaceName ) if serviceName.nil?
+        gen_identifier( serviceName, TlaElementText::TLA_LABEL_END )
+      end
+
+      ##
+      # Solidity code should check for error
+      def gen_interface_fail_label( interfaceName, serviceName=nil )
+        serviceName = gen_serviceName( interfaceName ) if serviceName.nil?
+        gen_identifier( serviceName, TlaElementText::TLA_LABEL_FAIL )
+      end
+
+      private def gen_serviceName( interfaceName )
+        metatype = :solidity_contract_function
+        gen_specname( metatype, interfaceName)
+      end
+      
+
+      ##
+      # Create +specName+ corresponging +appName+ in +metatype+
+      def gen_specname( metatype, appName )
+
+        sym = :TLA_specname
+        addPartial( sym, "#{spec_name('specname')}" )
+        
+        stla( sym,{
+                :specname => {
+                  :metatype => setMetatype( metatype ),
+                  :appName => appName,
+                }})
+      end
+
+      # @return name (which can be processed by EVAL)
+      def gen_plainname( name )
+
+        sym = :TLA_plainname
+        addPartial( sym, "{|{name}|}" )
+        
+        stla( sym, {
+                :name => name
+              })
+      end
+
+      def gen_constant( constant )
+        gen_plainname( constant )
+      end
+
+      # @return "str"
+      def gen_str( str )
+
+        sym = :TLA_str
+        addPartial( sym, '"{|#EVAL|}str{|/EVAL|}"' )
+        
+        stla( sym, {
+                :str=> str.is_a?( String ) ? gen_plainname(str) : str,
+              })
+      end
+      
+      # @return "str"
+      def gen_parenthesis( str )
+
+        sym = :TLA_parenthesis
+        addPartial( sym, '( {|#EVAL|}str{|/EVAL|} )' )
+        
+        stla( sym, {
+                :str=> str.is_a?( String ) ? gen_plainname(str) : str,
+              })
+      end
+      
+
+      # ------------------------------------------------------------------
+      # Statements
+
+      def gen_stmts( stmts )
+        sym = :TLA_stmts
+        addPartial( sym,
+                   "{|#stmts|}{|#EVAL|}.{|/EVAL|};\n"\
+                   "{|/stmts|}"
+                  )
+        
+        stmts = stla( sym, {
+                # 1 stmt or array of stmts
+                :stmts => stmts[0].is_a?(Symbol) ? s(stmts) : stmts
+                      })
+        
+        # add method to return statements in stmts block for checking
+        # the need to add label after if-statement
+        methodName = :requiresLabelAfterChecker
+        stmts.define_singleton_method( methodName ) do
+          # pass if & else
+          stmts[1][:stmts]
+        end
+
+        stmts        
+        
+      end
+
+      # @param [Integer|String] labelIndex generate unique labels using index
+      #
+      def gen_labeled_stmt( stmt, labelPrefix=false, labelIndex=0 )
+        sym = :TLA_labeled_stmt
+        addPartial( sym, "{|#label|}{|#EVAL|}labelPrefix{|/EVAL|}_{|labelIndex|}: {|/label|}{|#EVAL|}stmt{|/EVAL|}" )        
+        labTla = stla( sym, {
+                :stmt => stmt,
+                :label => labelPrefix ? true : false,
+                :labelPrefix => labelPrefix.is_a?( String)  ? gen_plainname(labelPrefix) : labelPrefix,
+                :labelIndex => labelIndex,
+                       })
+
+        # labelel stmt should be followed by a label - if it is infront
+        # +stmt+, which should be followed by a label or if
+        # label is used within block
+        statementRequiresLabel( labTla, requiresLabelAfter( stmt ))
+        labTla 
+      end
+
+      ##
+      # Generate statement, which may also generate trace output.
+      #
+      # @param [Array] traceArray message/evaluatable mesage
+      # @option traceArray [String|TlaSexp] parameter for print operation
+      #
+      def gen_traced_stmt( stmt, traceArray=false )
+        sym = :TLA_traced_stmt
+        addPartial( sym,
+            <<-EOS.unindent
+            {|#trace|}{|^preferences.tla-trace|}\\* {|/preferences.tla-trace|} {|#EVAL|}trace_print{|/EVAL|};
+            {|^preferences.tla-trace|}
+            {|/preferences.tla-trace|}{|/trace|}{|#EVAL|}stmt{|/EVAL|}
+            EOS
+                  )
+        
+        trace_stmt = stla( sym, {
+                :stmt => stmt,
+                :trace => traceArray ? true : false,
+                :trace_print => gen_print( traceArray ),
+                     })
+
+        # trace_stmt should be followed by a label - if it is infront
+        # +stmt+, which should be followed by a label
+        statementRequiresLabel( trace_stmt ) if requiresLabelAfter( stmt )
+        trace_stmt
+        
+      end
+
+      def gen_print( parameters )
+        sym = :TLA_print
+        addPartial(
+          sym,
+          "print <<"\
+          "{|#parameters|}{|#EVAL|}parameter{|/EVAL|}{|_comma|}{|/parameters|}"\
+          ">>"
+        )
+
+        # String mapper to Sexp && convert whole into to s() -array
+        parameters = gen_str( parameters ) if parameters.is_a?( String )
+        parameters = parameters[0].is_a?( Symbol ) ? s(parameters) : parameters
+        parameters.unshift( TRACE_PREFIX ) 
+
+        stla( sym, {
+                :parameters => parameters.any?  ?
+                                 parameters.map.with_index do |p,i|
+                                   { :_comma => (i+1) == parameters.length ? '' : ',',
+                                     :parameter => p.is_a?(String) ?  gen_str(p) : p
+                                   }
+                                 end :
+                                 false,
+              })
+        
+      end
+
+      def gen_assign( lval, rval )
+        sym = :TLA_assign
+        # tlaStatementTypeRequiresLabel( sym )
+        addPartial( sym, "{|#EVAL|}lval{|/EVAL|} := {|#EVAL|}rval{|/EVAL|}" )
+        stla( sym, {
+                :lval => lval.is_a?( String)  ? gen_plainname(lval) : lval,
+                :rval => rval.is_a?( String)  ? gen_plainname(rval) : rval,                
+              })
+      end
+
+      def gen_return()
+
+        sym = :TLA_return
+        tlaStatementTypeRequiresLabel( sym )        
+        addPartial( sym, "return" )
+        stla( sym, {})
+        
+      end
+
+      def gen_assert( cond, msg )
+
+        sym = :TLA_assert
+        tlaStatementTypeRequiresLabel( sym )        
+        addPartial( sym,
+                    "(* {|#EVAL|}msg{|/EVAL|} *)\n"\
+                    "assert( {|#EVAL|}cond{|/EVAL|} )"
+                  )
+        stla( sym, {
+                :cond => cond.is_a?(String)  ? gen_plainname(cond) : cond,
+                :msg => msg.is_a?(String)  ? gen_str(msg) : msg,
+              })
+      end
+
+      
+
+      
+      def gen_free_text( str )
+        sym = :TLA_free_text
+        addPartial( sym, "{|{text}|}" )
+        # tlaStatementTypeRequiresLabel( sym )
+        stla( sym, {
+                :text => str,
+              })
+      end
+
+      ##
+      # preable at the start of service procedure
+      def gen_check_resume( procedureName )
+
+        sym = :TLA_check_resume
+        addPartial(
+          sym,
+          <<-EOS.unindent
+          (* check if resuming  {|#EVAL|}procedureName{|/EVAL|} *)
+          if ( resume_context # Nil ) {
+              (* prepare stack entry with resume context followed by 
+                 a return to jump to resume location *)
+              stack := <<resume_context.ret_ctx >> \\o stack[self];
+          {|#EVAL|}procedureName{|/EVAL|}_resumed:
+              return;
+          }
+          EOS
+        )
+        tlaStatementTypeRequiresLabel( sym )
+        stla( sym, {
+                :procedureName => procedureName,
+              })
+        
+      end
+
+      def gen_construct_contract( stateVariable, newContract, idPool, id )
+        sym = :TLA_construct_contract
+        addPartial( sym,
+                    <<-EOS.unindent
+                    \\* construct  {|#EVAL|}contracts{|/EVAL|}
+                    create_new_contract( {|#EVAL|}contracts{|/EVAL|}, {|#EVAL|}newContract{|/EVAL|}, {|#EVAL|}idPool{|/EVAL|}, {|#EVAL|}id{|/EVAL|} )
+                    EOS
+                  )
+        stla( sym, {
+                :contracts => stateVariable,
+                :newContract => newContract,
+                :idPool => idPool,
+                :id => id, 
+              })
+        
+      end
+
+
+      def gen_debug_msg( str )
+        sym = :TLA_debug_msg
+        # addPartial( sym, '{|^preferences.tla-debug|}\*{|/preferences.tla-debug|} print << "DEBUG: {|#EVAL|}text{|/EVAL|}" >>' )
+        addPartial( sym, 'print << "DEBUG: {|#EVAL|}text{|/EVAL|}" >>' )        
+        # tlaStatementTypeRequiresLabel( sym )
+        stla( sym, {
+                :text => str.is_a?( String ) ? gen_plainname(str) : str,
+              })
+      end
+
+      def gen_commented( content )
+        sym = :TLA_commented
+        addPartial( sym,
+                    "(*  {|#EVAL|}content{|/EVAL|} *)\n"\
+                    "skip"
+                  )        
+        stla( sym, {
+                :content => content.is_a?( String ) ? gen_plainname(content) : content,
+              })
+      end
+
+
+      def gen_procedure_call( procedure, parameters=s() )
+        sym = :TLA_procedure_call
+        # add label after proc.call
+        tlaStatementTypeRequiresLabel( sym )
+        addPartial(
+          sym,
+          "call {|#EVAL|}procedure{|/EVAL|}( {|#parameters|}{|#EVAL|}parameter{|/EVAL|}{|_comma|}{|/parameters|})"
+        )
+
+        parameters = parameters.is_a?( String ) ? gen_plainname(parameters) : parameters
+        parameters = parameters[0].is_a?( Symbol ) ? s(parameters) : parameters
+        stla( sym, {
+                :procedure => procedure.is_a?( String ) ? gen_plainname(procedure) : procedure,
+                # false or [ {:p, _comma: }] 
+                :parameters => parameters.any?  ?
+                                 parameters.map.with_index do |p,i|
+                                   { :_comma => (i+1) == parameters.length ? '' : ',',
+                                     :parameter => p
+                                   }
+                                 end :
+                                 false,
+              })
+      end
+
+      def gen_and( lhs, rhs )
+        gen_bin_op( '/\\', lhs, rhs )
+      end
+
+      def gen_not( expression )
+        gen_unary_op( '~', expression )
+        # sym = :TLA_not
+        # addPartial(
+        #   sym,
+        #   "~{|#EVAL|}expression{|/EVAL|}"
+        # )
+        # stla( sym, {
+        #         :expression =>expression,
+        #       })
+      end
+
+      def gen_unary_op( op, expr )
+        sym = :TLA_unary_op
+        addPartial(
+          sym, "{|{op}|} {|#EVAL|}expr{|/EVAL|}"
+        )
+
+        stla( sym, {
+                :expr => expr.is_a?( String)  ? gen_plainname(expr) : expr,
+                :op => op,
+              })
+      end
+
+      def gen_bin_op( op, lhs, rhs )
+        sym = :TLA_bin_op
+        addPartial(
+          sym, "{|#EVAL|}lhs{|/EVAL|} {|{op}|} {|#EVAL|}rhs{|/EVAL|}"
+        )
+
+        stla( sym, {
+                :lhs => lhs.is_a?( String)  ? gen_plainname(lhs) : lhs,
+                :op => op,
+                :rhs => rhs.is_a?( String)  ? gen_plainname(rhs) : rhs,                
+              })
+      end
+
+      def gen_either( stmt, stmts )
+        sym = :TLA_either
+        tlaStatementTypeRequiresLabel( sym )
+        addPartial(
+          sym,
+          "either {|#EVAL|}stmt{|/EVAL|}" \
+          "{|#stmts|} or {|#EVAL|}.{|/EVAL|}"\
+          "{|/stmts|}"
+        )
+        
+        stla( sym, {
+                :stmt => stmt,
+                :stmts => stmts[0].is_a?(Symbol) ? s(stmts) : stmts,
+              })
+
+      end
+
+      def gen_if( expression, thenStatement, elseStatement=nil )
+        sym = :TLA_if
+        addPartial(
+          sym,
+          
+          "if ( {|#EVAL|}cond{|/EVAL|} ) {\n"\
+          '      {|#EVAL|}then{|/EVAL|}'\
+          '}{|#else_given|} '\
+          "else {\n"\
+          '      {|#EVAL|}else{|/EVAL|}'\
+          '}{|/else_given|}'
+        )
+
+        
+        stmt_if = stla( sym, {
+                :cond => expression.is_a?(String)  ? gen_plainname(expression) : expression,
+                # :then => gen_stmts( thenStatement.length == 1 ? s(stmt) : thenStatement ),
+                :then => gen_stmts( thenStatement ),
+                :else_given => elseStatement ? true : false,
+                :else => elseStatement ? gen_stmts( elseStatement )  : false,
+                        })
+
+        # add label if then part of else part requires label
+        # statementRequiresLabel( stmt_if ) if requiresLabelAfter( thenStatement) || requiresLabelAfter(elseStatement)
+
+        # add method to return statements in then/else braches for
+        # checking the need to add label after if-statement
+        methodName = :requiresLabelAfterChecker
+        stmt_if.define_singleton_method( methodName ) do
+          # pass if & else
+          stmt_if[1][:then][1][:stmts]  + ( stmt_if[1][:else] ? stmt_if[1][:else][1][:stmts] : [] )
+        end
+        
+        # add method to recurse into then/else block to label
+        # statements within these blocks
+        setLabelBlockStatements( stmt_if, stmt_if[1][:then][1][:stmts] )
+        setLabelBlockStatements( stmt_if, stmt_if[1][:else][1][:stmts], :labelBlockStatementsElse )   if elseStatement
+        
+        stmt_if
+      end
+
+      def gen_IF( expression, thenExpr, elseExpr )
+        sym = :TLA_IF
+        addPartial(
+          sym,
+          
+          "IF {|#EVAL|}cond{|/EVAL|} THEN "\
+          '{|#EVAL|}then{|/EVAL|} '\
+          'ELSE '\
+          '{|#EVAL|}else{|/EVAL|}'
+        )
+
+        stla( sym, {
+                :cond => expression.is_a?( String)  ? gen_plainname(expression) : expression,
+                # :then => gen_stmts( thenExpr.length == 1 ? s(stmt) : thenExpr ),
+                :then => thenExpr.is_a?( String)  ? gen_plainname(thenExpr) : thenExpr,
+                :else => elseExpr.is_a?( String)  ? gen_plainname(elseExpr) : elseExpr,                
+              })
+      end
+
+      def gen_EXCEPT( variable, excepts )
+        sym = :TLA_EXCEPT
+        addPartial(
+          sym,
+          "[ {|#EVAL|}variable{|/EVAL|} "\
+          "EXCEPT "\
+          '{|#excepts|}{|#EVAL|}except{|/EVAL|}{|_comma|}{|/excepts|} '\
+          ']'
+        )
+
+        # if signleton given
+        excepts = excepts[0].is_a?(Symbol) ? s(excepts)  : excepts
+        stla( sym, {
+                :variable => variable.is_a?( String ) ? gen_plainname(variable ) : variable,
+                # :then => gen_stmts( thenExpr.length == 1 ? s(stmt) : thenExpr ),
+                :excepts => excepts.any?  ?
+                              excepts.map.with_index do |p,i|
+                                { :_comma => (i+1) == excepts.length ? '' : ',',
+                                  :except => p
+                                }
+                              end :
+                              false,
+              })
+      end
+
+
+      def gen_skip()
+        sym = :TLA_skip
+        addPartial( sym, "skip" )
+        # tlaStatementTypeRequiresLabel( sym )
+        stla( sym, {})
+      end
+
+      ##
+      # skip statement, but reqeuires label
+      def gen_label()
+        sym = :TLA_label
+        tlaStatementTypeRequiresLabel( sym )
+        addPartial( sym, "skip" )
+        stla( sym, {})
+      end
+      
+      
+
+      # ------------------------------------------------------------------
+      # NOT USED
+
+
+      # Generate element for a lval to set a +return_variable+ of +function_name+
+      def lval_function_return( function_name, return_variable )
+
+        sym = :TLA_lval_function_return 
+        addPartial( sym,
+                               "{|function_name|}_{|return_variable|}" )
+        
+        stla( sym,
+              {
+                :function_name =>function_name,
+                :return_variable =>return_variable,
+              })
+        
+      end
+
+      # TODO: remove
+      def rval_todo_remove
+
+        sym = :TLA_rval_todo_remove
+        addPartial( sym, "{|demo|}" )
+        
+        stla( sym,
+              {
+                :demo =>1,
+              })
+      end
+
+      # Usefull as a placeholder
+      def gen_operator_dummy( metatype, name )
+        gen_operator(
+          gen_specname( metatype, name ),
+          s(),
+          gen_free_text( "TRUE"  ),
+        )
+      end
+
+      def gen_operator_call( operatorName, parameters=[] )
+        sym = :TLA_operator_call
+        addPartial(
+          sym,
+          "{|#EVAL|}operatorName{|/EVAL|}"\
+          "{|#parameters.length|}( {|/parameters.length|}"\
+          "{|#parameters|}{|#EVAL|}parameter{|/EVAL|}{|_comma|}{|/parameters|}"\
+          "{|#parameters.length|} ){|/parameters.length|}"
+        )
+        
+        parameters = parameters[0].is_a?( Symbol ) ? s(parameters) : parameters
+        
+        stla( sym, {
+                :operatorName => operatorName.is_a?( String ) ? gen_plainname(operatorName ) : operatorName,
+                :parameters => parameters.any?  ?
+                                 parameters.map.with_index do |p,i|
+                                   { :_comma => (i+1) == parameters.length ? '' : ',',
+                                     :parameter => p
+                                   }
+                                 end :
+                                 false,
+              })
+        
+      end
+
+      ##
+      # Like operator call, but allways use ()
+      def gen_macro_call( macroName, parameters=[] )
+        sym = :TLA_macro_call
+        addPartial(
+          sym,
+          "{|#EVAL|}macroName{|/EVAL|}("\
+          "{|#parameters|}{|#EVAL|}parameter{|/EVAL|}{|_comma|}{|/parameters|}"\
+          ")"
+        )
+        
+        parameters = parameters[0].is_a?( Symbol ) ? s(parameters) : parameters
+        
+        stla( sym, {
+                :macroName => macroName.is_a?( String ) ? gen_plainname(macroName ) : macroName,
+                :parameters => parameters.any?  ?
+                                 parameters.map.with_index do |p,i|
+                                   { :_comma => (i+1) == parameters.length ? '' : ',',
+                                     :parameter => p
+                                   }
+                                 end :
+                                 false,
+              })
+        
+      end
+
+      
+
+      def gen_goto( label )
+        sym = :TLA_goto
+        tlaStatementTypeRequiresLabel( sym )
+        addPartial( sym, "goto {|#EVAL|}goto{|/EVAL|}" )
+        
+        stla( sym, {
+                :goto => label.is_a?( String) ? gen_plainname(label) : label,
+              })
+        
+      end
+
+
+
+      # 
+      def gen_operator( operatorName, parameters, operatorBody )
+        sym = :TLA_operator
+        addPartial(
+          sym,
+          "{|#EVAL|}operatorName{|/EVAL|}{|#parameters.length|}({|/parameters.length|}{|#parameters|}{|#EVAL|}parameter{|/EVAL|}{|_comma|}{|/parameters|}{|#parameters.length|}){|/parameters.length|}  == {|#EVAL|}operatorBody{|/EVAL|}"
+        )
+        
+        stla( sym,
+              {
+                :operatorName => operatorName,
+                :parameters => parameters.any?  ?
+                                 parameters.map.with_index do |p,i|
+                                   { :_comma => (i+1) == parameters.length ? '' : ',',
+                                     :parameter => p
+                                   }
+                                 end :
+                                 false,
+                :operatorBody => operatorBody
+              })
+      end
+
+      def return_stmt( functionNameDef )
+        sym = :TLA_return_stmt
+        addPartial( sym, "goto #{spec_name('return_from')}_exit; \\* return contract '{| return_from |}'" )
+        
+        stla( sym,
+              {
+                :return_from =>functionNameDef
+              })
+      end
+
+
+      # NOT USED
+      # ------------------------------------------------------------------
+      
+
+
+
+      # ------------------------------------------------------------------
+      # @!group Utitilities to create generate elements
+
+      # create s() with +sym+ (to dispatch correct template) and +hash+ as
+      # template data to render.
+      def stla( sym, hash)
+        sTla = s( sym, hash )
+        
+        # sTla.define_singleton_method( :patch, lambda { |key,val| self[1][key] = val } )
+        # sTla.define_singleton_method( :h ) do
+        #   self[1]
+        # end
+        # sTla.define_singleton_method( :e ) do
+        #   s(self[1])
+        # end
+        sTla
+      end
+
+
+      ###
+      # Add +partialTemplate+ with name +partialSymbol+ to partial
+      # collection.
+      #
+      # NOTICE: as an optimization Mustache template implementation
+      # can use partials, which are initalized using
+      # 'Mustache.templateify' to speed up rendering phase.
+      #
+      # @param [Symbol] partialSymbol identifying partial
+      #
+      # @param [String] partialTemplate to render element SEXP
+      #
+      #
+      def addPartial( partialSymbol, partialTemplate )
+        raise "Should have called #setPartials before actions" if partials.nil?
+        # would like to guarantee that no template refinition takes
+        # place - currently assume that implementation is correct and
+        # just return
+        
+        return if partials.key?(partialSymbol)
+        raise <<-EOS.unindent  if partials_duplicateCheck.key?(partialSymbol) && partials_duplicateCheckpartials[partialSymbol] != partialTemplate 
+        Partial  #{partialSymbol} redefinitition:
+
+        Previous: 
+        #{partials[partialSymbol]}
+
+        New: 
+        #{partialTemplate}
+
+        EOS
+                                               
+        partials[partialSymbol]  = Mustache.templateify(partialTemplate)
+        partials_duplicateCheck[partialSymbol]  = partialTemplate
+      end
+
+      # @!endgroup
+
+      # ------------------------------------------------------------------
+      # @!group common idioms
+
+      ##
+      # Mustache SPEC_NAME lamba call for +metatype+ & +appName+
+      # access unique name for +metatype+/+appName+ combination in
+      # specification code.
+      #
+      # @param [Hash] specNameDef name in tla generate element
+      # @options specNameDef [Symbol] :metatype
+      # @options specNameDef [Symbol] :appName      
+      #
+      # @return [String] string wrapped within SPEC_NAME mustache
+      # lambda call
+      def spec_name( specNameDef )
+        # "{{#SPEC_NAME}}#{specNameDef[:metatype]}.#{specNameDef[:appName]}{{/SPEC_NAME}}"
+        # "{{#SPEC_NAME}}{{#{specNameDef}.metatype}}.{{#{specNameDef}.appName}}{{/SPEC_NAME}}"
+        # "{{#SPEC_NAME}}{{metatype}}.{{appName}}{{/SPEC_NAME}}"
+        "{{#SPEC_NAME}}{|#{specNameDef}.metatype|}.{|#{specNameDef}.appName|}{{/SPEC_NAME}}"        
+      end
+
+      def appName( specNameDef )
+        "{|#{specNameDef}.metatype|}.{|#{specNameDef}.appName|}"        
+      end
+      
+
+      def exit_label( funcNameDef )
+      end
+
+      ##
+      # Pass +metatype+ trough, and ensure that it exists in
+      # +metatypes+
+     
+      def setMetatype( metatype )
+        raise SbuilderEtherumException, <<-EOS unless validMetatypes.key?( metatype )
+        Unknown metatype '#{metatype}' type '#{metatype.class}'
+
+        Known metatypes: #{validMetatypes.keys.join(',')}
+
+        EOS
+                                          
+        metatype                                          
+      end
+      
+
+      # @!endgroup      
+      
+      
+    end # class TlaElementGenerator
+
+  end
+end