tla-sbuilder 0.2.2 → 0.3.4

data/lib/sbuilder/facade/facade_constants.rb

@@ -0,0 +1,23 @@
+module Sbuilder
+
+  module FacadeConstants
+  
+    # Meta model keys
+    META_MODEL_DOMAINS="domains"    
+    META_MODEL_DEFINITIONS="definitions"
+    META_MODEL_INTERFACE_TYPES="interface_types"
+    META_MODEL_INTERFACE_RESPONSE_TYPES="interface_response_types"    
+    META_MODEL_PROCESSES="processes"
+    META_MODEL_SERVICE_IMPLEMENTATION="service_implementation"
+    META_MODEL_SERVICE_COMPLETION="service_completion"        
+    META_MODEL_INFRA_SERVICES="infra_services"
+    META_MODEL_FRAMEWORK_SVC="framework-svc"
+    META_MODEL_INVARIANT='invariants'
+
+  end
+
+  class Facade
+    include Sbuilder::FacadeConstants
+  end
+
+end

data/lib/sbuilder/facade/loader_plugin_root.rb

@@ -0,0 +1,56 @@
+module Sbuilder
+
+  # Abstract base class for loader plugins
+  #
+  # Known child classes: ApiLoaderPlugin, SnippetLoaderPlugin
+  
+  class LoaderPluginRoot
+
+    PROGNAME = nil                       # progname for logger default class name
+    include Sbuilder::Utils::MyLogger    # mix logger
+
+    def initialize( options = {} )
+      
+      @logger = getLogger( PROGNAME, options )
+      @logger.info( "#{__method__} initialized, options=#{options}" )
+      
+      
+    end
+
+
+    # #configure method called by controller
+    #
+    # @return [LoaderPluginRoot] self
+    #
+    def configure( configuration )
+      doConfigure( configuration )
+      self
+    end
+
+    # base class should implement 'doConfigure'
+    def doConfigure( configuration )
+      warn "Pluging '#{self.class.to_s}' should implement doConfigure"
+    end
+
+    # @return [Logger] log to Sbuiler log-file
+    def logger
+      @logger
+    end
+
+    def self.validateProperties( hash, required_props, allowed_props )
+      Sbuilder::Utils::Validate.validateProperties( hash, required_props, allowed_props )      
+    end
+    
+
+    def validateProperties( hash, required_props, allowed_props )
+      self.class.validateProperties( hash, required_props, allowed_props )      
+    end
+
+    def oneOf( defintionHash, propList, min=1, max=1 )
+      Sbuilder::Utils::Validate.oneOf( defintionHash, propList, min, max )
+    end
+    
+    
+  end
+
+end

data/lib/sbuilder/facade/param_set_root.rb

@@ -0,0 +1,55 @@
+module Sbuilder
+
+  # Abstract base class for parameter sets (definitions,
+  # interfaces). Provides common method to add parameters to the
+  # parameter set.
+  #
+  # @attr parameters [Sbuilder:Parameter::Array] array of parameters
+  #
+
+  class ParamSetRoot
+
+    
+    attr_reader :parameters                   # array of parameters:Parameter
+
+    # ------------------------------------------------------------------
+    # @!group Constructor and Object Initialize
+    
+
+    # constructor for the abstact class
+    def initialize( options = {} )
+      @parameters = []
+    end
+
+    # @!endgroup    
+
+    # ------------------------------------------------------------------
+    # @!group Configure Model Object Relationships
+    
+    # Add a 'parameter' to known parameters in the parameter set.
+    #
+    # @param param[Sbuilder::parameter] parameter to add
+    def addParameter( param )
+      parameters << param
+      self
+    end
+
+    # @param [String] name to look
+    #
+    # @return [Sbuilder::Parameter|nil] return parameter with name, nil if not found
+    def lookupParameter( name )
+
+      parameters.each do |parameter|
+        return parameter if parameter.name == name 
+      end
+
+      # not found
+      return nil
+      
+    end
+
+    # @!endgroup
+
+
+  end # class
+end

data/lib/sbuilder/facade/snippet_loader_facade.rb

