tla-sbuilder 0.2.2 → 0.3.4

data/lib/utils/{cache_lines.rb → fileio.rb}

@@ -2,9 +2,15 @@ module Sbuilder
   
   module Utils
 
-    module CacheLines
+    module FileIo
+
+      def self.write( path, data  )
+        File.open( path, "w" ) { |f| f.write( data ) }
+      end
+      
 
       # write lines in cache file
+      # @todo use Sbuilder::Utils::File.write
       def self.cache_write( cacheFile, data  )
         File.open( cacheFile, "w" ) { |f| f.write( data ) }
       end
@@ -19,3 +25,4 @@ module Sbuilder
     end
   end
 end
+

data/lib/utils/logger.rb

@@ -30,8 +30,9 @@ module Sbuilder
         @@logfile = options[:logfile] || File.join( Dir.getwd, LOGFILE )
       end
 
-      def getLogger( progname, options={} ) 
+      def getLogger( progname=nil, options={} ) 
 
+        progname = self.class.name.split('::').last if progname.nil?
         level = get_level( options )
 
         if level.nil? 

data/lib/utils/powerset.rb

@@ -0,0 +1,13 @@
+
+module Sbuilder
+    
+  module Powerset
+
+    # @see http://www.entish.org/wordpress/?p=676
+    def self.powerset( arr )
+        return arr.inject([[]]){|c,y|c.inject([]){|r,i|r+=[i,i+[y]]}}
+      end
+
+  end
+
+end

data/lib/utils/validate.rb

@@ -0,0 +1,38 @@
+module Sbuilder
+  
+  module Utils
+
+    module Validate
+
+      # validate 'defintionHash' all 'required'/only 'allowed' props set
+      #
+      # @param [Hash] hash to validate
+      #
+      # @param [String:Array] required array of mandatory properties
+      #
+      # @param [String:Array] allowed optional list of allowed properties
+      #
+      # @exception when validation fails 
+      def self.validateProperties( defintionHash, required, allowed=[] )
+        allowed = required unless allowed
+        allowed = (required + allowed).uniq
+        
+        
+        missingProps = required - defintionHash.keys
+        raise ValidateException.new "Missing properties #{missingProps} in #{defintionHash} - required #{required}" if missingProps.any?
+
+        invalidProps = defintionHash.keys - allowed 
+        raise ValidateException.new "Unknown properties #{invalidProps} in #{defintionHash} - allowed #{allowed}" if invalidProps.any?
+
+      end
+
+      def self.oneOf( defintionHash, propList, min=1, max=1 )
+        props = propList.select {|prop| defintionHash.has_key?(prop) }.length
+        raise ValidateException.new "Must give min #{min} - max #{max} #{propList} in #{defintionHash}" unless  props >= min && props <= max
+      end
+
+      
+    end
+    
+  end
+end

data/mustache/cfg/const_def.mustache

@@ -2,6 +2,8 @@
 (* Declare magic constants *)
 CONSTANT WildCard = WildCard
 CONSTANT Nil = Nil
+CONSTANT Abort = Abort
+
 
 (* Pluscal sets 'defaultInitValue' for unitialized variables *)
 CONSTANT defaultInitValue <- Nil

data/mustache/cfg/macro_run.mustache

@@ -1,7 +1,4 @@
 (* 'enabled' macro check is process enables *)
-CONSTANT ProcessEnabled <- RunProcessEnabled
-CONSTANT ProcessRunning <- RunProcessRunning
-CONSTANT ProcessParameter <- RunProcessParameter
-CONSTANT ProcessesToRun <- RunProcessesToRun
+
 CONSTANT TickNext <- RunTickNext
 CONSTANT InTransaction <- RunInTransaction

data/mustache/data-model-header.mustache

@@ -7,6 +7,7 @@
 
 
 <!-- ul>
+    <li><a href="#Metatypes">Metatypes</a></li>
     <li><a href="#interfaces">Model interfaces</a></li>
     <li><a href="#definitions">Model definitions</a></li>    
     <li><a href="#domains">Model domains</a></li>

data/mustache/definition_types.mustache

@@ -5,11 +5,36 @@ Defined types {{META.desc}}
  - template  {{META.template}}
 *******************************************************************)
 
