sbuilder-al 0.0.8

data/lib/model/module.rb

@@ -0,0 +1,25 @@
+module Sbuilder
+  module Al
+    ##
+    # Application model classes and Domain Scpecific (DSL) language
+    # to build application model for Sbuilder::Al
+    #
+    # Sub modules
+    #
+    # - Model {Sbuilder::Al::Model} Application model POJO classes
+    #
+    # - Builders {Sbuilder::Al::Model::Builders}
+    #
+    # - Builders {Sbuilder::Al::Model::Api} Api module to include into
+    #        object to construct {Sbuilder::Al::Model} application
+    #        model.
+    #
+    module Model
+    end
+  end
+end
+
+require_relative("constants")
+require_relative("model")
+require_relative("builders")
+require_relative("api")

data/lib/plugin/controller.rb

@@ -0,0 +1,247 @@
+module Sbuilder
+  module Al
+    module Plugin
+      class Controller
+
+        # include logger
+        include Sbuilder::Al::Util::MyLogger         # mix logger
+
+
+        # ------------------------------------------------------------------
+        # Module state
+
+        # @!attribute application [Array<RootObject>] array of
+        #    Sbuilder::Al::Model objects
+        attr_accessor :application
+
+        # @!attribute [Hash] metaDefs which application objects use
+        # @option metaDefs [String] <key> name of metadefinition
+        # @option metaDefs [Hash] <value> hash with properties
+        # ':description' and optinally ':prefix'
+        attr_accessor :metaDefs
+
+        # @!attribute producer [Sbuilder::Al::Translator::Producer>]
+        attr_accessor :producer
+
+        # @!attribute producer [Sbuilder::Al::Translator::Translator>]
+        attr_accessor :translator
+
+        # @!attribute producer [Sbuilder::Al::Translator::Renderer>]
+        attr_accessor :renderer
+
+        # Fixed template to convert tlaSexp to tlaString
+        SNIPPET_TEMPLATE = "{|#EVAL|}template{|/EVAL|}" + "\n"
+        DOMAIN_TEMPLATE = "{|#EVAL|}template{|/EVAL|}"
+        SNIPPET_KEY = :template
+
+        # 
+        PLUGIN_CONFIGURATION_REQUIRED= [ 'rubypaths'  ]
+
+        # ------------------------------------------------------------------
+        # @!group Constructor
+
+        def initialize( options = {} )
+          @logger = getLogger( nil, options )
+          @logger.info( "#{__method__} sbuilder-al plugin controller initialized" )
+
+          self.application = []
+          self.metaDefs = {} 
+          initTranlatePipe( self, options )
+        end
+
+        # Init state attributes for a pipe to translate 'alObject' to
+        # 'tlaString' in {Sbuilder::Al:Controller::Controller}
+        #
+        private def initTranlatePipe( c, options={} )
+          # traslate
+	  tlaGen = Sbuilder::Al::Translator::TlaGenerator.start()
+	  c.producer = Sbuilder::Al::Translator::Producer.start( tlaGen, options )
+	  rules = Sbuilder::Al::Translator::AlRules.rules( producer )
+	  c.translator = Sbuilder::Al::Translator::Translator.start( rules )
+          #  render
+          c.renderer  = Sbuilder::Al::Translator::Renderer.start( c.producer )
+        end
+
+        # Construct controller object with default configuration
+        #
+        def self.start( options={})
+
+          warn "Depracate method .start for Sbuilder::Al::Plugin::Controller"
+          o = Sbuilder::Al::Plugin::Controller.new( options )
+          
+          o
+        end
+
+        # @!endgroup 
+
+        # ------------------------------------------------------------------
+        # @!group Load application
+
+        # Load Ruby scripts  from conf['rubypaths'], uses {#addAlobjects}
+        #
+        # @param conf [Hash] configuration hash with property 'rubypaths'
+        #
+        # @return [Controller] self to allow pipe
+        #
+        def initApplication( conf )
+          warn "Missing configuration 'rubypaths' in al-configuration #{conf}" if conf['rubypaths'].nil?
+          loadAlScripts( conf['rubypaths'] || [] )
+        end
+
+        # A method called when all plugins have had their
+        # initApplication called, and next phase in sbuilder loading
+        # starts
+        def initApplicationFinalize
+          # nop
+        end
+
+        # Load AL language Ruby scrips in 'filenames' to
+        # {#application} using {#addAlObjects}.
+        #
+        # 
+        # @param filenames [String, Array<String>] path to file with
+        # Ruby scripts to evaluate and to load to {#application}
+        #
+        # @return [Controller] self to allow pipe
+        def loadAlScripts( filenames )
+          filenames = [ filenames ] unless filenames.is_a?(Array)
+          filenames.each do |filename|
+            # self.application = application + Sbuilder::Al::Util::ScriptEval.script_eval( filename )
+            addAlObjects( Sbuilder::Al::Util::ScriptEval.script_eval( filename ) )
+          end
+          # To allow pipe
+          self
+        end
+
+          
+        # @!endgroup
+
+        # ------------------------------------------------------------------
+        # @!group Services used by child classes
+
+        ##
+        # Add AL language object 'alObjects' to {#application} elements
+        #
+        # @param alObjects [AlObject, Array<AlObject>] AL language
+        # object(s) to add
+        def addAlObjects( alObjects )
+          alObjects = [ alObjects ] unless alObjects.is_a?(Array)
+          @logger.info( "#{__method__} adding alObjects.length=#{alObjects.length}")
+          @logger.debug( "#{__method__} alObjects.length=#{alObjects.join("\n")}") if @logger.debug?          
+          self.application = application + alObjects
+        end
+
+        # Add metatype definitions to controller contex.
+        #
+        # @param defs [Hash] a hash describing matetypes
+        def addMetatypes( defs )
+          self.metaDefs = metaDefs.merge(defs)
+        end
+
+        # @!endgroup
+
+
+        # ------------------------------------------------------------------
+        # @!group Translate & render
+
+        # Convert 'alObject' to tla language string.
+        #
+        # In the first step, implementation uses {#translator} to
+        # convert 'alObject' to 'tlaSexp', and ,in the second step,
+        # {#renderer} to create 'tlaString' for 'tlaSexp'. NB:
+        # renderer uses partial templates created by {#translator}.
+        #
+        # @param alObject [Sbuilder::Al::Moldel] AL language object to
+        # render to string
+        #
+        # @return [String] tlaString for 'alObject'
+        def  alObject2tlaString( alObject )
+          tlaSexp = alObject2tlaSexp( alObject )
+          tlaSexp2tlaString( tlaSexp )
+          # tlaString = renderer.to_str( SNIPPET_TEMPLATE, { SNIPPET_KEY=>tlaSexp } )
+          # tlaString
+        end
+
+        def tlaSexp2tlaString(tlaSexp, template=SNIPPET_TEMPLATE)
+          tlaString = renderer.to_str( template, { SNIPPET_KEY=>tlaSexp } )
+        end
+
+
+        def  alObject2tlaSexp( alObject )
+          tlaSexp = translator.translate( alObject )
+        end
+
+        # @!endgroup        
+        
+
+        # ------------------------------------------------------------------
+        # @!group Access Api Langauge (AL) objects in {#application}
+
+        # @return [Array<AlObject>] Al object array with type :domain
+
+        def domains
+          application.any? && application.select do |alObject|
+            alObject[:type] == :domain
+          end.map do |alObject|
+            @logger.debug "#{__method__}: alObject.values=#{alObject.values}" if @logger.debug?
+            alObject2tlaSexp(alObject)
+          end.
+          map do |domainDef|
+            @logger.debug "#{__method__}: before-domainDef[:values]=#{domainDef[:values]}" if @logger.debug?
+            domainDef[:values] = domainDef[:values].map { |tlaSexp| tlaSexp2tlaString(tlaSexp, template=DOMAIN_TEMPLATE) }
+            @logger.debug "#{__method__}: after-domainDef[:values]=#{domainDef[:values]}" if @logger.debug?            
+            domainDef
+          end || []
+        end
+
+        # @return [Array<AlObject>] array of type defines (type ==
+        #      :definition) or function defines ( type ==
+        #      :function_definition)
+        def typeDefines
+          application.any? && application.select { |alObject| alObject[:type] == :definition || alObject[:type] == :function_definition } || []
+        end
+
+        # @return [Array<AlObject>] array of Al interface objects
+        def interfaces
+          application.any? && application.select { |alObject| alObject[:type] == :transaction } || []
+        end
+
+        #
+        # Implementation translates {#application}AlObjects for
+        # non-snippets types (:domain, :definition,
+        # :function_definition).
+        #
+        # Implemetation expect alObjects being processed to implement
+        # method #meta and #appName. Normally #appName is alias name
+        # for #name method, but, at least :transaction, :appName is
+        # results "#{name}(#{operation})"
+        #
+        # @return [Array<Hash>] array of snippet hashes with
+        #      properties :metatype, :appName, :tlaString
+        def tlaSnippets
+          application.
+            reject do |alObject|
+            [:domain, :definition, :function_definition ].include?(alObject.type)
+          end.map do |alObject|
+            # No tlaString conversion for some alObjects (particularly
+            # :alias, which just associates appName to specName
+            # without implementation in :tlaString
+            tlaString = [:alias].include?(alObject.type) ? nil :  alObject2tlaString(alObject)
+            {
+              :metatype => alObject.meta,
+              :appName => alObject.appName,
+              :specName => alObject.respond_to?(:specName)  ? alObject.specName : nil,
+              :tlaString => tlaString,
+            }
+          end
+        end
+        
+
+        # @!endgroup
+
+
+      end
+    end
+  end
+end
+