@@ -0,0 +1,600 @@
+module Sbuilder
+
+  # Facade providing interface to concrete 'SnippetLoaderPlugin'
+  # -classes.
+  #
+  #
+  # Facade operator (and snippet plugin) implement choreography:
+  #
+  # * expect 'metatype' to be registered: either it is sbuilder
+  # * defined metatype, it has been registered previously, or 
+  # * plugin has registered 'metatype' using #registerMetatype -api
+  # * provided by facade.
+  #
+  # * hand over: snippet plugin passess snippet `metatype`, `appName`,
+  #  `snippetBody` to facade
+  #
+  # * generate specName: facade generates `specName` = for `metatype`,
+  #   `appName` pair
+  #
+  # * register snippet matadata to symbol table: facade passes snippet matadata
+  #  `metatype`, `appName`, `specName` to symbol table in controller
+  # 
+  # * render snippet code: facade render `snippetBody` to create
+  #  `snippetCode`. Rendering resolves references in `snippetBody`
+  #  from application namespace to specification namespace allowing
+  #  snippet plugins to be unaware of names used in specification
+  #  code. Rendering (=preferred mode of operation) may also resolve
+  #  `snippetName` if `snippetBody` is given using template reference,
+  #  instead of fixed name.
+  #
+  # * parse snippet code: facade access parser (via ParserFacade), and
+  #  parses `snippetCode`.
+  #
+  # * check snippet name: facade ensures that `snitppetName` matches
+  #  `specName`
+  #
+  # * service implementation: `metatype` == META_MODEL_SERVICE_IMPLEMENTATION
+  #   registers `specName` as 
+  #
+  # * save snippet: snippet is saved in Sbuilder `codeRepository` into
+  #   `metatype` specific directory using a file referring to `appName`.
+  #
+  # * add snippet to generation/render phases: 
+  #
+  #
+  # Error modes:
+  #
+  # - unknown `metatype`: raise exception (and quit processing is
+  #   allowed because this indicates a problem in general setup
+  #
+  # - `specName` and `snippetName` mismatch: may result if snippet
+  #   loader defines `spectName`, or if `snippetBlock` does no
+  #   correctly render `snippetName`
+  #
+  # - snippet metadata uniqueness: `specName` is unique, also
+  #   `metatype`/`appName` combination
+  #
+  # - unnkwon reference: render -problem, e.g. SPEC_NAME not found
+  # 
+  #
+  # The use case is implemented using two public api inferfaces:
+  #
+  # * handOver: api being called by snippet loader
+  #
+  # * acceptSnippets: api being called by controller (once all
+  #   snippets have been handed over)
+
+  # @attr_reader [Hash:Array] snippets handed over to facade
+  # @option snippets [String] metatype
+  # @option snippets [String] appName
+  # @option snippets [String] snippetBody
+  #
+  #
+  # @attr_reader [Sbuilder::Controller] controller running sbuilder
+
+
+  
+  class SnippetLoaderFacade
+
+    extend Forwardable                        # for easy delegation
+
+    # [Hash:Array] of snippets handed over to facade
+    attr_reader :snippets
+
+    # [Sbuilder:Controller]
+    attr_reader :controller
+
+    # @attr [String] snippetHeader prefix to wrap snippetBody
+    attr_reader :snippetHeader
+      
+    # @atr [String] postfix to wrap snippetBody 
+    attr_reader :snippetFooter
+    
+    
+    # ------------------------------------------------------------------
+    
+    # progname for logger
+    PROGNAME = nil                            # progname for logger default class name
+    include Sbuilder::Utils::MyLogger         # mix logger
+
+    # Map parser node_type to extension point name
+    @@snippetType2extensionPointMapper = {
+      'Macro'  => Sbuilder::Constants::EXTENSION_POINT_MACRO,
+      'Procedure'  => Sbuilder::Constants::EXTENSION_POINT_IMPLEMENTATION,
+      'VariableDef'  => Sbuilder::Constants::EXTENSION_POINT_STATE,
+      'OperatorDef'  => Sbuilder::Constants::EXTENSION_POINT_OPERATIONS,
+    }
+
+    DEFAULT_SNIPPET_HEADER = <<-EOS.unindent
+      (* SNIPPET: {{metatype}}/{{appName}} --> {{specName}} *)
+      EOS
+
+    DEFAULT_SNIPPET_FOOTER = <<-EOS.unindent
+      (* --END OF SNIPPET-- *)
+
+      EOS
+
+    
+    # ------------------------------------------------------------------
+    # @!group Construtor
+
+    def initialize( factory, options = {} )
+    
+      @logger = getLogger( PROGNAME, options )
+      @logger.info( "#{__method__} initialized" )
+
+      # collaborators init
+      setFactory( factory )
+      @controller = nil
+
+      # snippets handed over to facade
+      @snippets = []
+      
+      @options = options
+
+      @snippetHeader = DEFAULT_SNIPPET_HEADER
+      @snippetFooter = DEFAULT_SNIPPET_FOOTER
+    
+    end
+    
+    # @!endgroup
+
+    # ------------------------------------------------------------------
+    # @!group Prepare Facade
+
+    # Allow facade to access controller services
+    # @param controller [Sbuilder::Controller] controller sets self
+    def setController( controller )
+      @controller = controller
+    end
+
+    # Facade delagates the task to create new objects to `factory
+    # @param factory [Sbuilder::Factory] to create new obejcts
+    def setFactory( factory )
+      @factory = factory
+    end
+
+    def setMustache( mustache )
+      @mustache = mustache
+    end
+
+    ##
+    # Set 'snippetHeader' to wrap around snippets
+    def setSnippetHeader( snippetHeader )
+      @snippetHeader = snippetHeader
+    end
+
+    # Set 'snippetFooter' to wrap around snippets    
+    def setSnippetFooter( snippetFooter )
+      @snippetFooter = snippetFooter
+    end
+
+    # @!endgroup
+
+    # ------------------------------------------------------------------
+    # @!group SnippetLoaderPlugin defines metatype
+
+    ##
+    # Return array of base metatypes in sbuilder context
+    #
+    # @return [Hash] baseMetatypes
+    # @option baseMetatype [Symbol] :name of metatype
+    # @option baseMetatype [Symbol] :desc metatype description
+    def baseMetatypes
+      controller.baseMetatypes
+    end
+
+
+    ##
+    # Add 'metatype' with 'desc' and optional 'prefix' to sbuilder
+    # context.
+    def registerMetatype( metatype, desc, prefix=nil )
+      @logger.info "#{__method__}, metatype='#{metatype}', desc=#{desc}"
+      metatypeDef = createMetatypeDef( metatype, desc, prefix )
+      controller.registerMetatype( metatypeDef )
+    end
+
+    private def createMetatypeDef( metatype, desc, prefix )
+      {
+        :name => metatype,
+        :desc     => desc,
+        :prefix => prefix,
+      }
+    end
+
+    # ------------------------------------------------------------------
+    # @!group SnippetLoaderPlugin hands over snippet
+
+
+    # snippet plugin passess snippet `metatype`, `appName`,
+    # `specName`=nil, and `snippetBody` to facade.
+    #
+    # @param [String] metatype in specification model
+    #
+    # @param [String] appName in application domain being modeled in
+    # `snippetBody`, identified by `metatype`, `appName`, or
+    # `specName.`
+    #
+    # @param [String] specName used to identify `snippetBody` ,
+    # default nil allows sbuilder to generate `specName`. Nil no body
+    #
+    # @param [String] specName use as specName
+
+    
+    def handOver( metatype, appName, snippetBody=nil, specName=nil  )
+      # collect snippets handed over
+      @logger.info "#{__method__}, metatype=#{metatype}, appName=#{appName}, snippetBody=#{snippetBody}"
+
+      # generate specName & combine to hash
+      entry = snippetEntry( metatype, appName, snippetBody )
+
+      # override default specName
+      entry['specName'] = specName unless specName.nil?
+
+      # enable mapping from 'metatype/appName' to 'specName'
+      addSymbol( metatype, appName, entry['specName'] )
+
+      # TLA code generated for interface defition need to entry point
+      # to model implementation defined using
+      # META_MODEL_SERVICE_IMPLEMENTATION -metatype
+      if ( metatype == Sbuilder::Constants::META_MODEL_SERVICE_IMPLEMENTATION ) then
+        interfaceExtension(  appName, entry['specName'], 'implementation' )
+      elsif metatype == Sbuilder::Constants::META_MODEL_SERVICE_COMPLETION
+        interfaceExtension(  appName, entry['specName'], 'completion' )        
+      end
+      
+      @snippets << entry
+    end
+
+    # @!endgroup
+
+    # ------------------------------------------------------------------
+    # @!group controller processes snippets collected
+
+    # Method called by controller to accept snippets, which snippet
+    # plugin has handed over to facade.
+    #
+    # @param [TlaParserS::Resolver] parserResolver to parse `snippetCode`
+    #
+    
+    def acceptSnippets( parserResolver )
+
+      # resove SPEC_NAMEs and convert 'snippetBody' to
+      # 'snippetCode'. Processing continues in block
+      
+      generateSnippetBodies( getMustache ) do |metatype, appName, specName, snippetCode|
+        @logger.info( "#{__method__}: process #{metatype}, appName=#{appName}" )
+        @logger.debug( "#{__method__}: snippetCode = #{snippetCode}" ) if @logger.debug?
+
+        # create an single hash holding properties, and which can be
+        # also passed to parser.
+        parseEntry = parseEntry( metatype, appName, specName, snippetCode )
+
+        # write to file to the file pointed by modulePath (which is
+        # also identified module during parsing)
+        writeSnippetModule( parseEntry[:modulePath], snippetCode )
+
+        # par
+        snippets = parserResolver.initSnippets(  parseEntry  )
+        @logger.info "#{__method__}, snippets=#{snippets.map {|s| { :node_type => s[:node_type], :value => s[:value] } } }"
+
+        # snippetCode should be parseable
+        raise Sbuilder::FacadeException.new  <<-EOS if snippets.nil? || !snippets.any?
+        No snippets found in an entry '#{metatype}:#{appName}':
+
+        #{snippetCode}
+
+        EOS
+        
+        # snippet loader can process only one snippet at a time
+        raise Sbuilder::FacadeException.new  <<-EOS if snippets.length > 1
+        Too many snippets defined in an entry
+        EOS
+
+        # extract name && type of the snippet from the parsed result
+        snippetName = snippetName( snippets[0] )
+        snippetType = snippetType( snippets[0] )
+
+        # Map snippet type to extension point type, and add the
+        # processes snippet as partial to the extension point
+        addPartial( parseEntry, snippetType )
+
+        # add 
+
+        # validate that snippetCode.snippetName == specName
+        raise Sbuilder::FacadeException.new <<-EOS if snippetName( snippets[0] ) != specName 
+        Snippet name '#{ snippetName }' differs from specName '#{specName}' for metatype='#{metatype}', and appName='#{appName}'
+        
+        Difference found in snippet code: 
+
+        #{snippetCode}
+        EOS
+
+      end
+      
+    end
+
+    # @!endgroup
+
+    # ------------------------------------------------------------------
+    # @!group Support code generation
+
+    # @return [Object] mustache object configured using 'setMustache'
+    private def getMustache
+      @mustache
+    end
+
+    # @param [Hash] snippetEntry used to create initial render data
+    # @option snippetEntry [String] metatype
+    # @option snippetEntry [String] appName
+    # @option snippetEntry [String] specName    
+    private def initialReaderData( snippetEntry )
+      snippetEntry
+    end
+
+
+    
+    private def initRenderData
+      
+    end
+
+    # Create unique specName
+    #
+    # @param [String] specName, default nil allows sbuilder to generate `specName`
+    #
+    # @param [String] appName is name application domain being mapped
+    # to `specName` in `metatype`
+    #
+    # @return [String] specName unique name in specification code,
+    # mapping result of `metatype` and `appName` combination
+    
+    private def generateSpecName( metatype, appName )
+      prefix = metatypePrefix(metatype)
+      prefix += "_" unless prefix.blank?
+        prefix + 
+        appName.
+        gsub( /\//, "_" ).   # / --> _
+        gsub( /\(/, "_" ).   # ( --> _
+        gsub( /\{/, "_" ).   # { --> _
+        gsub( /\}/, "_" ).   # } --> _
+        gsub( /\./, "_" ).   # . --> _              
+        gsub( /\)/, "_" )    # ) --> _
+        
+    end
+
+    # @param [Hash] entry in resolver symbol table
+    #
+    # @option entry [:symbol] :value key holding parsed snippet name 
+    #
+    # @return [String] snippetName from 'entry' in property :value
+    private def snippetName( entry )
+      entry[:value]
+    end
+
+    # @param [Hash] entry in resolver symbol table
+    #
+    # @option entry [:symbol] :node_type key holding parsed snippet class name
+    #
+    # @return [String] snippetType from 'entry' in property :node_type
+    private def snippetType( entry )
+      entry[:node_type]
+    end
+
+    # Map 'snippetType' to 'extensionPoint', exception if mapping cannot
+    # be made
+    private def snippetType2extensionPoint( snippetType )
+      extensionPoint = @@snippetType2extensionPointMapper[snippetType]
+      raise Sbuilder::FacadeException.new <<-EOS if extensionPoint.nil?
+      Unknown snippetType '#{snippetType}'. Do not know, how to map it to extension point.
+
+      Known node types #{@@snippetType2extensionPointMapper.keys.join( ',' )}
+      EOS
+      extensionPoint
+    end
+
+    # Use controller to retunn :prefix property in 'metatype'
+    # defintion.
+    #
+    # @return [String] prefix to use for 'metatype'
+    private def metatypePrefix( metatype )
+      
+      metatypeDefinition = controller.getMetaTypeDefinition( metatype )
+      
+      raise Sbuilder::FacadeException.new  <<-EOS if metatypeDefinition.nil?
+      Metatype definition for metatype '#{metatype}' not found
+      EOS
+      
+      raise Sbuilder::FacadeException.new  <<-EOS unless metatypeDefinition[:prefix]
+      Missing property :prefix for metatype '#{metatype}' defined as #{metatypeDefinition}
+      EOS
+      
+      return metatypeDefinition[:prefix]
+    end
+
+    # Create hash which can be passed to tla-parser. Particularly this
+    # hash defines methods (read, moduleName) used by parser.
+    #
+    # @return [Hash] parseEntry to pass to parser#initSnippets
+    #
+    # @option parseEntry [:symbol] code TLA code to parse
+    #
+    # @option parseEntry [:symbol] name string used to identify 'code'
+    #
+
+    def parseEntry( metatype, appName, specName, snippetCode )
+      ret = { :read => snippetCode, :name=> "Api #{metatype}:#{appName}",
+              :modulePath => snippetModulePath(metatype, appName, specName ),
+              :moduleName => File.join( metatype, specName ),             
+            }
+
+      # make it look like a file (supporting read-method)
+      ret.define_singleton_method( :read ) do
+        self[:read]
+      end
+      # parser identifies `snippetCode` as module
+      ret.define_singleton_method( :modulePath ) do
+        self[:modulePath]        
+      end
+      # parser identifies `snippetCode` as module
+      ret.define_singleton_method( :moduleName ) do
+        self[:moduleName]        
+      end
+
+      ret
+
+    end
+
+    # Create module path for  'snippetCode'
+    #
+    # @return [String] modulePath where 'snippetCode' is saved
+    
+    def snippetModulePath( metatype, appName, specName )
+      File.join( snippetRepository( metatype ), specName )
+    end
+
+    # @return [String] repositoryPath to root direcnoty under, which
+    # to store snippets
+    #
+    # @param [String] metatype in specification model
+    #
+    # @return [String] path to an existing snippet direcotory
+
+    def snippetRepository( metatype )
+      snippetRepo = controller.snippetRepository
+      controller.metatypeSnippetRepository( snippetRepo, metatype )
+    end
+
+    private def snippetEntry( metatype, appName, snippetBody )
+      {
+        'metatype' => metatype,
+        'appName' => appName,
+        'snippetBody' => snippetBody,
+        'specName' => generateSpecName(metatype, appName ),
+      }
+    end
+
+    # Iterate 'snippets' handed over to the facade, and use mustache
+    # render 'snippetBody' to 'snippetCode'.  Typically rendering
+    # resolves SPEC_NAME -section used to map application domain names
+    # to specification code domain.
+    #
+    # @yields [metatype,appName,specName,snippetCode] yields
+    # 'snippetCode' together with meta data to caller
+    #
+    #
+    private def generateSnippetBodies( mustache, &blk )
+
+      snippets.each do |snippetEntry|
+
+        spippetCode = nil
+
+        # render body - only if defined
+        if snippetEntry['snippetBody']
+
+          @logger.debug "#{__method__}: snippetEntry['snippetBody']=#{snippetEntry['snippetBody']}" if @logger.debug?
+
+          # create initial hash
+          renderData = initialReaderData( snippetEntry )
+          
+          # add functions to renderData allowing access to symbol_table
+          # (SPEC_NAME)
+          renderData = decorateRenderData( renderData, mustache )
+
+          # wrap snippet between header/footer, resolve {{mustache}} references
+          bodyText = snippetHeader + snippetEntry['snippetBody'] + snippetFooter
+          snippetCode = mustache.render( bodyText, renderData )
+
+          # pass code + meta data to block
+          yield snippetEntry['metatype'], snippetEntry['appName'], snippetEntry['specName'], snippetCode
+
+        end
+
+      end
+      
+    end
+
+    # Add functions used in mustache rendering sections to 'renderData'
+    #
+    # Implementation delegates this task to controller
+    #
+    # @param [Hash] renderData to decorate
+    #
+    # @return [Hash] renderData decorated with functions uses in
+    # mustache rendering.
+    private def decorateRenderData( renderData, mustache )
+      controller.decorateRenderData( renderData, mustache )
+    end
+
+    private def addSymbol( metatype, appName, specName )
+      controller.getSymbolTable.addSymbol( metatype, appName, specName )
+    end
+
+    # Inform sbuilder for the fact the interface for  'appName'  service
+    # should call 'specName'.
+    #
+    # Implementation creates a hash (matching propertis used in
+    # 'interface-extension'), and delegates the operation to
+    # 'controller.extendInterface'
+    #
+    # @param [String] extensionType passed to sbuilder defining, what
+    # to extend, known cases 'implementation', 'completion'
+    #
+    #
+    private def interfaceExtension( appName, specName, extensionType )
+      interfaceExtensionDef = {
+        'matcher' => appName,
+        extensionType  => specName,
+      }
+      controller.extendInterface(  interfaceExtensionDef )
+    end
+
+    # Mapp 'snippetType' to 'extensionPoint', and add 'parseEntry' to
+    # controller partial.
+    
+    private def addPartial( parseEntry, snippetType )
+      extensionPoint = snippetType2extensionPoint( snippetType )
+      controller.addPartials( [ parseEntry.moduleName ], extensionPoint )
+    end                  
+
+
+    # Write 'snippetCode' to 'modulePath'
+    #
+    # @param [String] modulePath path to file
+    #
+    # @param [String] snippetCode contet to write
+    #
+    #
+    private def writeSnippetModule( modulePath, snippetCode )
+      @logger.info "#{__method__}, modulePath=#{modulePath}"      
+      @logger.debug "#{__method__}, modulePath=#{modulePath}, snippetCode=#{snippetCode}"
+      Sbuilder::Utils::FileIo.write( modulePath, snippetCode )
+    end
+
+    # @!endgroup    
+    
+    # ------------------------------------------------------------------
+    # @!group Miscellaneous services
+
+    # Return cache directory location from opitions
+    #
+    # @return [String] path to cache -directory
+    def getCacheDir
+      controller.getCacheDir
+    end
+
+    # @return [String] semver number
+    def version
+      Sbuilder::version
+    end
+
+    # @param logname [String] progname to set on logger
+    #
+    # @return [Logger] new logger object
+    def createLogger( logname=nil )
+      getLogger( logname, @options )
+    end
+
+  end
+  
+end