tla-sbuilder 0.2.2 → 0.3.4

data/lib/sbuilder/controller_utils.rb

@@ -0,0 +1,122 @@
+module Sbuilder
+
+  ##
+  # collect method, which all
+  module ControllerUtils
+
+
+    def dispatchExtendDomain( domainDef )
+      Utils::Validate.validateProperties( domainDef, Constants::VALIDATION[:domain_extension][:required], Constants::VALIDATION[:domain_extension][:allowed] )
+      Utils::Validate.oneOf( domainDef, Constants::VALIDATION[:domain_extension][:one_of] )
+      
+      if !domainDef['cardinality'].nil? then
+        extendDomainWithCardinality(  domainDef )
+      elsif !domainDef['values'].nil?
+        extendDomainWithValues(  domainDef )
+      elsif !domainDef['range'].nil?
+        extendDomainRange(  domainDef )
+      elsif !domainDef['type'].nil?
+        extendDomainWithType(  domainDef )
+      else
+        raise ExtensionException,  "Invalid domain definition #{domainDef}"
+      end
+    end
+
+    ##
+    # Extend domain with (integer) range
+    #
+    # @param [Hash] 
+    # @option domainDef [String] range array lenght 2 start-stop
+    #
+    def extendDomainRange(  domainDef )
+      # must be array with length of two, with first element less or equal
+      raise ExtensionException,  "Invalid domain range defintion" unless domainDef['range'] &&
+                                                                         domainDef['range'].is_a?( Array ) &&
+                                                                         domainDef['range'].length == 2 &&
+                                                                         domainDef['range'][0]  <= domainDef['range'][1]
+
+      domain = factory.createDomain( Sbuilder::Constants::TYPE_RANGE_DOMAIN )
+      domain.setName( domainDef['domain'] )
+      domain.setRange( domainDef['range'][0], domainDef['range'][1] )
+
+      # pass to model via controller      
+      extendDomain( domain )
+      
+    end
+
+    
+
+    def extendDomainWithType( domainDef )
+      # @logger.info( "#{__method__}: domainDef=#{domainDef}" )
+      Utils::Validate.validateProperties(
+        domainDef,
+        Constants::VALIDATION[:domain_extension][:type_required], Constants::VALIDATION[:domain_extension][:type_allowed]
+      )
+
+      # create & configure
+      domain = factory.createDomain( Sbuilder::Constants::TYPE_DOMAIN_TYPE )
+      domain.setName( domainDef['domain'] )
+      domain.setType( domainDef['type'] )      
+
+      # pass to model via controller      
+      extendDomain( domain )
+    end
+
+    
+
+    def extendDomainWithCardinality(  domainDef )
+      # @logger.info( "#{__method__} domainDef=#{domainDef}" )
+      # validateProperties( domainDef, @@extensionDoaminProperties )
+      Utils::Validate.validateProperties(
+        domainDef,
+        Constants::VALIDATION[:domain_extension][:cardinality_required], Constants::VALIDATION[:domain_extension][:cardinality_allowed]
+      )
+
+      # create & configure
+      domain = factory.createDomain( Sbuilder::Constants::TYPE_CARDINALITY_DOMAIN )
+      domain.setName( domainDef['domain'] )
+      domain.setCardinality( domainDef['cardinality'] )      
+
+      # pass to model via controller      
+      extendDomain( domain )
+    end
+
+    #
+    # @param [String] domainName
+    # @param [String:Array] arrOfDomainValues
+    #
+    # Creates 'domainDef' and delegates to 'extendDomainWithValues'
+    #
+    def setApplicationDomainValues( domainName, arrOfDomainValues )
+      domainDef = {
+        'domain' => domainName,
+        'values' => arrOfDomainValues
+      }
+      # add to model
+      addApplicationDomainValue( domainDef )
+    end
+
+    def extendDomainWithValues(  domainDef )
+      # @logger.info( "#{__method__} domainDef=#{domainDef}" )
+      # validateProperties( domainDef, @@extensionValuesProperties )
+      Utils::Validate.validateProperties(
+        domainDef,
+        Constants::VALIDATION[:domain_extension][:value_required], Constants::VALIDATION[:domain_extension][:value_allowed]
+      )
+
+      # create & configure
+      domain = factory.createDomain( Sbuilder::Constants::TYPE_VALUE_DOMAIN )
+      domain.setName( domainDef['domain'] )
+      domainDef['values'].each { |value| domain.addValue( value  ) }
+
+      # pass to model via controller
+      extendDomain( domain )      
+      
+    end
+
+    
+    
+  end
+
+  
+end

