tla-sbuilder 0.2.2 → 0.3.4

data/lib/sbuilder/extension_loader_deprecated_step_extensions.rb

@@ -0,0 +1,711 @@
+module Sbuilder
+
+  # To complete runnable code Sbuilder uses setups. A setup
+  # is a sequence of interface operations, and their input parameters.
+  # In addition, a setup may define domain cardinalities, or domain
+  # values.  The tools allows defining multiple setups, each setup
+  # resulting to a complete, runnable TLA+ code, allowing system model
+  # to be run in various environment context
+  #
+  # User defines sequence of interface operations, and their input
+  # parameters using 'step-extension'. A 'step-extension' is an array
+  # with
+  #
+  #    - 'interface' property
+  #
+  #    - 'input' property (or 'inputs' array with elements containing 'input' propperty)
+  #
+  #    - 'bindExact' optional boolean property (default false) controlling,
+  #       how 'input' properties are intepreted. In short 'bindExact' == true results to
+  #       'bindSet', and 'bindExact' == false results to 'bindRule' (see description below)
+  #
+  #
+  # In sbuilder, 'setup' 'step-extension' is used to create
+  # environment context for the setup as follows:
+  #
+  # * sbuilder maps 'step-extension' to a template data array 'steps',
+  #   which can be passed to mustache rendering. Elements in 'steps'
+  #   array define properties 'interface_operation', 'process',
+  #   'bindRule', and 'bindSet'.
+  #
+  # * sbuilder uses template data array 'steps' to render 'RunSteps' -array
+  #   in 'setup.tla'. Array elements have the same properties as
+  #   'steps' array described above.
+  #
+  # * In specification code, 'process' -field of the head element in
+  #   'RunSteps' array chooses the TLA process to execute. The process
+  #   models interface operation of the 'interface' property in
+  #   'step-extension'. Input to the process is controlled either
+  #   using 'bindRule' or 'bindSet' -field on the head element. When
+  #   using 'bindRule', input to the process can be any value in
+  #   process input domain satistfying 'bindRule' condition. When
+  #   using 'bindSet', process input is chosen from the elements in
+  #   the 'bindSet'.
+
+  
+  module ExtensionLoader_Deprecated_Step_Extensions
+
+    @@validStepExtension_required = ["interface" ]
+    @@validStepExtension_allowed = @@validStepExtension_required  + ["input", "bindExact", "inputs"]
+    
+    @@validStepExtension_input = [ "input" ]
+
+    # ------------------------------------------------------------------
+    # extend steps: recurse 'stepExtensionDef' and create a hash, which
+    # can passed to mustache templates
+    
+    def extendStep( stepExtensionDef )
+      @logger.info( "#{__method__} stepExtensionDef=#{stepExtensionDef}" )
+
+      validateProperties( stepExtensionDef, @@validStepExtension_required, @@validStepExtension_allowed )
+
+      # access paramSet for interface being extenedd && assert that it also exists
+      interface = controller.getInterface( stepExtensionDef['interface'] )
+
+      # create new param-set && configure it
+      stepParamSet = controller.createParamSet( Sbuilder::Constants::PARAM_SET_STEPS )
+      stepParamSet.setInterfaceReference( interface )
+      stepParamSet.setBindExact( stepExtensionDef["bindExact"] )      
+
+      # iterate stepParamSet['inputs']/stepParamSet['input'] to create
+      # mustacheTemplateData & add use 'stepParamSet.addInput' add it
+      # to 'stepParamSet'
+      extendStep_Inputs( interface, stepParamSet, stepExtensionDef )
+
+      # pass extension for controller - to delegate to model
+      controller.extendStep( stepParamSet )      
+
+    end
+
+    # ------------------------------------------------------------------
+    # Implementation
+    
+
+    def extendStep_Inputs( interface, stepParamSet, stepExtensionDef )
+
+      raise ExtensionException.new  <<-EOS if stepExtensionDef['input'] && stepExtensionDef['inputs'] 
+      Property 'input' cannot be defined together with 'inputs' in #{stepExtensionDef.to_yaml}
+
+      Use 
+
+        inputs:
+           - input: 
+                ...
+           - input: 
+                ...
+
+      or for a single input
+
+        input:
+           ....
+      EOS
+
+      raise ExtensionException.new  <<-EOS if stepExtensionDef['inputs'] && stepExtensionDef['bindExact'] != true
+      Property 'inputs' cannot be defined unless 'bindExact' true.
+
+      Error in in #{stepExtensionDef.to_yaml}
+
+      EOS
+      
+
+      # process either 'inputs' or 'input'
+      stepExtensionDefInputs = stepExtensionDef['inputs'] ? stepExtensionDef['inputs'] : [ { 'input' => stepExtensionDef['input'] } ]
+
+      # loop
+      stepExtensionDefInputs.each do |stepExtensionDefInput|
+
+        # single case: create 'mustacheTemplateData' and add it to
+        # 'stepParamSet'
+        begin
+          
+          validateProperties( stepExtensionDefInput, @@validStepExtension_input  )
+          
+          mustacheTemplateData = extendStep_Input( interface, stepParamSet, stepExtensionDefInput['input'] )
+          @logger.debug "#{__method__}, mustacheTemplateData=#{mustacheTemplateData.to_yaml}"
+          stepParamSet.addInput( mustacheTemplateData )
+
+        rescue ExtensionException => ee
+          msg = "Error #{ee} caused by #{ee.backtrace.join("\n")} when extending interface '#{stepExtensionDef['interface']}'\n\n"
+          @logger.error( "#{__method__} #{msg}" )
+          raise ExtensionException.new( msg )
+        end
+        
+      end #  iterate
+
+    end # def extendStep_Inputs( interface, stepParamSet, stepExtensionDef )
+
+
+    # expand one input to a mustache template
+    def extendStep_Input( interface, stepParamSet, stepExtensionDefInputs )
+
+        # convert input paramters for the interface to datastructure, which
+        # can passed to template rendering
+        mustacheTemplateData = extendStepInputs( interface, stepExtensionDefInputs )
+
+        # add missing sub-documents in 'stepExtensionDef'
+        expandedStepExtensionDef = expandStepInputForDefaults(  interface, stepExtensionDefInputs )
+        
+        # add _default values for parameters not defined
+        # NB: expandedStepExtensionDef = stepExtensionDef['input']
+        mustacheTemplateData = extendStepDefaults( interface, expandedStepExtensionDef, mustacheTemplateData )
+
+        # assign unique number to hash element in 'mustacheTemplateData'
+        mustacheTemplateData = extendNumbering( mustacheTemplateData )        
+
+        # added to stepParameterSet
+        return mustacheTemplateData
+      
+    end
+    
+
+    # 'expandedInputs' includes all 'interaface' fields (recurisively)
+    def expandStepInputForDefaults( interface, stepExtensionInputs )
+
+      # make a deeeep copy
+      # puts( "expandStepInputForDefaults: stepExtensionInputs=#{stepExtensionInputs.to_yaml}\n\n" )
+      expandedInputs  =  Marshal.load( Marshal.dump( stepExtensionInputs ))
+      
+      # recurse 'interface' and ensure that 'expandedInputs' structure
+      # corresponds 'interface' structure
+      expandStepInputForDefaultsRecursion( interface, expandedInputs )
+
+      # puts( "expandStepInputForDefaults: expandedInputs=#{expandedInputs.to_yaml}\n\n" )      
+      return expandedInputs
+        
+    end
+
+    # recurs 'paramSet' in synch with 'stepExtensionDef': for each
+    # non-leaf paramter (i.e. a a parameter referencing to an other
+    # paramset) ensure that 'stepExtensionDef' also this entry
+    def expandStepInputForDefaultsRecursion( paramSet, stepExtensionInput )
+
+      @logger.debug( "#{__method__} paramSet=#{paramSet}, stepExtensionInput=#{stepExtensionInput}, stepExtensionInput.nil?=#{stepExtensionInput.nil?}" )
+
+      # when no 'input' on 'step-extension'
+      stepExtensionInput = {}  if stepExtensionInput.nil?
+      
+      paramSet.parameters.each do |parameter|
+        if parameter.isReference && stepExtensionInput.is_a?( Hash ) then
+          # add empty input parameter (if not defined) for records (ie. Hashe).
+          # rows are not expanded (we do not know many we should add)
+          # stepExtensionInput[parameter.name] = initRecord( parameter.name ) unless stepExtensionInput.has_key?( parameter.name )
+          stepExtensionInput[parameter.name] = {} unless stepExtensionInput.has_key?( parameter.name )
+          # recurse referenced 'paramSet' together with 'stepExtensionDef'
+          expandStepInputForDefaultsRecursion( parameter.getResolvedReference, stepExtensionInput[parameter.name] )
+        end
+      end
+    end
+
+    
+
+    # ------------------------------------------------------------------
+    # recurse 'stepExtensionInputs' and use it to set default values
+    # in 'mustacheTemplateData' structure.
+
+    def extendStepDefaults( interface, stepExtensionInputs, mustacheTemplateData )
+      # puts "extendStepDefaults - starting"
+      # recrurse 'stepExtensionInputs' and yield 'rows' && 'records'
+      recurseStepDefaults( stepExtensionInputs ) do |type, keys, indexes, stepExtensionInput, defaultValues|
+        # puts "type=#{type}, keys=#{keys}, indexes=#{indexes}, stepExtensionInput=#{stepExtensionInput}, defaultValues=#{defaultValues}"
+
+        # configuration in model
+        interfaceParameters = locateParameter( interface, keys )
+
+        # what we have expanded so far - using 'stepExtensionInputs'
+        templateData = locateTemplateData( mustacheTemplateData, keys, indexes )
+
+        # default value is on the top of the stack
+        # defaultValue = defaultValues.last 
+        # defaultValue is the last non-nil value on stack 'defaultValues'
+        defaultValue = defaultValues.reverse.find { |v| !v.nil? } 
+
+        next unless defaultValue
+
+        # create an entry in 'mustacheTemplateData' if path 'keys'/'indexes' no configuration
+        # in 'step-extension' 'input'
+        templateData = addTemplateData( mustacheTemplateData, keys, indexes ) unless templateData
+        expandDefaults( interfaceParameters, defaultValue, templateData )          
+        
+        # case type
+        # when "row"
+        #   next unless defaultValue
+        #   # access data row 'index'
+        #   index = indexes.last
+        #   # expandDefaults( interfaceParameters, defaultValue, templateData['rows'][index] )
+        #   puts "row-expansion templateData=#{templateData}"
+        #   expandDefaults( interfaceParameters, defaultValue, templateData )          
+        # when "record"
+        #   # possibly no default value defined
+        #   next unless defaultValue
+        #   expandDefaults( interfaceParameters, defaultValue, templateData )
+        # else
+        #   # should not happen
+        #   raise "Unknown type #{type}"
+        # end
+      end
+      # empty is returnet as boolean false
+      mustacheTemplateData  = false if mustacheTemplateData  == {}
+      
+      mustacheTemplateData      
+    end # def extendStepDefaults
+
+    # recurse 'stepExtensionInputs' and yield
+    # - record|row, [keys], parameterDef
+    def recurseStepDefaults( stepExtensionInputs, keys=[], indexes=[], defaultValues=nil, &block )
+      # puts "recurseStepDefaults(enter) stepExtensionInputs=#{stepExtensionInputs}" 
+      return unless stepExtensionInputs
+      # init defaultValues
+      defaultValues = [ stepExtensionInputs["_default"] ] unless defaultValues
+      if !keys.any? then
+        # puts "recurseStepDefaults(init) #{stepExtensionInputs}"
+        yield "record", keys, indexes, stepExtensionInputs, defaultValues
+      end
+      stepExtensionInputs.each do |parameterName, parameterDef|
+        if parameterDef.is_a?( Array ) then
+          parameterDef.each.with_index do |parameterDefRow,index|
+            defaultValues.push( parameterDefRow["_default"] )
+            # puts "recurseStepDefaults:(array) resolved-defaultValues=#{defaultValues} index=#{index},  for parameterDefRow=#{parameterDefRow}"
+            yield "row", keys + [parameterName], indexes + [index], parameterDefRow, defaultValues
+            recurseStepDefaults( parameterDefRow, keys + [parameterName], indexes + [index], defaultValues, &block)
+            defaultValues.pop            
+          end
+        elsif parameterDef.is_a?( Hash ) then
+          defaultValues.push( parameterDef["_default"] )
+          # puts "recurseStepDefaults:(hash): resolved-defaultValues=#{defaultValues} keys=#{keys},  for parameterDef=#{parameterDef}"          
+          yield "record", keys + [parameterName], indexes + [nil], parameterDef, defaultValues
+          recurseStepDefaults( parameterDef, keys + [parameterName], indexes + [nil], defaultValues, &block)
+          defaultValues.pop
+        else
+          # puts "recurseStepDefaults:(else): resolved-defaultValues=#{defaultValues} keys=#{keys},  for parameterDef=#{parameterDef}"                    
+          # leaf entry
+        end
+
+      end
+
+    end # def recurseStepDefaults
+    
+
+    # add expanded parameters to 'templateData'
+    def expandDefaults( interfaceParameters, defaultValue, templateData )
+      
+      # puts "\nexpandDefaults defaultValue=#{defaultValue} on '#{templateData}' missing from #{interfaceParameters}"
+      # return unless templateData
+
+      # array of 'parameter_name' fields found on templateData
+      definedParameters = templateData && templateData['columns'] ?  templateData['columns'].map { |column| column[:parameter_name] } : []
+      
+      # select parameters, which are not defined on 'templateData'
+      # (i.e. missing from 'definedParameters') append new entries in
+      # 'templateData' with 'defaultValue' expanded
+      
+      parametersToBe( interfaceParameters ).select do |param|
+
+        # puts "expandDefaults param=#{param} of #{param.class}"
+        # select for expsion
+        # if NOT already defined i.e. NOT in definedParameters
+        # if CARDNIALITY defined (ie. paramter_dom object)
+        
+        !definedParameters.include?( param[:parameter_name] ) && !param[:cardinality].nil?
+        
+      end.each do |param|
+        # one more added - modify comm
+        templateData['columns'].last["_comma"] = ',' if templateData && templateData['columns'] && templateData['columns'].length > 0
+
+        # puts  "added fied #{param[:parameter_name]}"
+        # create default entry
+        expadedElement = {
+          :parameter_name => param[:parameter_name],
+          "_comma" => '',
+          "rows" => false,
+          "columns" => false,
+        }
+        
+        expadedElement = expandDefaultValue( expadedElement, defaultValue, param )
+        # ensure that 'columns' array exists (espeically case when
+        # only _default defined in step extension)
+        templateData['columns'] = [] unless templateData && templateData['columns']
+        templateData['columns'] << expadedElement
+        
+      end # apped new entries to 'templateData'
+
+      templateData
+
+    end
+
+    # retrurn array of hashes(:parameter_name, :cardinality, :domain_prefix)
+    # on an interface parameters
+    def parametersToBe( interfaceParameters )
+      @logger.debug( "#{__method__} interfaceParameters=#{interfaceParameters}" )
+      parameters = interfaceParameters.parameters.map do |parameter|
+        # puts "parameter=#{parameter}"
+        {
+          :parameter_name => parameter.name,
+          :cardinality => parameter.respond_to?( :resolvedDomain) ? parameter.resolvedDomain.cardinality : nil,
+          # :domain_prefix => parameter.respond_to?( :resolvedDomain) ? parameter.resolvedDomain.domain_prefix : nil,
+          :domain_name => parameter.respond_to?( :resolvedDomain) ? parameter.resolvedDomain.domain_name : nil,
+        }
+
+      end
+      return parameters
+    end
+    
+
+    # update :domain_value (whewn 'defaultValue' is String), or :domain_element= #{param[:domain_prefix]}#{:domain_prefix}" otherwise
+    def expandDefaultValue( expadedElement, defaultValue, param )
+
+      # Case 'String'
+      return expadedElement.merge( { :domain_value => defaultValue, :domain_element => false }) if defaultValue.is_a?( String )
+
+      # Case 'Interger'
+      # puts "expandDefaultValue param=#{param}"
+      if defaultValue.is_a?( Integer ) then
+        raise ExtensionException.new  <<-EOS if  defaultValue > param[:cardinality]
+          Cardinality of the default exceeds the cardinality of the parameter domain
+            
+             cardinality of default : #{defaultValue}
+             cardinality on domain  : #{param[:cardinality]}
+             name of parameter      : #{param[:parameter_name]}
+             domain name            : #{param[:domain_name]}
+
+        EOS
+        return  expadedElement.merge( { :domain_element => getDomainElement( param, defaultValue ), :domain_value => false } )
+      end
+
+      # else - unknown value
+      raise raise ExtensionException.new <<-EOS
+           Unknown type #{defaultValue.class} for default #{defaultValue} value encountered.
+
+                  Exteding paramter #{param}
+          EOS
+    end
+    
+    def getDomainElement2( extededParameter, domainElement )
+      # puts( "extededParameter=#{extededParameter}, domainElement=#{domainElement}" )
+      return extededParameter.resolvedDomain.domain_entry( domainElement )
+      # "#{extededParameter.resolvedDomain.name}_#{domainElement}"
+    end
+    def getDomainElement( param, defaultValue )
+      # ret = "#{param[:domain_prefix]}#{defaultValue}"
+      ret = model.getDomain(param[:domain_name]).domain_entry( defaultValue )
+      # puts( "getDomainElement: param=#{param}, defaultValue=#{defaultValue} --> #{ret}" )
+      return ret
+
+    end
+
+    # ------------------------------------------------------------------
+    # number elements
+
+    # assign '_first' element for hash within 'mustacheTemplateData'
+    #
+    # @param mustacheTemplateData [Hash]
+    # @return [Hash] 'mustacheTemplateData' with record elements numbered
+    def extendNumbering( mustacheTemplateData )
+
+      recurseHash( mustacheTemplateData ) do |h,k,v,i|
+        v["_index"] = i
+      end
+      return mustacheTemplateData
+    end
+
+    # recurse hash, and yield 'hash', 'key', 'value', 'index' for each
+    # entry within the hash structure, which is_a?(Hash).
+    
+    def recurseHash( hash, &block )
+
+      hash && hash.each_with_index do |(k,v),index|
+        if  v.is_a?( Hash )  then
+          yield  hash, k, v, index
+          recurseHash( v, &block)
+        elsif v.is_a?( Array )  then
+          v.each_with_index do |array_element,i|
+            if array_element.is_a?(Hash)
+              yield  hash, k, array_element, i 
+              recurseHash( array_element, &block)
+            end
+          end
+        end
+      end
+    end
+
+    # ------------------------------------------------------------------
+    # recurse 'stepExtensionInputs' configuration and create a hash
+    # structure, which can be passed to mustache template
+    
+    def extendStepInputs( interface, stepExtensionInputs )
+      @logger.debug( "#{__method__} stepExtensionInputs=#{stepExtensionInputs}" )
+
+      # recursion uses this as a stack
+      subDocumentStack = []
+      subDocumentStack.push( {} )
+
+
+      stepExtensionInputs && recurseStepInputs(  stepExtensionInputs ) do |act,keys,domainElement,row|
+        # puts "#{act}, keys=#{keys},domainElement=#{domainElement}, #{row}"
+        
+        # uses path  [keys] in 'interface' to locate parameter to extend
+        extededParameter = locateParameter( interface, keys )
+        parameterName = keys.last
+        next if parameterName[0] == "_"
+
+        case act
+        when "="
+          @logger.debug( "#{__method__} extededParameter=#{extededParameter.name}, extededParameter.resolvedDomain=#{extededParameter.resolvedDomain}" )
+           input = {
+            :parameter_name => parameterName,
+            :domain_element => getDomainElement2(extededParameter, domainElement),
+            "rows" => false,
+            "columns" => false,
+            "_comma" => ','
+          }
+          # create new parameter && add it to the paramSet
+          raise ExtensionException.new  <<-EOS if domainElement.is_a?( Integer ) && extededParameter.resolvedDomain.cardinality < domainElement 
+          The cardinality on step exceeds the cardinality of the parameter domain
+             
+              Name of parameter  : #{extededParameter.name}
+              Name of parameter domain  : #{extededParameter.resolvedDomain.name}
+              Cardinality of the parameter domain : #{extededParameter.resolvedDomain.cardinality}
+              Cardinality defined: #{domainElement}
+
+          EOS
+
+          subDocumentStack.last["columns"] = [] unless subDocumentStack.last["columns"]          
+          subDocumentStack.last["columns"] << input
+        when "["
+          input = initRecord( parameterName )
+          # {
+          #   :parameter_name => parameterName,
+          #   "rows" => false,
+          #   "columns" => false,
+          # }
+          subDocumentStack.last["columns"] = [] unless subDocumentStack.last["columns"]          
+          subDocumentStack.last["columns"] << input
+          subDocumentStack.push( input )
+        when "]"
+          # end of sub-record
+          input = subDocumentStack.pop
+          # last element has no comma
+          input['columns'].last["_comma"] = '' if input['columns']
+        when "<<"
+          if row == 0 then
+            # start of array processing = start of row
+            input = initRecord( parameterName )
+            # {
+            #   :parameter_name => parameterName,
+            #   "rows" => false,
+            #   "columns" => false,
+            # }
+            subDocumentStack.push( addColumn( subDocumentStack.last, input ))
+                                                       
+            # subDocumentStack.last["columns"] = [] unless subDocumentStack.last["columns"]
+            # subDocumentStack.last["columns"] << input
+            # subDocumentStack.push( input )          
+          else
+            # start a new row in an array
+            input = {
+              "rows" => false,
+              "columns" => false,
+              "_comma" => ",",              
+            }
+            subDocumentStack.push( input )                      
+          end
+          
+        when ">>"
+          if row == 0 then
+            # end of array 
+            input  = subDocumentStack.pop
+            input['rows'].last["_comma"] = '' if input['rows']                        
+            input['columns'].last["_comma"] = '' if input['columns']            
+
+          else
+            input = subDocumentStack.pop
+            input['rows'].last["_comma"] = '' if input['rows']                        
+            input['columns'].last["_comma"] = '' if input['columns']            
+            # puts "subDocumentStack=#{subDocumentStack}"
+            subDocumentStack.last["rows"] = [] unless subDocumentStack.last["rows"]
+            subDocumentStack.last["rows"] << input
+          end
+        else
+          raise "Unknown act #{act}"
+        end
+      end
+
+      raise "subDocumentStack should have been empty #{subDocumentStack}" unless subDocumentStack.length == 1
+      ret = subDocumentStack.first
+
+      # last element has no _comma always 
+      ret['columns'].last["_comma"] = '' if ret['columns']
+  
+      @logger.info( "#{__method__} return=#{ret}" )
+      return ret
+      
+    end # def extendStepInputs( interface, stepExtensionInputs )
+
+    # Recurse 'stepExtensionInputs' (i.e. hash under key 'step-extension' ).
+    # During recursion yield:
+    # =   : reference parameter, domainElement
+    # [   : starts hash
+    # ]   : end hash
+    # <<  : array
+    # >>  : end array
+    def recurseStepInputs( stepExtensionInputs, keys=[], row=0, &block )
+      stepExtensionInputs.each do |parameterName, parameterDef|
+        begin 
+          if parameterDef.is_a?( Array ) then
+            yield "<<", keys + [parameterName], nil, 0
+            parameterDef.each.with_index do |parameterDefRow,index|
+              yield "<<", keys + [parameterName], nil, index+1
+              recurseStepInputs( parameterDefRow, keys + [parameterName], index+1, &block )
+              yield ">>", keys + [parameterName], nil, index+1
+            end
+            yield ">>", keys + [parameterName], nil, 0
+            
+          elsif parameterDef.is_a?( Hash ) then
+            yield "[", keys + [parameterName], nil, row          
+            recurseStepInputs( parameterDef, keys + [parameterName], row, &block  )
+            yield "]", keys + [parameterName], nil, row          
+          else
+            # do not process "meta fields" e.g '_default'
+            yield "=", keys + [parameterName], parameterDef, row
+          end
+        rescue SbuilderException => e
+          msg = <<-EOS.gsub( /^\s*/, '' )
+          Error:
+
+          #{e.message}  
+
+
+          when processing parameter #{parameterName} with definition:
+
+          #{parameterDef.to_yaml}
+
+          EOS
+          @logger.error( "#{__method__} #{msg}" )
+          raise Sbuilder::LoaderException.new, msg, e.backtrace
+        end
+      end
+    end # recurseStepInputs
+    
+
+    # uses path  [keys] in 'interface' to locate parameter
+    def locateParameter( interface, keys )
+      extededParameter = interface
+      if keys.any?
+        extededParameter = keys.inject(interface) { |p,key|
+          # _default paramtes not real parameters
+          next if key == "_default"
+          p = p.locateParameter( key )
+          # resolve in model context - possible for paramter_ref
+          # p = p.getResolvedReference( controller.model ) if p.respond_to?( :getResolvedReference )
+          p = p.getResolvedReference if p.respond_to?( :getResolvedReference )          
+          p
+        }
+        @logger.debug( "#{__method__} keys #{keys}->extededParameter=#{extededParameter}" )
+      end
+      return extededParameter
+    end
+
+    # ensure that templateData element in ['keys'] and ['indexes']
+    # exists in 'mustacheTemplateData'.
+    def addTemplateData( mustacheTemplateData, keys, indexes )
+      
+      templateData = mustacheTemplateData
+      prev = templateData
+      keys.each_with_index do |key,i|
+        index = indexes[i]
+        # puts "addTemplateData:  key=#{key}, #{i}, index #{index}"
+        templateData = templateData['columns'].select{ |column| column[:parameter_name] == key }.first
+        if templateData.nil? then
+          templateData = initRecord( key )
+          addColumn( prev, templateData )
+          # puts "addTemplateData: added #{templateData} for key #{key} --> #{mustacheTemplateData}"
+        else
+          # puts "addTemplateData: exists #{templateData} for key #{key}"
+        end
+        
+        prev = templateData
+        
+        # # puts "data1=#{data}"
+        # if !index.nil? then
+        #   templateData = templateData['rows'][index]
+        #   # puts "data2=#{data}"
+        # end
+      end # iterate
+
+      return templateData
+    end
+    
+
+    # uses path in  [keys] and ['indexes'] to locate data 'mustacheTemplateData'.
+    def locateTemplateData( mustacheTemplateData, keys, indexes )
+      ret = mustacheTemplateData
+      i = 0
+      if keys.any?
+        ret = keys.inject(ret) { |data,key|
+          index = indexes[i]
+          i += 1
+          # puts "\n\nindex=#{index} of #{indexes}, i=#{i}, key=#{key} on '#{data}'"
+          break unless data
+          data = data['columns'].select{ |column| column[:parameter_name] == key }.first
+          # puts "data1=#{data}"
+          if !index.nil? then
+            data = data['rows'][index]
+            # puts "data2=#{data}"
+          end
+          
+          # if index.nil? then
+          # else
+          #   data = data['rows'][index]['columns'].select{ |column| column[:parameter_name] == key }.first            
+          # end
+          data
+        }
+      end
+      return ret
+    end
+
+    # ------------------------------------------------------------------
+    # Build a hash structure, which can be passed to mustache template
+    
+    # create record entry
+    private
+    def initRecord( parameterName )
+      {
+            :parameter_name => parameterName,
+            "rows" => false,
+            "columns" => false,
+            "_comma" => ",",     # assume that comma get removed if -needed
+      }
+    end
+
+    def addColumn( columns, column )
+      # subDocumentStack.last["columns"] = [] unless subDocumentStack.last["columns"]
+      # subDocumentStack.last["columns"] << input
+      # subDocumentStack.push( input )          
+      columns['columns'] = [] unless columns['columns']
+      
+      # la
+      columns['columns'].last["_comma"] = ',' if columns['columns'].length > 0
+
+      # no comma here
+      column["_comma"] = ''
+
+      columns['columns'] << column
+      return column
+    end
+
+    # # validate 'defintionHash' all 'required'/only 'allowed' props set
+    private def validateProperties( defintionHash, required, allowed=nil )
+
+      allowed = required unless allowed
+      
+      missingProps = required - defintionHash.keys
+      raise ExtensionException.new "Missing properties #{missingProps} in #{defintionHash} - required #{required}" if missingProps.any?
+
+      invalidProps = defintionHash.keys - allowed 
+      raise ExtensionException.new "Unknown properties #{invalidProps} in #{defintionHash} - allowed #{allowed}" if invalidProps.any?
+
+    end
+
+  end
+  
+end
+