tla-trace-filter 0.0.3

data/lib/tla-trace-filter.rb

@@ -0,0 +1,6 @@
+require_relative( 'util/logger.rb')
+require_relative( 'filter/filter.rb')
+require_relative( 'parser/parser.rb')
+require_relative( 'render/render.rb')
+
+#

data/lib/util/logger.rb

@@ -0,0 +1,82 @@
+module TlaTraceFilter
+    module Util
+
+      require 'logger'
+
+      # see http://hawkins.io/2013/08/using-the-ruby-logger/
+
+      module MyLogger
+        
+        # no logging done
+
+        class NullLoger < Logger
+          def initialize(*args)
+          end
+
+          def add(*args, &block)
+          end
+
+          def debug?
+            false
+          end
+        end
+
+        @@logfile = nil                          # absolute path to log file
+        LOGFILE="tla-trace-filter.log"
+
+        def logfile( options ) 
+          return @@logfile if @@logfile
+          @@logfile = options[:logfile] || File.join( Dir.getwd, LOGFILE )
+          @@logfile
+        end
+
+        def getLogger( progname=nil, options={} )
+
+
+          progname = self.class.name.split('::').last if progname.nil?
+          level = get_level( options )
+
+          if level.nil? 
+
+            return NullLoger.new 
+
+          else
+            
+            logger = Logger.new( logfile(options) )
+            logger.level=level
+            logger.progname = progname
+            return logger
+
+          end
+
+        end # getLogger
+        
+
+        # ------------------------------------------------------------------
+        private
+
+        def get_level( options ) 
+
+          level_name = options && options[:log] ? options[:log] : ENV['LOG_LEVEL']
+
+          level = case  level_name
+                  when 'warn', 'WARN'
+                    Logger::WARN
+                  when 'info', 'INFO'
+                    Logger::INFO
+                  when 'debug', 'DEBUG'
+                    Logger::DEBUG
+                  when 'error', 'ERROR'
+                    Logger::ERROR
+                  else
+                    nil
+                  end
+
+          return level
+        end
+
+      end
+      
+    end
+  end
+      

data/mustache/add-links-interface.mustache