data/lib/sbuilder/default-sbuilder.yaml

@@ -7,6 +7,15 @@ generate:
        # ----------------------------------------
        # Default model.tla.
        # 
+       # Define initial symbol table metatype entries & reserve
+       # following 'namaspace' prefixies:
+       #
+       # - domains --> d_
+       # - definitions -> t_ (types)
+       # - interface_types -> it_
+       # - processes -> p_
+       # - infra_services -> i_
+       # 
        #  Override template extension points
        # - extend_const.tla
        # - extend_state.tla
@@ -33,7 +42,6 @@ generate:
                template: tla/const_def.mustache
                modelData: none
                
-               # --------------------
                # extension point: extend_const.tla
              - desc: Extension point for constants
                template: extend/extend_const.mustache
@@ -42,6 +50,7 @@ generate:
              - desc: Domain definitions
                template: domains.mustache
                modelData: domains
+               symbols: 'lambda{ |d| [ Sbuilder::Constants::META_MODEL_DOMAINS, d[:domain_name], "d_#{d[:domain_name]}" ] }'
 
              - desc: Environment operators 
                template: tla/operator_run.mustache
@@ -54,10 +63,16 @@ generate:
              - desc: Data type definitions
                template: definition_types.mustache
                modelData: definitions
+               symbols: 'lambda{ |d| [ Sbuilder::Constants::META_MODEL_DEFINITIONS, d[:definition_name],  "t_#{d[:definition_name]}", ] }'
 
              - desc: Interface types 
                template: interface_types.mustache
-               modelData: interface_types  # = interfaces (not filtered)
+               modelData: interfaces      # = all interfaces (not filtered)
+               # model data 'interfaces' is mapped to 'interface_types'
+               symbols:
+                 - 'lambda{ |iface| [Constants::META_MODEL_INTERFACE_TYPES,  iface[:interface_operation], "#{Constants::META_MODEL.select{ |e| e[:name] == Constants::META_MODEL_INTERFACE_TYPES}.first[:prefix]}#{iface[:interface_name]}", ] }'
+                 - 'lambda{ |iface| [Constants::META_MODEL_INTERFACE_RESPONSE_TYPES,iface[:interface_operation], "#{Constants::META_MODEL.select{ |e| e[:name] == Constants::META_MODEL_INTERFACE_RESPONSE_TYPES}.first[:prefix]}#{iface[:interface_name]}",  ] }'                 
+
 
              - desc: Start of plc block
                template: tla/plc_header.mustache
@@ -72,16 +87,15 @@ generate:
                modelData: none
                
 
-               # --------------------
                # extension point: extend_state.tla
                
              - desc: Extension point for specification state
                template: extend/extend_state.mustache
                modelData: none
 
-             - desc: Specification state
-               template: state_variables.mustache
-               modelData: variables
+             # - desc: Specification state
+             #   template: state_variables.mustache
+             #   modelData: variables
 
              - desc: Start of plc define block
                template: tla/plc_define_header.mustache
@@ -100,10 +114,8 @@ generate:
                template: tla/operators-infrastructure-service.mustache
                modelData: none
                
-               # --------------------
                # extension point: extend_operations.tla
