sbuilder-al 0.0.8

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6f8c4a390b98790cf7eebeae8c39af57fff98657
+  data.tar.gz: f89df2d19fb85e6f1ccdbb6c19caa8ad38a87f61
+SHA512:
+  metadata.gz: 69fe015460b662fc1e07f7b7e6cf6d308dcf4bc0062243b1cabed7e22a96774d5556f29e0a83e5c73022762d552e261e7c23a36fa6c026e5d827dceaa30da10b
+  data.tar.gz: 30d6f16c6884da322c0cd63b62b241d2c8c3b5687ebcd39c43b20136704e10fe55a91b45b9813bfddeebc0e17e4766c575425e6f8574fa43f633a237bb66bfb7

data/README.org

@@ -0,0 +1,217 @@
+* =sbuilder-al=: an API Language Interface to  =tla-sbuilder= -Tool
+
+  =tla-sbuilder= is tool to generate runnable formal models in [[http://research.microsoft.com/en-us/um/people/lamport/tla/book.html][TLA+
+  language]] for [[https://github.com/jarjuk/tla-sbuilder#TARGET-SYSTEM][business IT systems]]. A formal model can be [[https://en.wikipedia.org/wiki/Model_checking][model
+  checked]] using [[http://research.microsoft.com/en-us/um/people/lamport/tla/tools.html][TLA+ Tools]].
+
+   =sbuillder-al= defines an [[design/al-language-bnf.org][API Language]] (AL), which it maps to [[https://github.com/jarjuk/tla-sbuilder#API_LOADER][API
+  Loader]] and [[https://github.com/jarjuk/tla-sbuilder#SNIPPET_LOADER][Snippet Loader]] extension points in =tla-sbuilder=.
+
+  Normally, there is no need to install =sbuilder-al= separately
+  because =sbuilder-al= is included as dependency for higher level
+  interfaces. For example, [[https://github.com/jarjuk/sbuilder-eth][sbuilder-eth]] GEM, Ethereum Solidity
+  interface to =tla-sbuilder=, uses =sbuilder-al= to interface with
+  =tla-sbuilder=.
+
+* Development
+
+** Run Rspec Unit Tests
+
+To run =rspec= unit tests
+
+#+name rspec
+#+BEGIN_SRC sh :eval no-export :results output :exports code
+bundle exec rspec
+#+END_SRC
+
+#+RESULTS:
+#+begin_example
+...................*.......................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
+
+Pending: (Failures listed here are expected and do not affect your suite's status)
+
+  1) Sbuilder::Al::Meta::Etc.alObject2ApiString domain 
+     # causes dump
+     # ./spec/meta/etc_spec.rb:113
+
+Finished in 0.4775 seconds (files took 0.49587 seconds to load)
+1659 examples, 0 failures, 1 pending
+
+#+end_example
+
+
+** Run Cucumber Tests
+
+   To run =cucumber= tests
+
+#+name cucumber
+#+BEGIN_SRC sh :eval no-export :results output :exports code
+bundle exec  cucumber
+#+END_SRC
+
+#+RESULTS:
+: Using the default profile...
+: ...........................................................................
+: 
+: 6 scenarios (6 passed)
+: 75 steps (75 passed)
+: 0m8.028s
+
+
+* Usage (Normally not needed)
+  :PROPERTIES:
+  :CUSTOM_ID: MANUAL-USAGE
+  :END:
+
+Following short steps demonstrate, how =sbuilder-al= loads AL snippets
+to =tla-sbuilder= context.
+
+** Create Gemfile
+
+Configure =sbuilder-al= into =Gemfile=
+
+#+BEGIN_SRC ruby :eval no
+source "https://rubygems.org"
+gem "sbuilder-al"
+#+END_SRC
+
+and install it together with dependencies:
+
+#+BEGIN_SRC sh :eval no
+bundle install
+#+END_SRC
+
+** Initialize =tla-sbuilder= directory structure
+
+Command
+
+#+name: sbuilder-init
+#+BEGIN_SRC sh :eval no-export :results output :exports code
+bundle exec  sbuilder.rb init
+#+END_SRC
+
+creates directory structure for running tla-sbuilder.
+
+#+RESULTS: sbuilder-init
+#+begin_example
+Directory cnf - created
+Directory cache - already exists - no need to create
+Directory src - created
+Directory src/extend - created
+Directory gen - created
+File cnf/sbuilder.yaml.example - created
+File cnf/resolver_customer.yaml.example - created
+File cnf/extend_customer_doms.yaml.example - created
+File cnf/extend_customer_if.yaml.example - created
+File cnf/extend_customer_run1.yaml.example - created
+File cnf/extend_customer_run2.yaml.example - created
+File cnf/interface_customer.yaml.example - created
+#+end_example
+
+
+** Create Configuration File =cnf/sbuider.yaml=
+
+Create a configuration file =cnf/sbuilder.yaml= with the following YAML content
+
+#+BEGIN_SRC yaml :eval no :tangle cnf/sbuilder.yaml
+
+# Define 'sbuilder-al' extension point
+extend:
+  loaders:
+     - className: Sbuilder::Al::Plugin::Plugin
+       gem: sbuilder-al
+       objects:
+          # define object 'alLoader' and configure it 
+          - objectName: alLoader
+            configuration:
+                metatypes:
+                    example: 
+                        description: Example metatype using ex prefix
+                        prefix: ex
+                rubypaths:
+                     - src/al.rb
+
+# Run as API loader extension point
+interfaces:
+   -  objectName: alLoader
+
+# Run as Snippet loader extension point
+snippets:
+  -  objectName: alLoader
+
+
+# Define setup with name 'setup1'
+setups:
+- setupDirectory: setup1
+
+#+END_SRC
+
+** Create Api Langauage file =src/al=
+
+Create a simple AL language module, which defines an API object
+=alApi= to construct AL language objects in an array 
+
+#+BEGIN_SRC ruby eval :no exports :code :tangle src/al.rb
+
+    # Include GEM 
+    require('sbuilder-al')
+
+    # Define api interface to tla-sbuilder
+    class AlApi
+       include Sbuilder::Al::Model::Api
+    end
+
+    nameSpaces = { "example" => { :description=>"Example namespace", :prefix=>"ex_" } }
+    alApi = AlApi.start( nameSpaces ) 
+
+
+    # Application is an array of AL elements
+    [
+       alApi.variable( "example") do
+	 name "var1"
+	 init alApi.constantExpression { value "Hello World" }
+       end,
+
+    ]
+
+
+#+END_SRC
+
+** Generate sbuilder
+
+Running 
+
+#+name: sbuilder-gen
+#+BEGIN_SRC sh :eval no-export :results output :exports code
+bundle exec  sbuilder.rb generate setup1
+#+END_SRC
+
+#+RESULTS: sbuilder-gen
+
+creates a file 
+
+#+name: sbuilder-ls
+#+BEGIN_SRC sh :eval no-export :results output :exports code
+ls -l gen/setup1/tla/model.tla
+#+END_SRC
+
+#+RESULTS: sbuilder-ls
+: -rw-rw-r-- 1 jj jj 16242 joulu 18 10:36 gen/setup1/tla/model.tla
+
+which defines variable =ev_var1=
+
+#+name: sbuilder-grep
+#+BEGIN_SRC sh :eval no-export :results output :exports code
+grep 'Hello' gen/setup1/tla/model.tla
+#+END_SRC
+
+#+RESULTS: sbuilder-grep
+:       ex_var1 = "Hello World";
+
+
+for the AL snippet created in =src/al.rb= module.
+
+
+* License
+
+MIT

data/VERSION

@@ -0,0 +1 @@
+0.0.8

data/design/al-language-bnf.org

@@ -0,0 +1,216 @@
+#+BEGIN_EXAMPLE
+
+# Top level application 
+<application>        :: <snippet>*
+<snippet>            :: <apiSnippet> | <tlaSnippet>
+
+# Api snippets
+<apiSnippet>         :: <transaction> | <definition>  | <domain>
+
+<domain>             :: =domain= {  =name= STRING, 
+                           [ 
+                               =value= STRING     |
+                               =value= INT        |
+                               =value= true       |
+                               =value= false      |
+                               =literal= STRING
+                           ]*
+                         }
+
+<definition>         :: =definition= { 
+			    =name= STRING
+			    <property>*
+			 }
+
+
+<property>           :: =property= {
+			       =name= STRING
+			       =domain= STRING
+                               =isArray= BOOLEAN
+			  } |
+			  =property= {
+			       =name= STRING
+			       =definition= STRING 
+                               =isArray= BOOLEAN
+			  }
+
+# TLA & API snippets
+<transaction>        :: =transaction=  <meta>  {
+			    =name= STRING 
+                            (=local= STRING)*
+                            =interfaceOption= <booleanExpression> 
+                            =returnOption= <booleanExpression> 
+                            =request= <request>
+                            =response= <response>
+			    =operation= STRING
+			    =block= <block>
+			}
+
+<request>            :: =request= { 
+                              <reqResponseParam>*
+                          }
+<response>           :: =response= {
+                              <reqResponseParam>*
+                         }
+<reqResponseParam>   :: =parameter= <name> <isArray> [ <domainName> ] |
+                        =reference= <name>  <isArray> <definitionName>
+<isArray>            :: true | false
+
+
+# TLA snippets
+<tlaSnippet>         :: <transaction> | <macro> | <operator> | <variable> | <alias>
+<macro>              :: =macro=  <meta>  {
+			    =name= STRING 
+			    (=parameter= <STRING>)*
+			    =block= <block>
+                          }
+
+<alias>              :: =aliased=(<meta> ) {
+                            =name= STRING
+                            =specName= STRING
+                         }
+
+<operator>           :: =operator= <meta>  {
+			    =name= STRING 
+                            (=parameter= <STRING>)*
+			    <operatorParameter>* 
+			    =expression= <expression>
+			 }
+
+# Block && statements
+<block>              :: <statement>*
+<statement>          :: <outputStmt> | <skipStmt> | <labelStmt> |  
+                        <callService> | <callMacro> | <conditionalStmt> | <assignTo> | 
+                        <ReturnValue> | <Return> | <jump> | <aborted> | <done> | <failure>
+
+<skipStmt>           :: =nop=
+<labelStmt>          :: =label=
+<outputStmt>         :: =output= <expression>*
+
+<assignTo>           :: =assignTo= {
+                          =variable= <parameterRVal>
+                          =rval= <expression>
+                        } |
+                        =assignTo= {
+                          =variable= <reference>
+                          =rval= <expression>
+                        }
+
+<reference>          :: <referenceLocation> ('.' STRING)*
+<referenceLocation>  :: <txParameterRef> | <simpleRef> | <variableRef>
+<simpleRef>          :: STRING
+<variableRef>        :: <meta> STRING 
+<txParameterRef>     :: <meta> STRING STRING
+
+<lval>               :: <parameterReference> | <variableReference>
+
+<callService>        :: =callService= <meta> <name> <operation>  {
+			     (=parameter= <expression>)*
+		         }
+<callMacro>          :: =callMacro= <meta> <name>  {
+			     (=parameter= <expression>)*
+			 }
+<conditionalStmt>    :: =ifThen= <expression> <block> ( =elseThen <block> )?
+
+
+<jump>               :: =jump= STRING
+
+<aborted>            :: =aborted= <interfaceOpration>
+<done>               :: =done= <interfaceOpration>
+<failure>            :: =done= <interfaceOpration>
+
+<return>             :: =ret= <booleanExpression> 
+
+<ReturnValue>        :: =returnValue= STRING <expression> 
+
+# expressions
+<expression>         :: <constantExpression> | 
+                        <referenceExpression> | 
+                        <tlaExpression> | 
+                        <operatorCall> |
+                        <binaryExpression>
+                        <unaryExpression>
+
+<operatorCall>       :: *TBD*
+
+<referenceExpression>:: =reference= <reference>
+
+
+<operatorExpression> :: =parameterReference= STRING
+
+<tlaExpression>      :: =tlaExpression= {
+			       =template= <tlaTemplate>
+			       =args= <expression>*
+			  }
+<tlaTemplate>        :: =:set= | =:sequence= | =:nil= | =:parenthesis=
+
+<binaryExpression>   :: =binaryExpression= {
+                            =lval= <expression>
+                            =op= <binaryOp>
+                            =rval= <expression>
+                        }
+
+<unaryExpression>   :: =unaryExpression= {
+                            =op= <unaryOp>
+                            =expr= <expression>
+                        }
+
+<binaryOp>           :: =:plus= | =:minus= | =:equal= | =:mult= | =:div= | =:lt= | =:le= 
+<unaryOp>            :: =:not
+
+<constantExpression> :: <integerExpression> | <stringExpression>  | <booleanExpression> 
+<booleanExpression>  :: <trueExpression>  | <falseExpression> 
+<trueExpression>     :: TRUE
+<falseExpression>    :: FALSE
+<stringExpression>   :: STRING
+<integerExpression>  :: INT
+
+
+# Namespace meta
+<meta>               :: <sbuilderMetatype> | STRING
+<name>               :: STRING
+<domainName>         :: STRING
+<definitionName>     :: STRING
+<sbuilderMetatype>   :: 'domains' | 'service_implementation' | 'service_completion' | 'framework-svc'
+
+#+END_EXAMPLE
+
+TLA-templates
+
+#+BEGIN_EXAMPLE
+tlaSet(expression)   :: tlaExpression {
+                            tempalate :tlaSet
+                            args expr
+                         }
+
+
+tlaNil               :: tlaExpression {
+                            tempalate :nil
+                         }
+
+tlaSequence(expr)    :: =tlaExpression= {
+                            tempalate :sequence
+                            arg= expr
+                         }
+tlaParenthesis(expr) :: =tlaExpression= {
+                            tempalate :parenthesis
+                            arg= expr
+                         }
+
+tlaPlainname         :: =tlaPlainname= STRING
+tlaRecodrIndex       :: =tlaRecordIndex= STRING <tlaExpression>
+tlaIF                :: =tlaIF= <tlaExpression> <tlaExpression> <tlaExpression>
+tlaEXCEPT            :: =tlaEXCEPT= STRING <tlaExpression>
+tlaSetGenerator      :: =tlaEXCEPT= <tlaExpression> STRING <tlaExpression>  
+tlaSetIterate(v,set) :: tlaExpression {
+                            tempalate :set_iterate
+                            args v
+                            args set
+                         }
+
+=plus=(l,r)          :: =binaryExpression= { =lval= l; =op= :plus; =rval= r }
+=minus(l,r)          :: =binaryExpression= { =lval= l; =op= :minus; =rval r }
+=equal(l,r)          :: =binaryExpression= { =lval= l; =op= :equal; =rval= r }
+=unequal(l,r)        :: =binaryExpression= { =lval= l; =op= :unequal; =rval= r }
+
+#+END_EXAMPLE

data/lib/meta/etc.rb

@@ -0,0 +1,265 @@
+require "sbuilder"
+module Sbuilder
+  module Al
+    module Meta
+      module Etc
+
+        ## Define lambdas for plantUml strings
+        STR_CLASSNODE = 
+          lambda do |kl, attributes=false|
+          "
+            class #{kl.respond_to?(:demodulize) ? kl.demodulize : kl } {
+              #{ kl.attributes.join("\n") if (attributes && kl.respond_to?(:attributes) ) }
+            }
+            "
+        end
+
+        STR_MODULENODE = 
+          lambda do |modu, attributes=false|
+          "
+            package #{modu.to_s.split("::").last } {
+            }
+            "
+        end
+        
+        
+        STR_EDGE = 
+          lambda do |kl, chld|
+          "#{kl.respond_to?(:demodulize) ? kl.demodulize : kl } <|-- #{chld.respond_to?(:demodulize) ? chld.demodulize : chld}"
+        end
+        
+        
+
+        # @return [Array<class>] Class hierarchy recursable using
+        # 'descendants' method without classess below array 'prune'
+        #
+        # @param klass [class] to start of hierarchy collection
+        #
+        # @param classes [Array<class>] collected so far
+        #
+        # @param prune [Array<class>] hierarchy pruned away below the
+        # classes in 'prune' - array
+        def self.hierarchy( klass, prune=[], classes=[] )
+          classes += klass.descendants.map { |kl| hierarchy( kl, prune, classes ) }.flatten  if  klass.respond_to?( :descendants ) && !prune.include?(klass)
+          classes = classes <<  klass
+          classes.uniq
+        end
+
+        # @return [Array<class>] of ancestor classes defining
+        # ':descendants' method
+        def self.ancestors( klass, classes=[] )
+           if klass.superclass.respond_to?( :descendants )
+            classes += ancestors( klass.superclass, classes )
+            classes.unshift( klass.superclass)
+          end
+          classes
+        end
+
+        # @return [Array<[Class,Class]>] Array of child, parent arrays
+        def self.parentEdges( klasses )
+          klasses.reduce([] ) do |memo, kl|
+            # puts "kl.class.ancestors=#{kl.class.ancestors}"
+            #memo = memo + ((klasses - [kl]) & kl.class.ancestors ).map{ |kl2| [kl,kl2]}
+            memo << [kl,kl.superclass] if klasses.include?(kl.superclass)
+            memo
+          end
+        end
+
+        # @return [Array<Class>] of classes in myModule, excluding
+        # classes in 'excluded'
+        def self.moduleClasses( myModule, excluded=[] )
+          myModule.
+            # acces module constants
+            constants.
+            # select not excluded classes 
+            select do |c| 
+            klass = myModule.const_get(c, inherit=false)
+            klass.is_a?(Class)  && ( klass.ancestors & excluded ).empty? 
+          end.
+            # map 'em class symbols to Class objects
+            map { |c| myModule.const_get(c, inherit=false) }
+
+        end
+
+        # @return [Array<Module>] of Module in myModule, excluding
+        # classes in 'excluded'
+        def self.moduleSubModules( myModule, excluded=[] )
+          myModule.constants.
+            map { |c| myModule.const_get(c, inherit=false) }.
+            select { |c|  c.class == Module } #   && !excluded.include?( c )  }
+          # # map 'em class symbols to Class objects
+            # map { |c| myModule.const_get(c, inherit=false) }
+        end
+
+
+        ##
+        # Render 'alObject' as a string
+        #
+        # @param alObject [AlObject] AL language object to render as atring
+        #
+        def self.snippetString( alObject ) 
+          Sbuilder::Al::Plugin::Controller.start.alObject2tlaString( alObject )
+        end
+
+        # Class overriding configuration reader for Sbuilder
+        class MyController < Sbuilder::Controller
+          def initialize( factory, sbuilderConfigs )
+            @sbuilderConfigs = sbuilderConfigs
+            super( factory )
+          end
+          # Method to reaturn 'sbuilder.yaml' sbuilder overridden
+          def getConfigSbuilder
+            @sbuilderConfigs
+          end
+        end
+        
+        
+
+        ##
+        # Render 'apiElement' as a string
+        #
+        # @param apiElement [Hash] A hash to define api element
+        #
+        def self.alObject2ApiString( alObject,  alObjectCtx = [])
+
+          
+          # Configure
+          apiType2Config = {
+            :domain => {
+              "modelData" => "domains",
+              "template" => "domains.mustache",
+            },
+            :definition => {
+              "modelData" => "definitions",
+              "template" => "definition_types.mustache",
+            },
+          }
+
+          # Init sbuilder factory & controller & define configuration
+          sbuilderConfigs = {
+            "setups" => [
+              {
+                "setupDirectory": "example"
+              }
+            ]
+          }
+          factory = Sbuilder::Factory.getFactory()
+          sbuilderController = MyController.new( factory, sbuilderConfigs )
+          
+          # use sbuilder factory to instantiate API plugin && configure it
+          apiFacade = factory.getApiFacade(sbuilderController)
+          plugin = factory.getLoaderPlugin( Sbuilder::Al::Plugin::Plugin )
+          plugin.setFacade(apiFacade)
+
+          # Add translated element of interest to plugin 'application'
+          # (=state kept in controller)
+          apiElement = plugin.controller.alObject2tlaSexp( alObject )
+          raise "Expect :apiType property in #{apiElement}" unless apiElement.has_key?( :apiType )
+          
+          apiElementCtx = alObjectCtx.map{ |o| plugin.controller.alObject2tlaSexp( alObject ) }
+          
+          plugin.controller.addAlObjects( apiElementCtx )
+          plugin.controller.addAlObjects( apiElement )
+
+          # sbuilderController.load
+
+          sbuilderController.baseExtensionDefine
+
+          # invoke plugin API loader interface to pass data to sbuilder
+          plugin.load( nil )
+          
+          # After load prepare for snippets stuff
+          sbuilderController.resolve
+          sbuilderController.initializeSymbolTableMetaModel
+          sbuilderController.initializeSymbolTable
+          
+
+          # render template in sbuilder
+          setupName = "example"
+          outputPath = "output"
+          # choose template && data which to show
+          raise "Unknown apiType '#{apiElement[:apiType]}', valid apitype #{apiType2Config.keys.join(',')}" if apiType2Config[apiElement[:apiType]].nil?
+          generateDef = { "template" => apiType2Config[apiElement[:apiType]]["template"],
+                          "desc"=>"example",
+                          "modelData" => apiType2Config[apiElement[:apiType]]["modelData"],
+                        }
+          mustache = sbuilderController.prepareRender( setupName )
+          sbuilderController.generateTemplateString( setupName, outputPath, generateDef, mustache)
+        end
+        
+        
+
+        # @return [Array<String>] Class hierarchy edges and nodes for
+        # class 'klass' with classes  in 'prune'
+        #
+        # @param attributes [Boolean] true when include attributes to class default
+        #
+        # @param parents [Boolean] true when include also parent to hierarchy
+        def self.plantUmlClassHierarchy( klass, prune=[], attributes=false, parents=false )
+          klass = [klass] unless klass.is_a?( Array )
+
+          # Find all classes in hierarchy 'klass'
+          klassesInHierarchy =
+            klass.map do |kl|
+             hierarchy( kl, prune )
+          end.flatten
+
+          ## Create edge strings for hierarch down
+          hierarchyEdges =
+            klassesInHierarchy.
+            # do not look into descendants of a pruned class
+            select{ |kl| !prune.include?(kl) }.
+            map do |kl|
+              # kl.descendants.map { |chld| "#{kl.demodulize} <|-- #{chld.demodulize}" }
+              kl.descendants.map { |chld| STR_EDGE.call( kl, chld ) }
+          end.flatten
+
+          ## Create node string
+          hierarchyNodes =
+            klassesInHierarchy.map do |kl|
+            STR_CLASSNODE.call( kl, attributes )
+          end
+
+
+          parentNodes = []
+          parentEdges = []
+
+          if ( parents ) then
+
+            # string for all parent nodes
+            parentNodes = klass.map do |kl|
+              # find all ancestors for all classes
+              ancestors( kl )
+            end.flatten.uniq.map do |kl|
+              # and a node for them
+              STR_CLASSNODE.call( kl, attributes )
+            end
+
+            parentEdges = klass.reduce([]) do |memo,kl|
+
+              klWithAncestors = [kl] + ancestors( kl )
+              # puts( "klWithAncestors=#{klWithAncestors.join(',')}")
+              memo << (0..(klWithAncestors.length-2)).map do |i|
+                # puts( "i=#{i}, klWithAncestors.length=#{klWithAncestors.length}, klWithAncestors[i]=#{klWithAncestors[i]}, #{klWithAncestors[i+1]}")
+                # template 'strEdge' produces parent/sub-class edge
+                # [ klWithAncestors[i+1], klWithAncestors[i] ]
+                STR_EDGE.call(klWithAncestors[i+1], klWithAncestors[i])
+              end
+              memo
+            end.reject{ |arr| arr.empty? }
+            # puts( "parentEdges=#{parentEdges.length}=#{parentEdges.join(',')},#{parentEdges}")
+
+            
+          end # parents
+
+          # make edges unique
+          parentEdges = parentEdges.flatten.uniq
+          hierarchyEdges = hierarchyEdges.flatten.uniq
+          
+          hierarchyNodes + parentNodes +  parentEdges + hierarchyEdges
+        end
+        
+      end
+    end
+  end # Al
+end # Sbuilder