data/lib/plugin/module.rb

@@ -0,0 +1,2 @@
+require_relative( "controller")
+require_relative( "plugin")

data/lib/plugin/plugin.rb

@@ -0,0 +1,352 @@
+require  'sbuilder'
+
+module Sbuilder
+  module Al
+    module Plugin
+      class Plugin < Sbuilder::LoaderPluginRoot
+
+
+        # mix api loader plugin services
+        include ApiLoaderPluginMixer
+
+        # mix snippet loader plugin services
+        include SnippetLoaderPluginMixer
+
+        # include logger
+        include Sbuilder::Al::Util::MyLogger         # mix logger
+        
+        # ------------------------------------------------------------------
+        # state
+
+        # @!attribute controller [Sbuilder::Al::Controller::Controller] state of application
+        attr_accessor :controller
+
+        # @!attribute options [Hash] init options rememeber
+        attr_accessor :options
+
+        # ------------------------------------------------------------------
+        # Configuration
+
+        # # @!attribute metatypes [Hash] hash with metatypes as keys,
+        # #     and values as hash with properties :description (and
+        # #     (optional :prefix)
+        # attr_accessor :metatypes        
+
+        # ------------------------------------------------------------------
+        # Validation
+        
+        PLUGIN_CONFIGURATION_REQUIRED=[]
+        PLUGIN_CONFIGURATION_ALLOWED=[ 'application', "metatypes", "rubypaths" ]      
+        
+
+        # ------------------------------------------------------------------
+        # @!group Constructor
+
+
+        def initialize( options={} )
+          super( options )
+          self.options = options
+          @logger = getLogger( "AlPlugin", options )
+          @logger.info( "#{__method__} sbuilder-al plugin init" )
+          self.controller = Sbuilder::Al::Plugin::Controller.new( options )
+        end
+
+        # @return [String] version from VERSION
+        def self.version
+          File.read( File.join( File.dirname( __FILE__), "../..",  "VERSION"))
+        end
+
+        # @!endgroup
+
+        # ------------------------------------------------------------------
+        # @!group sbuilder configuration
+
+        # Class level configuration
+        #
+        # @param [Hash] configuration given in 'extend.loaders'
+        #
+        # @option configuration [String] solc_command path to solc
+        # executable
+        #
+        def self.configure( configuration )
+        end
+
+        # Instance level configuration
+        #
+        # @param [Hash] configuration for object instance, intercepts
+        # properties 'metatypes' and 'loader'. Configuration object
+        # passed as is to {#initApplication}
+        #          
+        #
+        # @return [Boolean] true for success
+
+        def configure( configuration )
+          configuration = {} if configuration.nil?
+          # validateProperties( configuration, PLUGIN_CONFIGURATION_REQUIRED, PLUGIN_CONFIGURATION_ALLOWED )
+
+          # self.metatypes = configuration['metatypes'] unless configuration['metatypes'].nil?
+          # self.metatypes = metatypes || {}
+          controller.addMetatypes( configuration['metatypes'] ) if configuration['metatypes']
+
+          
+          setController( configuration )
+          @logger.info "#{__method__}: calling initApplication with #{configuration}"
+          initApplication( configuration )
+
+          # success
+          true
+        end
+
+        # Set {#controller} if configuration['loader'] defined
+        private def setController( configuration )
+
+          # no change for controller
+          return if configuration['className'].nil?
+
+          # load class module to context - unless Class already defined
+          if ! Class.const_defined?( configuration['className'] )
+            if configuration['gem'].nil?
+              msg = <<-EOS
+                  Missing 'gem' property for loader class #{configuration['className']}
+                  in plugin configuration  #{configuration}
+              EOS
+              @logger.error( "#{__method__} #{msg}" )          
+              raise msg
+            end
+
+            if configuration['gem'][0] == '.'
+              require_relative configuration['gem']
+            else
+              require configuration['gem']
+            end
+            
+          end
+            
+          # create controller object
+          begin
+            @logger.info "#{__method__} configuration['className']=#{configuration['className']}"
+            klass = Object.const_get( configuration['className'] )
+          rescue Exception => e
+            msg = <<-EOS
+          Unknown class: #{configuration['className']}, #{e.message}
+
+          in plugin configuration  #{configuration}
+          EOS
+            @logger.error( "#{__method__} #{msg}" )          
+            raise NameError, msg, e.backtrace
+          end
+
+          # instantiate new controller object
+          self.controller = klass.new( options )
+
+        end # private def setController( configuration )
+
+        private def initApplication( configuration )
+          
+          # init application using 'configuration'
+          controller.initApplication( configuration )
+        end
+
+        # Signal that application initalization has finished &&
+        # registaration starts
+        private def initApplicationFinalize
+          controller.initApplicationFinalize
+        end
+        
+
+
+        # @!endgroup
+
+        # ------------------------------------------------------------------
+        # @!group Services
+
+        # @param metatype [String/Symbol] to check
+        #
+        # @return [Boolean] true if 'metatype' is valid sbuilderMetatype
+        def self.sbuilderMetatype?( metatype )
+          return true if baseMetatypes.map{ |h| h[:name] }.include?(metatype)
+          return( false )
+        end
+
+        # Accesss sbuilder service to convert 'operation' -name to a
+        # valid string in formal code.
+        def self.sbuilderOperation2name( operationName )
+          Sbuilder::ParamSetRoot.id2name( operationName )
+        end
+
+        # @!endgroup
+        
+        
+        # ------------------------------------------------------------------
+        # @!group sbuilder extension points
+
+        # Sbuilder API loader extension point. Load domains, defines
+        # and interfaces to Sbuilder using API facade.
+        # 
+        def load( sbuilderConfig )
+
+          # signal plugin that initiazation has finihsed &&
+          # registration has started
+          initApplicationFinalize
+
+          # pass various AL-objects using Sbuilder API loader
+          # extension point
+          loadDomains
+          loadDefines
+          loadInterfaces          
+        end
+
+        # Load domains to tla-sbuilder over api loader facade.
+        #
+        # Implementation queries domains from {#controller} and calls
+        # facade method 'defineDomain'
+        private def loadDomains
+          controller.domains.each do |domain|
+            @logger.info "#{__method__}: name=#{domain[:name]}, values=<#{domain[:values].is_a?(Array) ? domain[:values].join(',') : domain[:values]}>"
+            facade.defineDomain( domain[:name], domain[:values] )
+          end
+        end
+
+        # Load (type/funtion) defines to tla-sbuilder over api loader
+        # facade.
+        #
+        # Implementation queries typeDefines from {#controller},
+        # construcsts parameter set using 'newDefinition' or
+        # 'newFunctionDefinition', add parameters to the definition
+        # constructed using 'newParameter' and 'newParameterReference'
+        # facade methods.
+        
+        private def loadDefines
+          controller.typeDefines.each do |definition|
+            @logger.info "#{__method__}: name: #{definition[:name]}, type=#{definition[:type]}"
+            case definition[:type]
+            when :definition
+              currentDefinition = facade.newDefinition( definition[:name] )
+            when :function_definition
+              currentDefinition = facade.newFunctionDefinition( definition[:name] )              
+            else
+              raise "Unknown type '#{definition[:type]}' for #{definition}"
+            end
+            definition[:properties] && definition[:properties].each do |property|
+              # Add 'property' to 'currentDefinition'
+              addParameterSetProperty( currentDefinition, property )
+            end
+            facade.modelDefinition( currentDefinition )            
+          end
+        end
+
+
+        private def loadInterfaces
+          controller.interfaces.each do |interface|
+            # Create interface object
+            # TODO: configuration for infrastructureService and interfaceService
+            
+            infrastructureService = interface.returnOption       # support return value
+            interfaceService = interface.interfaceOption         # create interface process
+            currentInterface = facade.newInterface( interface[:name], interface[:operation], infrastructureService, interfaceService )
+            # add link to source - if it has been set
+            facade.setSourceLink( currentInterface, interface.sourceModule,
+                                  interface.sourceLine, interface.sourceColumn ) if interface.sourceModule && !interface.sourceLine.nil?
+            # Add request parameters
+            warn "No request defined for interface:'#{interface[:name]}(#{interface[:operation]})'"
+            interface[:request] && interface[:request].properties && interface[:request].properties.each do |property|
+              addParameterSetProperty( currentInterface, property )
+            end
+            interface[:response] && interface[:response].properties && interface[:response].properties.each do |property|
+              addParameterSetResponseProperty( currentInterface, property )
+            end
+            # Pass current interface to sbuilder
+            facade.modelInterface( currentInterface )
+          end
+        end
+
+        # Add 'property' to 'currentParameterSet'.
+        #
+        # Implementation uses '@facade' to construct parameters/parameter reference objects, which
+        # are added to the current parameter set.
+        #
+        # @param currentParameterSet [Sbuilder::Definition, Sbuilder::Interface] where to add the propery
+        # @param property [Hash] with properties :name and :domain/:definition
+        #
+        private def addParameterSetProperty( currentParameterSet, property )
+
+          raise "Expecting property :isArray on #{property}" unless property[:isArray].is_a?( TrueClass) || property[:isArray].is_a?( FalseClass)
+          isArray = property[:isArray]
+          if property[:definition]
+            newParameterReference = facade.newParameterReference( property[:name], property[:definition], isArray )
+            facade.addParameter( currentParameterSet, newParameterReference )
+          else
+            newParameter = facade.newParameter( property[:name], isArray )
+            facade.addParameter( currentParameterSet, newParameter, property[:domain] )
+          # else
+          #   raise "Must define 'domain' or 'definition' for parameter '#{property.name}'"
+          end
+        end
+        
+        private def addParameterSetResponseProperty( currentParameterSet, property )
+          raise "Expecting property :isArray on #{property}" unless property[:isArray].is_a?( TrueClass) || property[:isArray].is_a?( FalseClass)
+          isArray = property[:isArray]
+          if property[:definition]
+            newParameterReference = facade.newParameterReference( property[:name], property[:definition], isArray )
+            facade.addResponseParameter( currentParameterSet, newParameterReference )                
+          else # property[:domain]
+            # raise "Must define :name and :domain on #{property}" unless !property[:name].nil? && !property[:domain].nil?
+            newParameter = facade.newParameter( property[:name], isArray )
+            facade.addResponseParameter( currentParameterSet, newParameter, property[:domain] )
+          # else
+          #   raise "Must define 'domain' or 'definition' for parameter '#{property.name}'"
+          end
+        end
+        
+
+
+        # Snippet loader extension point
+        #
+        # Overrides abstract method in parent class.
+        #
+        # Implementation loads metatypes and snippets to tla-sbuilder
+        # over snippet facade.
+        #
+        # @param [Hash:Array] snippetDefitions given in sbuilder.yaml
+        #
+        def doRegisterSnippets( snippetDefitions )
+
+          @logger.debug( "#{__method__}: starting") if @logger.debug?
+
+          loadMetatypes
+          loadSnippets
+          
+        end
+
+        # Load metatypes to tla-sbuilder over snippet loader facade
+        #
+        # Implemetation extracts metatatypes from controller and calls
+        # snippetFacade.registerMetatype
+        private def loadMetatypes
+          # @logger.info "#{__method__}: metatypes=#{metatypes.keys.join(',')}"
+          # metatypes && metatypes.keys.each do |metatype|
+          #   snippetFacade.registerMetatype( metatype, metatypes[metatype]["description"], metatypes[metatype]["prefix"] )
+          # end
+          controller.metaDefs.keys.each do |metatype|
+            snippetFacade.registerMetatype( metatype, controller.metaDefs[metatype]["description"], controller.metaDefs[metatype]["prefix"] )
+          end
+          
+        end
+
+        # Load snippets to tla-sbuilder over snippet loader facade
+        #
+        # Implementation queries snippets from {#controller} and calls snippetFacade
+        # method 'handOver'
+        def loadSnippets
+          controller.tlaSnippets.each do |snippet|
+            snippetFacade.handOver( snippet[:metatype].to_s, snippet[:appName], snippet[:tlaString], snippet[:specName] )
+          end
+        end
+
+        # @!endgroup 
+        
+      end
+    end
+  end
+end
+