-
-             - desc: Extension point for operations 
+             - desc: Extension point for operations
                template: extend/extend_operations.mustache
                modelData: none
 
@@ -119,9 +131,7 @@ generate:
                template: tla/macro-infrastructure-service.mustache
                modelData: none
 
-               # --------------------
                # extension point: extend_macros.tla
-               
              - desc: Extension poin to add macros
                template: extend/extend_macros.mustache
                modelData: none
@@ -130,16 +140,19 @@ generate:
                template: interface_stubs_dummy.mustache
                modelData: none
                
-               # --------------------
                # extension point: extend_implementation.tla
-               
              - desc: Extension point for implementation
                template: extend/extend_implementation.mustache
                modelData: none
 
+               # create entries for two symbol table meta-types,
+               # META_MODEL_SERVICE_IMPLEMENTATION meta-types created only if it is defined
              - desc: Process interfaces
                template: interface_processes.mustache
                modelData: interfaces
+               symbols:
+                 - 'lambda{ |iface| [ Sbuilder::Constants::META_MODEL_PROCESSES, iface[:interface_operation],  "p_#{iface[:interface_name]}",  ] }'
+                 - 'lambda{ |iface| [ Sbuilder::Constants::META_MODEL_SERVICE_IMPLEMENTATION, iface[:interface_operation], iface[:implementation], ] if iface[:implementation] }'                 
 
              - desc: Environment model 'Tail' process
                template: tla/plc_tail.mustache
@@ -153,30 +166,20 @@ generate:
                template: tla/plc_translation.mustache
                modelData: none
 
-             - desc: Type constraint in specification
-               template: state_type_invariant.mustache
-               modelData: variables
+             # - desc: Type constraint in specification
+             #   template: state_type_invariant.mustache
+             #   modelData: variables
                
-               # --------------------
-               # extension point: extend_type_invariant.tla
-
-               # - desc: Extension point for  type invariants
-               #   template: extend/extend_type_invariant.tla
-               #   modelData: none
-
              - desc: Validate types for infrastructure service return values
                template: state_type_invariant-infrastructure-service.mustache
                modelData: infrastructureServices
-               
+               symbols: 'lambda{ |iface| [ Sbuilder::Constants::META_MODEL_INFRA_SERVICES, iface[:interface_operation], "i_#{iface[:interface_name]}", ] }'
 
-               # --------------------
                # extension point: extend_invariant.tla
-
              - desc: Extension point for specification invariants
                template: extend/extend_invariant.mustache
                modelData: none
 
-               # --------------------
                # extension point: extend_assumptions.tla
              - desc: Extension point for assumptions
                template: extend/extend_assumptions.mustache
@@ -231,19 +234,6 @@ generate:
                modelData: none
 
 
-               # --------------------
-               # extension point: extend_type_invariant.cfg
-               # - desc: Extesion pointo to activate type constraints
-               #   template: extend/extend_type_invariant.cfg
-               #   modelData: none
-
-               # --------------------
-               # extension point: extend_invariant.cfg
-               
-             - desc: Extension point to activate specification invariants - DEPRECATED
-               template: extend/extend_invariant_cfg.mustache
-               modelData: none
-
              - desc: Activate invariants defined in sbuilder.yaml
                template: invariant_activate.mustache
                modelData: invariants
@@ -301,19 +291,23 @@ generate:
        # Dump data-models for template generation
 
        - output: doc/data-model.md
-         inputs: 
+         inputs:
 
            - desc: Model header
              template:  data-model-header.mustache
              modelData: none
 
+           - desc: Metatypes
+             template: data-model-dump.mustache
+             modelData: metatypes
+
            - desc: Model interfaces
              template: data-model-dump.mustache
              modelData: interfaces
 
-           - desc: Model interface_types (=request/reponse for all interfaces)
-             template: data-model-dump.mustache
-             modelData: interface_types
+           # - desc: Model interface_types (=request/reponse for all interfaces)
+           #   template: data-model-dump.mustache
+           #   modelData: interface_types
 
            - desc: Model infrastructureServices
              template: data-model-dump.mustache