@@ -0,0 +1,33 @@
+{{!
+
+    Output link to interface source module
+    (If it can be found in 'interface.source.sourceModule')
+
+}}{{!
+
+Output hyperlink  to source.sourceModule/source.sourceLine if possible
+
+}}{{#interface.source.sourceModule}}
+Interface operation '{{interface.interface_operation}}' for step '{{{parsed.state_space.step }}}' transition label '{{pc}}' defined in source file:
+{{options.src_dir}}/{{interface.source.sourceModule}}:{{!
+
+    command line 'options.solc_line' tweaks intepretation of 'sourceLine'
+    --> true : to count characters starting from start of file
+    --> false: use interface.source.sourceLine
+
+}}{{^options.solc_line}}{{interface.source.sourceLine}}{{/options.solc_line}}{{#options.solc_line}}{{SOLC_LINE}}{{/options.solc_line}}{{!
+
+   continue with source column
+
+}}:{{interface.source.sourceColumn}}: {{{parsed.line}}}
+{{/interface.source.sourceModule}}{{!
+
+    else no hyperlink
+    
+}}{{^interface.source.sourceModule}}
+could not resolve source file for '{{interface.interface_operation}}'
+{{/interface.source.sourceModule}}{{!
+Local Variables:
+require-final-newline: nil
+End:
+}}

data/mustache/add-links-state-dump.mustache

@@ -0,0 +1,28 @@
+{{!
+
+   State dump
+
+}}{{#options.state_dump}}
+State dump: interface_started={{interface_started}}, interface_executing={{interface_executing}}
+
+Executing in:
+ - interfaceOperation: {{interface_operation}}
+ - pc/label: {{pc}}
+
+
+{{{parsed.state_space}}}
+
+{{/options.state_dump}}{{!
+
+   else
+
+}}
+{{^options.state_dump}}{{!
+
+     No state dump requested
+     
+}}{{/options.state_dump}}{{!
+Local Variables:
+require-final-newline: nil
+End:
+}}

data/mustache/add-links-transition.mustache

@@ -0,0 +1,14 @@
+{{!
+ Template to output hyperlink to tla specification code module 'model.tla'
+ found in directory 'options.tla_dir'
+
+ - references options and parsed
+ - 
+ 
+}}
+
+{{options.tla_dir}}/model.tla:{{parsed.actionLine}}: transition for {{{parsed.line}}}{{!
+Local Variables:
+require-final-newline: nil
+End:
+}}

data/mustache/add-links.mustache

@@ -0,0 +1,43 @@
+{{!
+
+  Root Mustache template
+
+  Can access to following data:
+  
+  :options: options passed from command line
+
+  :interface_started : boolean set to true when 'X_start'
+                       transition seen
+
+  :interface_executing : boolean set to true not 'X_start' && 
+                         valid interface executing
+
+  :interface_operation: string of interface operations executing, ?? if not known
+
+  :pc        : transition label identifying pc, ?? if not known
+
+  :interface : interface definition for transition step interface with
+               properties :source.sourceModule and :source.sourceLine
+               pointing to solidity source of the interface transition
+
+  :parsed:   data parsed from TLC trace file with properties:
+  	      - :line= string which triggers state space dump to parse state space
+	      - :actionLine=  line number (parser from ':line')
+	      - :state_space = state variables as parsed from the dump, particularly
+		variable :step, which is used as a key to 'interfaces.yaml'
+		to create :source reference
+
+
+}}{{>add-links-transition}}{{!
+
+     1)
+
+}}{{>add-links-interface}}{{!
+
+    2)
+
+}}{{>add-links-state-dump}}{{!
+Local Variables:
+require-final-newline: nil
+End:
+}}

data/mustache/api-call-default.mustache

@@ -0,0 +1,14 @@
+{{!
+     Default template called from API_CALL
+
+     It receives all same information as templates
+     'api-calls.mustache' and 'add-links.mustache' plus additional
+     data in property ':api_input'.
+
+     Api input is hash parsed from tlc trace output for currently
+     running interface (as present in context property :interface)
+
+
+}}
+
+CALL:{{now}} {{interface.interface_operation}}( {{{api_input}}} )

data/mustache/api-call-init.mustache

@@ -0,0 +1,70 @@
+{{!
+
+  api-call-init.mustache: define rendering for 'api-call' command
+  
+  Override this template to use other than default rendering.
+
+  This template is called once for a 'tla-trace-filter.rb api-call'.
+  It initialize four mappings: 
+
+  - API_INPUT_INIT : render state before API call
+  - API_CALL_INIT : render API interface and API input parameters
+  - API_RETURN_INIT : render API interface and API return parameters
+  - API_OUTPUT_INIT : render state after API call
+
+  These mappings wrap mustache lambda sections, which contain a YAML
+  formatted hash mapping interface operation to a name of mustache
+  partial template. Two special keys are used: 1) 'default'
+  (=template to use if no other found), and 2) 'empty' (=template to
+  use if 'interface.interface_operation' is nil).
+
+  Example:
+
+  Demo(): solidity-constructor
+  Demo(execute): solidity-message
+  empty: api-call-empty
+  default: api-call-input
+
+  Which reads:
+  - inteface operation "Demo()" uses mustache partial 'solidity-constructor.mustache'
+  - interface Demo(execute) use partial 'solidity-message.mustache
+  - undedefined interface operation (initial state) use partial 'api-call-empty.mustache'
+  - all other interface operations use  template 'api-call-input.mustache'
+
+  Search parth of these template files is configured using command line option --mustache
+  
+}}{{!
+
+   Configure templates to render state before API call
+
+}}{{#API_INPUT_STATE_INIT}}
+default: api-call-input
+empty: api-call-input
+{{/API_INPUT_STATE_INIT}}{{!
+
+ Configure templates to render API CALL
+ 
+}}{{#API_CALL_INIT}}
+default: api-call-default
+{{/API_CALL_INIT}}{{!
+
+ Configure templates to render API_RETURN
+ 
+}}{{#API_RETURN_INIT}}
+default: api-call-return
+empty: api-call-return
+{{/API_RETURN_INIT}}{{!
+
+    Configure templates to render state after API call
+    
+}}{{#API_OUTPUT_STATE_INIT}}
+default: api-call-output
+empty: api-call-output
+{{/API_OUTPUT_STATE_INIT}}{{!
+
+  Do not output new-line
+
+Local Variables:
+require-final-newline: nil
+End:
+}}

data/mustache/api-call-input.mustache

@@ -0,0 +1,20 @@
+{{!
+
+  api-call-input.mustache: output state before API call
+
+  Default implementation:
+  - output text INPUT-BLOCKCHAIN:
+  - YAML dump 'parsed.state_space.eth_accounts'
+  - YAML dump 'parsed.state_space.eth_storageRoot'
+
+}}
+
+# <INPUT-BLOCKCHAIN now="{{inputState.now}}">
+eth_accounts: {{{inputState.eth_accounts.to_yaml}}}
+eth_storageRoot: {{{inputState.eth_storageRoot.pretty_generate}}}
+# </INPUT-BLOCKCHAIN>
+{{!
+Local Variables:
+require-final-newline: nil
+End:
+}}

data/mustache/api-call-link.mustache

@@ -0,0 +1,2 @@
+{{options.src_dir}}/{{interface.source.sourceModule}}:{{^options.solc_line}}{{interface.source.sourceLine}}{{/options.solc_line}}{{#options.solc_line}}{{SOLC_LINE}}{{/options.solc_line}}:1: {{interface.interface_operation}} at tick {{now}}
+{{options.tla_dir}}/model.tla:{{parsed.actionLine}}: {{{parsed.line}}}

data/mustache/api-call-main.mustache

@@ -0,0 +1,86 @@
+{{!
+
+  api-call-main.mustache: template calling API_INPUT, API_CALL, API_OUTPUT templates
+  
+  Output API call for interface.interface_operation
+
+}}{{!
+
+  IF #interface.source.sourceModule - interface known
+
+}}{{#interface.source.sourceModule}}{{!
+
+  - start interface
+
+}}{{#interface_started}}
+------------------------------------------------------------------
+{{interface.interface_operation}}: at tick '{{parsed.state_space.now}}' for step '{{{parsed.state_space.step }}}'{{!
+
+   - input state: dispatched dynamically trough API_INPUT_STATE, which maps
+     [:interface][:interface_operation] to partial name set in 'api-call-init'
+     using API_INPUT_STATE_INIT
+
+}}{{{API_INPUT_STATE}}}{{!
+
+   - API call: dispatched dynamically trough API_CALL, which maps
+     [:interface][:interface_operation] to partial name set in 'api-call-init'
+     using API_CALL_INIT
+   
+}}{{{API_CALL}}}{{!
+
+   - API_RETURN: dispatched dynamically trough API_RETURN, which maps
+     [:interface][:interface_operation] to partial name set in 'api-call-init'
+     using API_RETURN_INIT
+   
+}}{{{API_RETURN}}}{{!
+
+   - output state: dispatched dynamically trough API_OUTPUT_STATE, which maps
+     [:interface][:interface_operation] to partial name set in 'api-call-init'
+   
+}}{{{API_OUTPUT_STATE}}}{{!
+
+   - link to source line
+}}{{>api-call-link}}{{!
+
+ END IF - interface.source.sourceModule
+
+}}{{/interface_started}}{{#interface_executing}}{{/interface_executing}}{{/interface.source.sourceModule}}{{!
+    
+    ELSE ^interface.source.sourceModule : when no source module identified
+    - interface started
+
+}}{{^interface.source.sourceModule}}{{#interface_started}}
+------------------------------------------------------------------
+{{interface.interface_operation}}: at tick '{{parsed.state_space.now}}' for step '{{{parsed.state_space.step }}}'{{!
+
+   - input state
+   
+}}{{{API_INPUT_STATE}}}{{!
+
+    - API call
+    
+}}{{{API_CALL}}}{{!
+
+    - API return
+    
+}}{{{API_RETURN}}}{{!
+
+    - output state + some extra lines to separate different api-calls
+    
+}}{{{API_OUTPUT_STATE}}}{{!
+
+    - link to source file
+    
+}}{{>api-call-link}}{{!
+
+     - end interface_started
+
+}}{{/interface_started}}{{!
+
+    END : ^interface.source.sourceModule
+
+}}{{/interface.source.sourceModule}}{{!
+Local Variables:
+require-final-newline: nil
+End:
+}}

data/mustache/api-call-output.mustache

@@ -0,0 +1,18 @@
+{{!
+
+  api-call-output.mustache:  output state state after API call
+
+  Default implementation: output eth_account, eth_storageRoot in YAML format
+
+  
+}}
+
+# <OUTPUT-BLOCKCHAIN now="{{inputState.now}}">
+eth_accounts: {{{outputState.eth_accounts.to_yaml}}}
+eth_storageRoot: {{{outputState.eth_storageRoot.to_yaml}}}
+# </OUTPUT-BLOCKCHAIN>
+{{!
+Local Variables:
+require-final-newline: nil
+End:
+}}

data/mustache/api-call-return.mustache

@@ -0,0 +1,13 @@
+{{!
+     Default template called from API_RETURN
+
+     It receives all same information as templates
+     'api-calls.mustache' and 'add-links.mustache' plus additional
+     data in property ':api_return'.
+
+     Api input is hash parsed from tlc trace output for currently
+     running interface (as present in context property :interface)
+
+
+}}
+RETURN:{{now}} {{interface.interface_operation}}=>{{{api_return}}}