-{{#definitions}}
-{{>name_definition_type.mustache}} == {{!
+{{#definitions}}{{!
+
+Add fixed string 'DEFINITION: definitions:', which can be used
+to extract definition from specification code
+
+}}
+
+(* DEFINITION: definitions:{{definition_name}} *)
+{{#SPEC_NAME}}definitions.{{definition_name}}{{/SPEC_NAME}} == {{!
 
     Start of definition.
 
+    Function definition 
+    
+}}{{#isFunction}}[ {{!
+
+   Iterate function domain
+
+}}{{#domainParameters}}{{#SPEC_NAME}}domains.{{type}}{{/SPEC_NAME}}{{_comma}}{{/domainParameters}} -> {{!
+
+   Iterate function range
+
+}}{{#rangeParameters}}{{#SPEC_NAME}}domains.{{type}}{{/SPEC_NAME}}{{_comma}}{{/rangeParameters}} ]{{/isFunction}}{{!
+
+    Normal definition i.e. not a function starts
+
+
+}}{{^isFunction}}{{!
+
+
     Add 'SUBSET ' for an array type
 
 }}{{#isArray}}SUBSET {{/isArray}}{{!
@@ -21,7 +46,7 @@ Defined types {{META.desc}}
     add fiels from #parameter_definitions
 }}
 {{#parameter_definitions}}
- {{>name_parameter_definition.mustache}}: {{#isArray}}SUBSET {{/isArray}}{{>name_parameter_type.mustache}}{{_comma}}
+ {{>name_parameter_definition.mustache}}: {{#isArray}}SUBSET {{/isArray}}{{#SPEC_NAME}}{{metatype}}.{{type}}{{/SPEC_NAME}}{{_comma}}
 {{/parameter_definitions}}{{!
 
      end of definition
@@ -35,6 +60,11 @@ Defined types {{META.desc}}
 
    Comment in the end
 
-}} \* definition '{{definition_name}}'
+}}{{/isFunction}}{{!
+
+    Add fixed END-OF-DEFINTION to mark end of definition
+
+}}
+(* END-OF-DEFINTION {{definition_name}}{{#isFunction}} (function type!){{/isFunction}} *)
 
 {{/definitions}}

data/mustache/domains.mustache

@@ -14,7 +14,7 @@
  ******************************************************************)
  
 {{#domains}}
-CONSTANTS {{>name_domain.mustache}} 
+CONSTANTS {{#SPEC_NAME}}domains.{{domain_name}}{{/SPEC_NAME}}
 {{/domains}}
 
 

data/mustache/domains_assign.mustache

@@ -16,7 +16,7 @@
  ******************************************************************)
 
 {{#domains}}
-CONSTANT {{>name_domain.mustache}}  <- Run_{{>name_domain.mustache}}
+CONSTANT {{#SPEC_NAME}}domains.{{domain_name}}{{/SPEC_NAME}}  <- Run_{{#SPEC_NAME}}domains.{{domain_name}}{{/SPEC_NAME}}
 {{/domains}}
 
 

data/mustache/infrastructure-service-init.mustache

@@ -26,7 +26,7 @@ InfrastructureServiceInit == {{!
     - output: <interface_name> |-> Nil, 
 
 
-}}{{#infrastructureServices}} {{>name_process.mustache}} |-> InfrastructureServiceResponse( Nil, Nil ){{_comma}}{{/infrastructureServices}}{{!
+}}{{#infrastructureServices}} {{#SPEC_NAME}}infra_services.{{interface_operation}}{{/SPEC_NAME}} |-> InfrastructureServiceResponse( Nil, Nil ){{_comma}}{{/infrastructureServices}}{{!
 
     Infrastructure-services defined && end
 

data/mustache/interface_processes.mustache

@@ -13,33 +13,39 @@ Interfaces generated  {{META.desc}}
 
 {{#interfaces}}
 (* Process {{interface_operation}} *)
-fair process ({{>name_process.mustache}}="{{interface_operation}}") {
-     {{>name_process.mustache}}_enter: while (TRUE) {
-         enable( "{{>name_process.mustache}}" );
+fair process ({{#SPEC_NAME}}processes.{{interface_operation}}{{/SPEC_NAME}}="{{interface_operation}}") {
+     {{#SPEC_NAME}}processes.{{interface_operation}}{{/SPEC_NAME}}_enter: while (TRUE) {
+         enable( "{{#SPEC_NAME}}processes.{{interface_operation}}{{/SPEC_NAME}}" );
 	 (* enable next process to run parallel *)
 	 \* process_done( "{{interface_operation}}" );
-	 with ( _input \in { t \in ProcessParameterInput( {{>name_interface_type.mustache}} ) : ProcessParameterBind( t ) } ) {
+	 with ( _input \in { t \in ProcessParameterInput( {{#SPEC_NAME}}interface_types.{{interface_operation}}{{/SPEC_NAME}} ) : ProcessParameterBind( t ) } ) {
 	    \* PREFERENCES.debug-output: {{PREFERENCES.debug-output}}
-	    {{^PREFERENCES.debug-output}}\* {{/PREFERENCES.debug-output}}print <<"Default process {{>name_process.mustache}} for operation '{{interface_operation}}',tick=", currentTime>>;
+	    {{^PREFERENCES.debug-output}}\* {{/PREFERENCES.debug-output}}print <<"Default process {{#SPEC_NAME}}processes.{{interface_operation}}{{/SPEC_NAME}} for operation '{{interface_operation}}',tick=", currentTime>>;
 	    {{^implementation}}
 	    {{^PREFERENCES.debug-output}}\* {{/PREFERENCES.debug-output}}print <<"   - input=>", _input >>;	    
-	    (* print <<"   - {{>name_interface_type.mustache}}=>", {{>name_interface_type.mustache}} >>; *)
+	    (* print <<"   - {{#SPEC_NAME}}interface_types.{{interface_operation}}{{/SPEC_NAME}} =>", {{#SPEC_NAME}}interface_types.{{interface_operation}}{{/SPEC_NAME}} >>; *)
 	    {{/implementation}}
 	    {{#parameter_definitions.length}}
 	    (* Valid input type? - _input must match type of API request *)	    
-	    assert(  _input \in {{>name_interface_type.mustache}} );{{/parameter_definitions.length}}{{!
+	    assert(  _input \in {{#SPEC_NAME}}interface_types.{{interface_operation}}{{/SPEC_NAME}} );{{/parameter_definitions.length}}{{!
 
 	       else : no parmaeter
 
 	    }}{{^parameter_definitions.length}}
 	    (* Valid input type? - API configuration did not define any parameters - must have Nil for _input.dummy: *)
 	     assert(  _input.dummy = Nil );{{/parameter_definitions.length}}	    
-	    {{#implementation}}{{implementation}}( _input );{{/implementation}}
+	    {{#implementation}}{{#SPEC_NAME}}service_implementation.{{interface_operation}}{{/SPEC_NAME}}( _input );{{/implementation}}
 	 }; \* with _input
 	 (* enable next process - after current process *)
-	 {{>name_process.mustache}}_exit: process_done( "{{interface_operation}}" );
+	 {{#SPEC_NAME}}processes.{{interface_operation}}{{/SPEC_NAME}}_exit:
+	     {{#completion}}{{completion}}( "{{interface_operation}}" );
+	     {{/completion}}{{!
+
+	       above adds call to completion macro (to simulate transactions) 
+
+	     }}process_done( "{{interface_operation}}" );
      } \* while(TRUE)
-} \* failr process {{>name_process.mustache}}
+} \* fair process {{#SPEC_NAME}}processes.{{interface_operation}}{{/SPEC_NAME}}
 
 {{/interfaces}}
 

data/mustache/interface_types.mustache

@@ -13,17 +13,25 @@ Interface input types: {{META.desc}}
  - template  {{META.template}}
 *******************************************************************)
 
-{{#interfaces}}
-{{>name_interface_type.mustache}} == [{{#parameter_definitions}}
-     {{>name_parameter_definition.mustache}}: {{>name_parameter_type.mustache}}{{_comma}}{{/parameter_definitions}}{{!
+{{#interfaces}}{{!
+
+    Add fixed string 'REQUEST: which can be used
+    to extract definition from specification code
+}}
+(* REQUEST: {{interface_operation}} --> TLA process: {{#SPEC_NAME}}processes.{{interface_operation}}{{/SPEC_NAME}} *)
+{{#SPEC_NAME}}interface_types.{{interface_operation}}{{/SPEC_NAME}} == [{{#parameter_definitions}}
+     {{>name_parameter_definition.mustache}}: {{#isArray}}SUBSET {{/isArray}}{{#SPEC_NAME}}{{metatype}}.{{type}}{{/SPEC_NAME}}{{_comma}}{{/parameter_definitions}}{{!
 
      Empty parameter definition (passes swagger schema validation).
      
      ouput 'dummy : {Nil}'
 
 }}{{^parameter_definitions.length}}dummy: {Nil}{{/parameter_definitions.length}}
-] \* operation '{{interface_operation}}' --> process '{{>name_process.mustache}}'
+]{{!
 
+   Add fixed string END-OF-REQUEST 
+}}
+(* END-OF-REQUEST *)
 {{/interfaces}}
 
 \* end of Interface input types
@@ -35,18 +43,36 @@ Interface response types: {{META.desc}}
 *******************************************************************)
 
 {{#interfaces}}
-{{>name_interface_response_type.mustache}} =={{!
+{{!
+
+    Add fixed string 'RESPONSE: which can be used
+    to extract definition from specification code
+
+
+}}
+(* RESPONSE: {{interface_operation}} --> TLA process: {{#SPEC_NAME}}processes.{{interface_operation}}{{/SPEC_NAME}} *)
+{{#SPEC_NAME}}interface_response_types.{{interface_operation}}{{/SPEC_NAME}} =={{!
 
     When something defined as a response i.e. 'response_definitions.length' exists
 
-}}{{#response_definitions.length}}[{{/response_definitions.length}}{{#response_definitions}}
-                {{>name_parameter_definition.mustache}}: {{>name_parameter_type.mustache}}{{_comma}}{{/response_definitions}}
-{{#response_definitions.length}}]{{/response_definitions.length}}{{!
+}}{{!
+   No new line here
+}}{{#response_definitions.length}} [
+{{/response_definitions.length}}{{#response_definitions}}    {{>name_parameter_definition.mustache}}: {{#SPEC_NAME}}{{metatype}}.{{type}}{{/SPEC_NAME}}{{_comma}}
+{{/response_definitions}}{{!
+   NO new line here
+}}{{#response_definitions.length}}]{{/response_definitions.length}}{{!
 
-    When no response defidined i.e. 'response_definitions.length' exists
+    When no response defined i.e. 'response_definitions.length' return false
 
-}}{{^response_definitions.length}}{ Nil }{{/response_definitions.length}}{{!
+}}{{^response_definitions.length}} { Nil }{{/response_definitions.length}}{{!
 
     Put a comment in the end
-}} \* interface '{{interface_name}}' response type
+    
+}}{{!
+
+    Add fixed string END-OF-RESPONSE: to mark end of response
+}}
+(* END-OF-RESPONSE *)
+
 {{/interfaces}}

data/mustache/operator-infrastructure-service.mustache

@@ -6,7 +6,7 @@
 ******************************************************************)
 InterfaceOperation2ProcessName( op ) == CASE op = "xxXXxx" -> Nil {{! to ease generation
 }}{{#infrastructureServices}}
-       [] op = "{{interface_operation}}" -> "{{>name_process.mustache}}" {{/infrastructureServices}}
+       [] op = "{{interface_operation}}" -> "{{#SPEC_NAME}}infra_services.{{interface_operation}}{{/SPEC_NAME}}" {{/infrastructureServices}}
        [] OTHER -> Assert( FALSE, "Unknown infrastructure service" ) 
        
 

data/mustache/resources/schedule_operator_new_step.tla

@@ -0,0 +1,8 @@
+(* Create a step entry to schedule in +steps+ sequence
+*  @param procci process identifier to schedule
+*  @param procInput an elment in process input set to pass to the process
+*  @param ctx context where to resume, Nil if no resume
+*)
+NewStep( procci, procInput, ctx  ) == [ process  |-> procci, bindRule |-> WildCard ,bindSet  |-> procInput, ctx  |-> ctx ]
+
+     

data/mustache/resources/schedule_process_macro.tla

@@ -0,0 +1,37 @@
+(*
+
+ Schedule a call for an external process +called+ with +input+, and
+ +resume+ back to the calling process in context +resumeCtx+.
+
+ Implementation adds two step entries in +steps+ sequence.
+ Entries cannot be made to position 1 because it represents
+ currently running process, which get shifted away the sequnce
+ once the process finishes.
+
+*)
+
+macro schedule_process_mac( called, input, resume, resumeCtx ) {
+
+    \* NOTICE!!: call and resume steps always successive elements
+    \* The only option is to apped to +steps+
+    if ( Cardinality( { p \in 1..Len(steps) :  \A s \in steps[p]: s.ctx = Nil }  ) <= 1  ) {
+	  steps := steps \o
+		  << { NewStep( called, input, Nil ) },
+		     { NewStep( resume, Nil, resumeCtx ) } >>;
+    } else {
+         \* Non-deteministic choice where to put
+	 with ( pos \in { p \in 2..Len(steps) : \A s \in steps[p]: s.ctx = Nil  } ) {
+	   steps := IF pos = Len(steps) THEN
+		     steps \o
+			<< { NewStep( called, input, Nil ) },
+			   { NewStep( resume, Nil, resumeCtx ) } >>
+		      ELSE
+			 SubSeq( steps, 1, pos-1 )  \o
+			     << { NewStep( called, input, Nil ) },
+				{ NewStep( resume, Nil, resumeCtx ) } >> \o         
+			 SubSeq( steps, pos, Len(steps))
+		    ;
+	 }; \* with
+   }; \* else
+  skip;
+}

data/mustache/resources/schedule_process_procedure.tla

@@ -0,0 +1,22 @@
+(*
+
+   Schedule process +input.called+ with +input.input+, and resume back
+   to currently running process +step+ to pc of +self+ ProcDef.
+
+   Creates a record with +ret_ctx+ property, which calling process can
+   use to restore its context, adds call step and resume step to
+   +steps+ sequence.
+
+*)
+
+procedure schedule_process_proc( input ) {
+
+schedule_process_start:
+
+     schedule_process_mac(
+          input.called,  input.input, step,
+	  [ ret_ctx |-> [ stack[self][2] EXCEPT !.pc = stack[self][1].pc ] ]
+      );
+
+     return;
+}

data/mustache/resources/schedule_throw.tla

@@ -0,0 +1,16 @@
+(*
+   Throw exception and exit current process via +exitLocation+.
+
+   Modify +stack+ top to return from current procedure to
+   +exitLocation+, and retain stack bottom to return from current
+   process.  *)
+
+macro schedule_throw( exitLocation ) {
+
+
+  stack := <<
+       [ stack[self][1] EXCEPT !.pc = exitLocation ],
+         stack[self][ Len(stack[self]) ]
+           >>;
+
+}

data/mustache/setup/domains_run.mustache

@@ -14,8 +14,14 @@ Assign values to skeleton domains: {{META.desc}}
 *******************************************************************)
 
 (* Domains for {{META.setup}} start *)
-{{#domains}}
-Run_{{>name_domain.mustache}}    == { {{#domain_values}}"{{>name_domain_value.mustache}}"{{_comma}} {{/domain_values}} } {{#nil_value}} \cup {Nil} {{/nil_value}} \*
+{{#domains}}{{!
+
+     iteratete 'domain_values' && output 'value'
+     'tlaBaseType': wrap domain values in set brackets
+     'nil_value' : union { Nil }
+
+}}
+Run_{{#SPEC_NAME}}domains.{{domain_name}}{{/SPEC_NAME}} == {{^tlaBaseType}}{ {{/tlaBaseType}}{{#domain_values}}{{{value}}}{{_comma}} {{/domain_values}} {{^tlaBaseType}} }{{/tlaBaseType}} {{#nil_value}} \cup {Nil} {{/nil_value}}
 {{/domains}}
 (* Domains for {{META.setup}} end *)