tla-trace-filter 0.0.3 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b2804fbc967c6c2816038bd6f3b6a8cfee973484
-  data.tar.gz: 9fab9d64242a596da309fa119ef34401f608cc7b
+  metadata.gz: c26773e9c1c8523333a24665eb9f648f021b17a0
+  data.tar.gz: d5a1a47884bb9bb5b07eede01df7e567037b7e57
 SHA512:
-  metadata.gz: 400432361333e1f8c3186c9ea77907877c1fc09ea7ee01c994f1b29d0f31ac15a39a5867422541c29dec1c4258136c700eb5d40072ee5ac9f8ff0437b7e9fd3c
-  data.tar.gz: 30366f9fade7597713f53e02d62bad8e37449ce5b0f249ddd87039191fc5562ccbd677ffb2bc211ed3f69e9b41ad4f9da145fca83ece7810cd659d14df5ae659
+  metadata.gz: c47bd7b02c21164670b48fee9f5ede938c80e25673bb17864e1a25bd31b75296c54c6b7d72aaf667c0d079ac51b23879bafc3011ad8f8f1b06d70f80bc670855
+  data.tar.gz: 40ef12b948cf1b57fccd9a700bec5561a2ae33813c03a633d7f867c15718292c1214b18032e9ebdcff05fc5cbe9d1ffbe1f37083bd50d22f806efbcdf66b7ddd

data/README.md