data/lib/sbuilder/domain.rb

@@ -3,15 +3,24 @@ module Sbuilder
 
   class Domain
 
+    # @attr [Strin] name
     attr_reader :name
 
+    # alias for 
+    alias domain_name :name
+    
+    # @attr [Domain] extension defined in setup, overrinding defaults
     attr_reader :extension
 
     # ------------------------------------------------------------------
-    # mixer
-    PROGNAME = "domain"               # progname for logger
+    # logger
+
+    PROGNAME = nil                            # progname for logger default class name
     include Sbuilder::Utils::MyLogger # mix logger
-    
+
+    # ------------------------------------------------------------------
+    # @!group Constructor & configure
+
 
     def initialize( options = {} )
       @logger = getLogger( PROGNAME, options )
@@ -22,49 +31,95 @@ module Sbuilder
       "#{self.class}: name=#{name}"
     end
 
-    # ------------------------------------------------------------------
-    # config
 
     def setName( name )
       @name = name
       self
     end
 
-    # def setCardinality( cardinality )
-    #   @cardinality = cardinality
-    #   raise "deprecated #{__method__} in #{self.class}"
-    #   self
-    # end
-
-    # ------------------------------------------------------------------
-    # extendDomain 
-    
     def setExtension( extension )
       @extension = extension
     end
 
+    # @!endgroup
+    
+
     # ------------------------------------------------------------------
-    # use extension
+    # @!group Behaviour
+    
+    
+    ##
+    # Should we add Nil to domain set
+    #
+    # @return [Boolean] delegate to extenion, true default
+    def includeNil
+      return extension.includeNil if extension
+      true
+    end
 
+    ##
+    # It is safe to call +cardinality+, +domain_values+,
+    # +numberOfElements+, +render_values+, ...
+    #
+    # @return true, extension may override
+    #
+    def tlaBaseType
+      return extension.tlaBaseType if extension
+      false
+    end
+    
+
+    # Notice: number of elements include also nil element, which should
+    # be calculated, when calculating elements in domain.
+    #
+    # 
     # delegate to extension - return 1 if does not exist
     def cardinality
       return 1 unless extension
       extension.cardinality
     end
 
+    # @return [integer] number of elements including nil
+    def numberOfElements
+      cardinality + 1
+    end
+
+    ##
+    # @return [Integer..Integer] range to access 'domain_entry' of
+    # (maybe extentended) domain
+    def domain_range
+      return extension.domain_range if extension
+      endIndx = includeNil ? cardinality : cardinality-1      
+      0..endIndx
+    end
+    
+
+    # @!endgroup
+
     # ------------------------------------------------------------------
-    # generate
+    # @!group Implementation details
+    
 
-    # alias for 
-    alias domain_name :name
+    ## 
+    # @return [Boolean] false which is internal nil repreentation
+    def nilValue
+      false
+    end
+
+    ##
+    # @return [Boolean] true if +includeNil+ && (Int(0) || Nil)
+    private def isNil( i )
+      includeNil && ( (i.is_a?(Integer) && i == 0) || (i.is_a?(String) && i == 'Nil' ))
+    end
+
+    # @!endgroup
+    
+
+    # ------------------------------------------------------------------
+    # @!group Domain values
 
-    # # used to generate default values - in extension loaded
-    # def domain_prefix
-    #   domain_name + "_"
-    # end
 
     # Return domain value for for element 'i'. Possibly delegate to sub-class.
-    # 
     #
     # @param i [Integer|String] element index (interger) or String value non integer
     #
@@ -72,7 +127,8 @@ module Sbuilder
     def domain_entry( i )
 
       # interpret 0 as Nil
-      return false if i.is_a?(Integer) && i == 0
+      # return false if (i.is_a?(Integer) && i == 0) || (i.is_a?(String) && i == 'Nil' )
+      return nilValue if isNil( i )
 
       # delegage - if possible
       return extension.domain_entry( i ) if extension
@@ -87,34 +143,102 @@ module Sbuilder
       Requested cardinality #{i} exceeds cardinality #{cardinality} of domain #{name}
       EOS
                                                      
-                                                     
+      # defaults strings
       "d_#{domain_name}_#{i}"
     end
-    
 
-    # return array of strings for entries in domain - overrid
-    def domain_entries
-      arr = *(1..cardinality).map { |i| domain_entry( i ) }
+    ##
+    # Default assumes that domain values are string elements, and they
+    # need to be wrapped with " -chars. Sub-classes may define
+    # integers, which should not be wrapped, and they override this
+    # method.
+    #
+    # @return [String] wrapped around "
+    def stringize( val )
+      return val if val.is_a?( FalseClass )
+      '"' + val + '"'
+    end
+
+
+    ## 
+    # Index from 1.. if domain (extension defines Nil), index from
+    # 0 if no need to reserve space for nil (e.g. domain_range).
+    #
+    # Known override in domain range, where using index range does
+    # not necassarily start with 0.
+    #
+    # @see #render_entry
+    #
+    # @return [Array] renderValues set of elements, which can be
+    # outputted to TLA code (i.e. they wrapped with "-char, if
+    # necassary). Does not include Nil.
+    #
+
+    def render_values
+      startIndx = includeNil ? 1 : 0
+      endIndx = includeNil ? cardinality : cardinality-1
+      arr = *(startIndx..endIndx).map { |i| render_entry( i ) }
       return arr
     end
 
+    # @!endgroup    
+    
+
+    # ------------------------------------------------------------------
+    # @!group Model data
 
-    # return and array of {:value,:_comma} hashes
+    ## 
+    # Return entry which can be rendered (string values wrapped with
+    # "-marks, integers plain, constans, e.g. Nil not wrappedd. If
+    # domain +includeNil+ values i==0 and i=='Nil' are wrapped to
+    # 'nilValue' (=false). Actual value from +domain_entry+
+    #
+    def render_entry( i )
+      return nilValue if isNil( i )
+      return extension.render_entry( i ) if extension
+      stringize( domain_entry( i ))
+    end
+
+    
+
+    ##
+    # Called from model#templateData, used in mustache templates to
+    # output elements in domain set. Nil NOT included in this set!
+    #
+    # Is not expected to be overridded by sub-classes.
+    #
+    # @see render_values returnin array of Hashes
+    #
+    # @see #includeNil whether Nil should be included
+    #
+    # @return [Hash:Array] array_of_hashes array of {:value,:_comma}
+    # @option array_of_hashes [:Symbol] :value
+    # @option array_of_hashes [:Symbol] :index
+    # @option array_of_hashes ['String'] _comma
+    
     def domain_values
-      # delegate  - if extended
-      return extension.domain_values if extension
-      arra = domain_entries.map.with_index do |domain_entry, i|
+      vals = extension.nil? ? render_values : extension.render_values
+      
+      # String is - name of a type, no need expand
+      return {
+        :value => vals,
+        '_comma' => '',
+        :index => 0,
+      } unless vals.is_a?( Array )
+      arra = vals.map.with_index do |domain_entry, i|
                 {
-                  :namespace => Constants::TYPE_NAMESPACE_DOM,
                   :value => domain_entry, 
-                  :_comma => (i +1) == cardinality ? "" : ",",
+                  '_comma' => ',',
                   :index => i+1,
                 }
       end
-      @logger.debug( "#{__method__} #{name}: arra #{arra.to_yaml}" )                  
+      arra.last['_comma'] = '' if arra && arra.any?
+      @logger.debug( "#{__method__} #{name}: arra #{arra.to_yaml}, includeNil=#{includeNil}" )                  
       return arra
     end
 
+    # @!endgroup        
+
   end