@@ -0,0 +1,108 @@
+# `tla-sbuilder-trace` - Post process trace output from model checking sbuilder formal models 
+
+Command line filter for
+processing
+[TLA+ Tools](http://research.microsoft.com/en-us/um/people/lamport/tla/tools.html) trace
+output resulting from model
+checking
+[TLA+ language](http://research.microsoft.com/en-us/um/people/lamport/tla/book.html) specification
+code generated
+using [sbuilder](https://github.com/jarjuk/tla-sbuilder) -tool.
+
+The tool implements two commands
+
+* `add-links` : for adding links pointing 1) to *TLA+ language*
+  specification code and 2) to source code translated by sbuilder tool
+
+* `api-calls` : for interpreting transitions in trace output as
+  interface calls on sbuilder source code translated by *sbuilder* tool
+
+
+## Installation
+
+
+To install `tla-trace-filter` GEM create a `Gemfile` -file with the
+content
+
+```
+source "https://rubygems.org"
+gem 'tla-trace-filter'
+```
+
+and run
+
+	bundle install
+
+
+## Usage
+
+### tla-trace-filter.rb add-links
+
+To add links to model checker trace output in file `gen/tlc.out`
+resulting from model checking *TLA+ language* specification code in
+file `gen/setup1/tla/model.tla`, and using YAML file
+`gen/setup1/tla/interfaces.yaml` to map transition names back to
+source code modules in directory `solidity` run:
+
+	bundle exec tla-trace-filter.rb add-links setup1
+	
+
+To embed links to trace output run:
+
+	bundle exec tla-trace-filter.rb add-links setup1 --embed
+
+
+### tla-trace-filter.rb api-calls
+
+To create API calls run:
+
+	bundle exec tla-trace-filter.rb api-calls setup1	
+	
+
+### Getting help
+
+Location of the files and directories can be changes using command
+line options. To get a list of available command and their options
+run:
+	
+	bundle exec tla-trace-filter.rb help
+
+## Documentation
+
+See [Cucumber](https://cucumber.io/) tests in GEM directory `features`.
+
+For a demonstration of `api-call-init` -extension point refer to
+a
+[blog entry](https://jarjuk.wordpress.com/2017/12/06/sbuilder-wallet-3/).
+
+
+## <a id="API-CALL_INIT">`api-call-init`-extension point</a>
+
+`tla-trace-filter.rb` -tool
+uses [mustache](https://mustache.github.io/) templates to produce
+output. Default templates used are located in GEM directory
+`mustache`.  Command line option `--mustache` can override the
+location, where templates are searched for.
+
+To show templates, used by the tool, issue the command
+
+	ls $(bundle show tla-trace-filter)/mustache
+	
+To get instructions, how to use `api-call-init` -extension point,
+issue the command:
+
+	cat $(bundle show tla-trace-filter)/mustache/api-call-init.mustache
+
+
+## <a id="MUSTACHE-LAMBDAS">Mustache output  lambdas</a>
+
+Following lambda function are available in mustache template
+
+* `{{#YAML_DUMP}}key{{/YAML_DUMP}}` : dump context `key` as YAML,
+  e.g. to dump `beforeState`, `api_input`, `api_return` or
+  `afterState` for `tla-trace-filter.rb api-calls` -command
+
+
+## License 
+
+MIT

data/VERSION

@@ -1 +1 @@
-0.0.3
+0.0.6

data/lib/cli/cli.rb

@@ -2,6 +2,8 @@ require_relative "../tla-trace-filter.rb"
 
 require 'thor'
 require 'yaml'
+require 'socket'       # gethostname
+require 'digest'       # sha1
 
 module TlaTraceFilter
   class Cli < Thor
@@ -12,13 +14,16 @@ module TlaTraceFilter
     API_CALL_TEMPLATE  = "api-call"         # root template for command 'api-call'
     ADD_LINKS_TEMPLATE = "add-links"        # root template for command 'add-links'
 
+    API_CALL_PRE       =  "api-call-pre"    # render before anything other templates
+    API_CALL_POST      =  "api-call-post"   # render last
+
     
     
     VERSION_BANNER =  <<~EOS
     #{File.basename $0}: #{File.readlines( File.join File.dirname( __FILE__ ), "../../VERSION" ).first.gsub( /\n/, "" )}
     EOS
 
-    MUSTACHE_DEFAULT = "mustache/"
+    MUSTACHE_DEFAULT = [ "mustache/" ]
     MUSTACHE_OPTION= <<-EOS
     Output is processed using mustache templates in directory 
     #{File.dirname __FILE__}/../../mustache. Mustache templates can be
@@ -48,6 +53,9 @@ module TlaTraceFilter
       def rendering
         @rendering ||= TlaTraceFilter::Render.new( options )
       end
+
+      # @# @!attribute [Digest:SHA1] sha1
+      attr_accessor :sha1
       
     end
 
@@ -106,10 +114,11 @@ module TlaTraceFilter
     add_shared_option :tla_dir, :type=>:string, :desc=>"Override default specification code dir gen/SETUP/tla"
     add_shared_option :src_dir, :default=>"./solidity", :type=>:string,  :desc=>"Source code root directory"
     add_shared_option :filter_src, :aliases => "-f", :type => :boolean, :default => false
-    add_shared_option :mustache, :aliases => "-m", :type => :string, :desc => "Add a directory (ends with /-char) or GEM to search for mustache template", :default=> MUSTACHE_DEFAULT
+    add_shared_option :mustache, :aliases => "-m", :type => :array, :desc => "Add a directory (ends with /-char) or GEM to search for mustache template", :default=> MUSTACHE_DEFAULT
     add_shared_option :solc_line, :type => :boolean, :default=>false, :desc => "TRUE interpretes sourceLines as characters starting from source start"
     add_shared_option :debug_mustache,  :type => :boolean, :default=>false, :desc => "Raise exception if referencing non-existing property"
     add_shared_option :embed,  :type => :boolean, :default=>false, :desc => "TRUE adds link to trace output"
+    add_shared_option :sha1,  :type => :boolean, :default=>true, :desc => "Make :sha1 available for template #{API_CALL_POST}"    
     
     # @!endgroup
 
@@ -185,11 +194,10 @@ module TlaTraceFilter
     API calls are resolved using 'interface.yaml' YAML file found in
     specification code directory (option :tla-dir).
 
-    Use command 
 
-    cat $(bundle show tla-trace-filter)/mustache/api-call-init.mustache
-
-    for instructions to map interface operations to mustache partials.
+    Extension points: 
+    - cat $(bundle show tla-trace-filter)/mustache/api-call-init.mustache: 
+      dynamic distpatch based on context[:interface][:interface_operation]
       
 
     #{MUSTACHE_OPTION}
@@ -202,18 +210,25 @@ module TlaTraceFilter
     shared_options :state_dump
     shared_options :filter_src
     shared_options :solc_line
+    shared_options :sha1
     
     def api_calls( setup, file=nil)
 
       # unfreeze 'options' && set defaults (:tla_dir)
       setOptions( setup )
 
+      # init sha1 calculation
+      sha1Init
+
       # Load fixed named template - allow used to define mapping
       apiInitTemplate = "{{>#{API_CALL_INIT} }}"
       @logger.info "#{__method__}, apiInitTemplate=#{apiInitTemplate}"
       rendered =  rendering.render(apiInitTemplate, options)
       @logger.info "#{__method__}, output from init '#{rendered}'"
-      puts rendered if rendered.length > 0
+      # outputRendered(rendered)
+
+      # preamble partial
+      outputRendered( rendering.render( "{{>#{API_CALL_PRE}}}", preAndPostHash(options ) ) )
       
       # Default FILE vs. given on cmd line
       file = traceFile( setup, file )
@@ -222,54 +237,71 @@ module TlaTraceFilter
       @logger.info "#{__method__}, template=#{template}"
 
       # queue length of 1
-      q = nil
-      lastData = nil
+      interfaceBeforeState = nil
+      interfaceEnterState = nil
+      interfaceEndState = nil
 
       # read 'file' yielding String/Hash and parsedLines producing Hash
       processInput( file ) do |data, parsedLines|
 
         if data.is_a?(String)
-          # api - call do not ouput trace lines
+          # api - call do not output trace lines
         elsif data.is_a?(Hash)
           
           # reason to output api-call
           if data[:interface_started]
 
-            if q.nil?
-              # init qeueu
-              q = data
+            if interfaceBeforeState.nil?
+              # first time processing state 0 
+              interfaceBeforeState = data
+              @logger.debug "loop: init interfaceBeforeState: #{interfaceBeforeState}" if @logger.debug?
+            elsif interfaceEnterState.nil?
+            # state 0 has been processed - is this the first interface
+              interfaceEnterState = data
             else
 
-              # output prev element in queue
-              q[:inputState] = q[:parsed][:state_space]
-              q[:now] = q[:parsed][:state_space][:now]
-              q[:outputState] = lastData[:parsed][:state_space]
-              # render parsed data && output if any ouput
-              rendered =  rendering.render(template, q)
-              puts rendered if rendered.length > 0
-
-              # queue current data
-              q = data
+              # New iterface has started to execute. Now we can render
+              # apiStep for previous interface call using state collected in
+              #
+              # * beforeState: takens from 'interfaceBeforeState': it s either the first
+              #   'data' parsed OR 'data' parsed  , which was reached
+              #   after executing previous interface call.
+
+              # * afterState: taken from preceding 'data' in 'interfaceEndState'
+              apiOutput = canonizeData( interfaceBeforeState, interfaceEnterState, interfaceEndState )
+              @logger.debug "loop: apiOutput #{apiOutput}" if @logger.debug?
+              rendered =  rendering.render(template, apiOutput)
+              outputRendered( rendered ) 
+
+              # init 'interfaceBeforeState' as 'interfaceEndState'
+              # from the previous step (which was just rendered)
+              interfaceBeforeState = interfaceEndState
+              # init 'interfaceEnterState' to current 'data' parsed from inputfile
+              interfaceEnterState = data
+              @logger.debug "loop: set interfaceBeforeState #{interfaceBeforeState}" if @logger.debug?
             end 
             
           end  # interface_started
 
-          # rememeber it
-          lastData = data
+          # advance 'interfaceEndState' with current 'data'
+          interfaceEndState = data
           
         end # elsif Hash?
       end # block
 
-      if !q.nil?
+      # flush interfaceBeforeState
+      if !interfaceBeforeState.nil?
         # render parsed data && output if any ouput
-        q[:inputState] = q[:parsed][:state_space]
-        q[:now] = q[:parsed][:state_space][:now]
-        q[:outputState] = lastData[:parsed][:state_space]
-        rendered =  rendering.render(template, q)
-        puts rendered if rendered.length > 0
+        apiOutput = canonizeData( interfaceBeforeState, interfaceEnterState || interfaceEndState, interfaceEndState )
+        @logger.debug "loop:exit: apiOutput (quit) #{apiOutput}" if @logger.debug?
+        rendered =  rendering.render(template, apiOutput)
+        outputRendered( rendered ) 
         
       end # 
-      
+
+      # postamble (including setting sha1) - but not calculating it
+      rendered =  rendering.render("{{>#{API_CALL_POST}}}", preAndPostHash(options ) )
+      puts rendered if rendered.length > 0
       
     end
     
@@ -278,10 +310,68 @@ module TlaTraceFilter
     
 
     # ------------------------------------------------------------------
-    # @!group No commans
+    # @!group No commansd
 
     no_commands do
 
+      # INitialize sha1 opbject 
+      def sha1Init
+        self.sha1 = Digest::SHA1.new if options[:sha1]
+      end
+      
+      def sha1Update( data )
+        sha1.update( data ) if options[:sha1]
+        # @logger.debug "#{__method__}: lines=#{@lines}, sha1.hexdigest=#{sha1.hexdigest}, data=#{data}" if @logger.debug?
+      end
+
+
+      # Output 'rendered' line && calculate sha1
+      def outputRendered rendered
+        if rendered.length > 0
+          sha1Update( rendered )
+          puts rendered
+        end
+      end
+
+      # @return [Hash] data hash passed to pre/post templates. 
+      def preAndPostHash( options)
+        {
+          :options => options,
+          :META => getMeta(),
+          :sha1 => sha1,
+        }
+      end
+
+      def getMeta
+        {
+          :timestamp => Time.new.strftime( "%Y-%m-%d %H:%M:%S" ),
+          :hostname => Socket.gethostname,
+          :user => ENV["USER"],
+        }
+      end
+
+      # @return [Hash] with properties from
+      #          'interfaceBeforeState','interfaceEnterState' and
+      #          'interfaceEndState'
+      def canonizeData( interfaceBeforeState, interfaceEnterState, interfaceEndState )
+        ret = {
+          options: interfaceBeforeState[:options],                       # cmd line options
+          interface_started: true,
+          beforeState: interfaceBeforeState[:parsed][:state_space],
+          parsed: interfaceEnterState[:parsed],
+          now: interfaceEndState[:parsed][:state_space][:now],
+          interface: interfaceEndState[:interface],
+          interface_operation: interfaceEndState[:interface_operation],
+          afterState: interfaceEndState[:parsed][:state_space],
+        }
+        
+        # q[:beforeState] = q[:parsed][:state_space]
+        # q[:now] = lastData[:parsed][:state_space][:now]
+        # q[:interface] = lastData[:interface]
+        # q[:afterState] = lastData[:parsed][:state_space]
+        # q
+      end
+
       # @param parsed [Hash] parsed model checking state
       #      
       # @param interfaceDefintion [type] interface for currently
@@ -433,43 +523,6 @@ module TlaTraceFilter
         interfaceHash
       end
 
-      # # @param interface_operation [String] interface geth(mine)
-      # #        executing tla transition parsed in state space
-      # # 
-      # # @param state_space [Hash] state space state parsed
-      # #
-      # # @return [Boolean] true if
-      # #       state_space[:pc][interface_operation] ends_with
-      # #       '_start', edge case return 'false' if
-      # #       'interface_operation' not found in 'state_space'
-      # #
-      
-      # def interfaceStarted?(interface_operation, state_space)
-      #   @logger.debug "#{__method__}: interface_operation, state_space=#{state_space.to_yaml}" if @logger.debug?
-      #   @logger.info "#{__method__}: look '#{interface_operation}' in #{state_space[:pc]}"
-      #   return false if interface_operation.nil? || interface_operation.length == 0
-      #   return false if state_space[:pc][interface_operation].nil?
-      #   # state_space[:pc][interface_operation].end_with? "_start"
-      #   isStart?( state_space[:pc][interface_operation] )
-      # end
-
-      # # @param interface_operation [String] interface geth(mine)
-      # #        executing tla transition parsed in state space
-      # # 
-      # # @param state_space [Hash] state space state parsed
-      # #
-      # # @return [Boolean] true if
-      # #       state_space[:pc][interface_operation] does NOT ends
-      # #       '_start' && 'interface_operation' found in 'state_space'
-      # #
-      
-      # def interfaceExecuting?(interface_operation, state_space)
-      #   # not valid interface_operation
-      #   return false if interface_operation.nil? || interface_operation.length == 0
-      #   return false if state_space[:pc][interface_operation].nil?
-      #   # toggle isStart?
-      #   return !isStart?( state_space[:pc][interface_operation] )
-      # end
 
       # @param interface_operation [String] interface geth(mine)
       #        executing tla transition parsed in state space
@@ -510,6 +563,7 @@ module TlaTraceFilter
 
       # unfreeze 'options' && set defaults (:tla_dir)
       def setOptions( setup )
+        @logger.info "#{__method__}, options=#{options.to_yaml}"
         # unfreeze options
         new_options = options.dup
         self.options = new_options

data/lib/render/render.rb

@@ -15,11 +15,11 @@ module TlaTraceFilter
     # ------------------------------------------------------------------
     # @!group Constants
 
-    # Default templates for inputState, call, and outputState
-    API_INPUT_STATE_DEFAULT_PARTIAL  = "api-call-input"    
-    API_CALL_DEFAULT_PARTIAL         = "api-call-default"
-    API_RETURN_DEFAULT_PARTIAL       = "api-call-return"    
-    API_OUTPUT_STATE_DEFAULT_PARTIAL = "api-call-output"
+    # Default templates for beforeState, call, and afterState
+    API_BEFORE_STATE_DEFAULT_PARTIAL  = "api-call-default-beforeState"    
+    API_CALL_DEFAULT_PARTIAL          = "api-call-default-api_input"
+    API_RETURN_DEFAULT_PARTIAL        = "api-call-default-api_return"    
+    API_AFTER_STATE_DEFAULT_PARTIAL   = "api-call-default-afterState"
 
     # Keys mapping to the output templates
     API_DEFAULT_KEY = "default"
@@ -46,13 +46,13 @@ module TlaTraceFilter
     #                (with default) to partial name
     attr_accessor :returnPartials
     
-    # @# @!attribute [Hash] inputStatePartials hash mapping interface-names
+    # @# @!attribute [Hash] beforeStatePartials hash mapping interface-names
     #                (with default) to partial name
-    attr_accessor :inputStatePartials
+    attr_accessor :beforeStatePartials
     
-    # @# @!attribute [Hash] outputStatePartials hash mapping interface-names
+    # @# @!attribute [Hash] afterStatePartials hash mapping interface-names
     #                (with default) to partial name
-    attr_accessor :outputStatePartials
+    attr_accessor :afterStatePartials
     
     # @!endgroup
 
@@ -79,18 +79,18 @@ module TlaTraceFilter
       # default search only GEM templates
       self.templatePaths =  [ File.join( File.dirname(__FILE__), "../../mustache/") ]
       # user defined template search path prepended
-      self.templatePaths =  [ options[:mustache] ] + templatePaths if options[:mustache]
+      self.templatePaths =  options[:mustache] + templatePaths if options[:mustache]
     end
 
     def initPartials
       self.partials = {}
       API_CALL_INIT( "" )
       API_RETURN_INIT( "" )
-      API_INPUT_STATE_INIT( "" )
-      API_OUTPUT_STATE_INIT( "" )
+      API_BEFORE_STATE_INIT( "" )
+      API_AFTER_STATE_INIT( "" )
       # self.callPartials = {}
-      # self.inputStatePartials = {}
-      # self.outputStatePartials = {}      
+      # self.beforeStatePartials = {}
+      # self.afterStatePartials = {}      
     end
 
     # @!endgroup
@@ -154,15 +154,15 @@ module TlaTraceFilter
     
     # Initiliaze template calls. If no data given results calling to
     # default templates
-    def API_INPUT_STATE_INIT( data)
+    def API_BEFORE_STATE_INIT( data)
       @logger.info "#{__method__}: data=#{data}"
       begin 
-        self.inputStatePartials = data.nil? || data == "" ? {} : YAML.load( data )
+        self.beforeStatePartials = data.nil? || data == "" ? {} : YAML.load( data )
       rescue Exception => e
         msg = <<-EOS
         #{e}
 
-        Error parsing YAML data in API_INPUT_STATE_INIT:
+        Error parsing YAML data in API_BEFORE_STATE_INIT:
 
         #{data}
         EOS
@@ -170,20 +170,20 @@ module TlaTraceFilter
         raise Exception.new, msg, e.backtrace
       end
 
-      @logger.debug "#{__method__}: inputStatePartials=#{inputStatePartials}" if @logger.debug?
+      @logger.debug "#{__method__}: beforeStatePartials=#{beforeStatePartials}" if @logger.debug?
       
       # ensure that 'default' and 'empty' partials are defined
-      self.inputStatePartials[API_DEFAULT_KEY] = API_INPUT_STATE_DEFAULT_PARTIAL if inputStatePartials[API_DEFAULT_KEY].nil?
-      self.inputStatePartials[API_EMPTY_KEY] = API_OUTPUT_STATE_DEFAULT_PARTIAL if inputStatePartials[API_EMPTY_KEY].nil?      
+      self.beforeStatePartials[API_DEFAULT_KEY] = API_BEFORE_STATE_DEFAULT_PARTIAL if beforeStatePartials[API_DEFAULT_KEY].nil?
+      self.beforeStatePartials[API_EMPTY_KEY] = API_AFTER_STATE_DEFAULT_PARTIAL if beforeStatePartials[API_EMPTY_KEY].nil?      
       
     end
 
     # Lambda to initiliaze template calls. If no data given results
     # calling to default templates
-    def API_OUTPUT_STATE_INIT( data)
+    def API_AFTER_STATE_INIT( data)
       @logger.info "#{__method__}: data=#{data}"
       begin 
-        self.outputStatePartials = data.nil? || data == "" ? {} : YAML.load( data )
+        self.afterStatePartials = data.nil? || data == "" ? {} : YAML.load( data )
       rescue Exception => e
         msg = <<-EOS
         #{e}
@@ -196,11 +196,11 @@ module TlaTraceFilter
         raise Exception.new, msg, e.backtrace
       end
 
-      @logger.debug "#{__method__}: outputStatePartials=#{outputStatePartials}" if @logger.debug?
+      @logger.debug "#{__method__}: afterStatePartials=#{afterStatePartials}" if @logger.debug?
       
       # ensure that 'default' and 'empty' partials are defined
-      self.outputStatePartials[API_DEFAULT_KEY] = API_OUTPUT_STATE_DEFAULT_PARTIAL if outputStatePartials[API_DEFAULT_KEY].nil?
-      self.outputStatePartials[API_EMPTY_KEY] = API_OUTPUT_STATE_DEFAULT_PARTIAL if outputStatePartials[API_EMPTY_KEY].nil?      
+      self.afterStatePartials[API_DEFAULT_KEY] = API_AFTER_STATE_DEFAULT_PARTIAL if afterStatePartials[API_DEFAULT_KEY].nil?
+      self.afterStatePartials[API_EMPTY_KEY] = API_AFTER_STATE_DEFAULT_PARTIAL if afterStatePartials[API_EMPTY_KEY].nil?      
       
     end
     
@@ -236,25 +236,25 @@ module TlaTraceFilter
     end
 
     def getInputStatePartialName( interfaceOperation )
-      inputStatePartialName = nil
-      inputStatePartialName = inputStatePartials[API_EMPTY_KEY] if interfaceOperation.nil?
-      inputStatePartialName = inputStatePartials[interfaceOperation] if inputStatePartialName.nil?
-      inputStatePartialName = inputStatePartials[API_DEFAULT_KEY] if inputStatePartialName.nil?
-      raise "Missing could not resolve '#{interfaceOperation}' in inputStatePartials #{inputStatePartials}" if inputStatePartialName.nil?
-
-      @logger.info "#{__method__}: API-call to interfaceOperation '#{interfaceOperation}' render with '#{inputStatePartialName}'"
-      inputStatePartialName
+      beforeStatePartialName = nil
+      beforeStatePartialName = beforeStatePartials[API_EMPTY_KEY] if interfaceOperation.nil?
+      beforeStatePartialName = beforeStatePartials[interfaceOperation] if beforeStatePartialName.nil?
+      beforeStatePartialName = beforeStatePartials[API_DEFAULT_KEY] if beforeStatePartialName.nil?
+      raise "Missing could not resolve '#{interfaceOperation}' in beforeStatePartials #{beforeStatePartials}" if beforeStatePartialName.nil?
+
+      @logger.info "#{__method__}: API-call to interfaceOperation '#{interfaceOperation}' render with '#{beforeStatePartialName}'"
+      beforeStatePartialName
     end
 
     def getOutputStatePartialName( interfaceOperation )
-      outputStatePartialName = nil
-      outputStatePartialName = outputStatePartials[API_EMPTY_KEY] if interfaceOperation.nil?
-      outputStatePartialName = outputStatePartials[interfaceOperation] if outputStatePartialName.nil?
-      outputStatePartialName = outputStatePartials[API_DEFAULT_KEY] if outputStatePartialName.nil?
-      raise "Missing could not resolve '#{interfaceOperation}' in outputStatePartials #{outputStatePartials}" if outputStatePartialName.nil?
-
-      @logger.info "#{__method__}: API-call to interfaceOperation '#{interfaceOperation}' render with '#{outputStatePartialName}'"
-      outputStatePartialName
+      afterStatePartialName = nil
+      afterStatePartialName = afterStatePartials[API_EMPTY_KEY] if interfaceOperation.nil?
+      afterStatePartialName = afterStatePartials[interfaceOperation] if afterStatePartialName.nil?
+      afterStatePartialName = afterStatePartials[API_DEFAULT_KEY] if afterStatePartialName.nil?
+      raise "Missing could not resolve '#{interfaceOperation}' in afterStatePartials #{afterStatePartials}" if afterStatePartialName.nil?
+
+      @logger.info "#{__method__}: API-call to interfaceOperation '#{interfaceOperation}' render with '#{afterStatePartialName}'"
+      afterStatePartialName
     end
 
     # @!endgroup
@@ -297,18 +297,18 @@ module TlaTraceFilter
       lineCount
     end
 
-    # Lamba called for 'API_INPUT_STATE' to dispatch dynamically rendering of
-    # [:interface][:interface_operation] inputState.
-    def API_INPUT_STATE
+    # Lamba called for 'API_BEFORE_STATE' to dispatch dynamically rendering of
+    # [:interface][:interface_operation] beforeState.
+    def API_BEFORE_STATE
       @logger.info "#{__method__}: [:interface][:interface_operation]=#{context[:interface][:interface_operation]},  now=#{context[:now]}"
       callPartialName = getInputStatePartialName( context[:interface][:interface_operation]  )
       template = partial( callPartialName )
       render( template, context )
     end
 
-    # Lamba called for 'API_OUTPUT_STATE' to dispatch dynamically rendering of
-    # [:interface][:interface_operation] outputState.
-    def API_OUTPUT_STATE
+    # Lamba called for 'API_AFTER_STATE' to dispatch dynamically rendering of
+    # [:interface][:interface_operation] afterState.
+    def API_AFTER_STATE
       @logger.info "#{__method__}: [:interface][:interface_operation]=#{context[:interface][:interface_operation]} now=#{context[:now]}"      
       callPartialName = getOutputStatePartialName( context[:interface][:interface_operation]  )
       template = partial( callPartialName )
@@ -316,6 +316,7 @@ module TlaTraceFilter
     end
 
     def API_RETURN
+      @logger.info "#{__method__}: [:interface][:interface_operation]=#{context[:interface][:interface_operation]} now=#{context[:now]}"      
 
       interfaceOperation = context[:interface][:interface_operation]
       responseKey = context[:interface][:response_key]      
@@ -325,8 +326,10 @@ module TlaTraceFilter
       template = partial( callPartialName )
 
       # context access likke i_Bank_saveAccount_
-      # raise "keys=#{context[:outputState][:responses].to_yaml}"
-      context[:api_return] = context[:outputState][:responses][responseKey]
+      # raise "keys=#{context[:afterState][:responses].to_yaml}"
+      @logger.debug "#{__method__}: context[:afterState]=#{context[:afterState].to_yaml}"  if @logger.debug?
+      
+      context[:api_return] = context[:afterState][:responses].nil? ? nil : context[:afterState][:responses][responseKey]
       
       render( template, context )
 
@@ -370,10 +373,10 @@ module TlaTraceFilter
           context[:parsed][:state_space][:step_input]
         else
           
-          api = "#{context[:interface][:interface_name]}_input"
+          inputvariable = "#{context[:interface][:interface_name]}_input"
                 
           # find name of procedure input varibable
-          api = context[:parsed][:state_space].keys.find { |k| k.to_s.end_with?( api ) } unless api.nil?
+          api = context[:parsed][:state_space].keys.find { |k| k.to_s.end_with?( inputvariable) } unless inputvariable.nil?
       
           # access procedure input data
           api = context[:parsed][:state_space][api] unless api.nil?
@@ -381,7 +384,15 @@ module TlaTraceFilter
           # access procedure input for currently running interface opertaion
           api = api[context[:interface][:interface_operation]] unless api.nil?
 
-          api =  { :error => "No input found in context[:parsed][:state_space][:step_input] - maybe set 'SetStepInput = TRUE'"} if api.nil?
+          if api.nil?
+            msg = %Q{
+            No input found in context[:parsed][:state_space][:step_input] - maybe set 'SetStepInput = TRUE'
+            
+            Tried to locate input variable ending with #{inputvariable} in context[:parsed][:state_space]
+            }
+
+            api =  { :error => msg } 
+          end         
 
           api
         end
@@ -391,6 +402,26 @@ module TlaTraceFilter
     end
     
 
+    # @!endgroup
+
+    # # ------------------------------------------------------------------
+    # @!group DUmp
+
+    # dump 'contextKey' in in YAML, where 'contextKey' is path of hash
+    # keys repareated by '.'
+    def DUMP_YAML( contextKey )
+      # enable splitting key  - just be sure
+      contextKey = contextKey.to_s unless contextKey.is_a? String
+      keys = contextKey.split(".")
+      c = context
+      keys.each do |key|
+        break if c.nil?
+        c = c[key.to_sym]
+      end
+      c.to_yaml
+    end
+    
+
     # @!endgroup
 
 
@@ -494,7 +525,8 @@ module TlaTraceFilter
     # otherwiset (= also NOT even if installed locally in gems)
     def gem_location( gemName )
       gemSpec = Gem.loaded_specs[gemName]
-      raise "Unknown gemName #{gemName}" if gemSpec.nil?
+      raise "Unknown gemName #{gemName} - known Gems #{Gem.loaded_specs.keys.join(",")} " if gemSpec.nil?
+      @logger.info "#{__method__}: gemName#{gemName} resolves to gemSpec.gem_dir#{gemSpec.gem_dir}"
       gemSpec.gem_dir
     end