tla-trace-filter 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b2804fbc967c6c2816038bd6f3b6a8cfee973484
+  data.tar.gz: 9fab9d64242a596da309fa119ef34401f608cc7b
+SHA512:
+  metadata.gz: 400432361333e1f8c3186c9ea77907877c1fc09ea7ee01c994f1b29d0f31ac15a39a5867422541c29dec1c4258136c700eb5d40072ee5ac9f8ff0437b7e9fd3c
+  data.tar.gz: 30366f9fade7597713f53e02d62bad8e37449ce5b0f249ddd87039191fc5562ccbd677ffb2bc211ed3f69e9b41ad4f9da145fca83ece7810cd659d14df5ae659

data/README.org

@@ -0,0 +1,66 @@
+* =tla-sbuilder-trace=  - Post process TLA-tools trace output
+
+A command line filter utility for processing [[http://research.microsoft.com/en-us/um/people/lamport/tla/tools.html][TLA+ Tools]] output
+resulting created when model checking [[[http://research.microsoft.com/en-us/um/people/lamport/tla/book.html][TLA+ language]]] formal model
+generated using [[https://github.com/jarjuk/tla-sbuilder][sbuilder]] -tool.
+
+The utility 
+
+
+* Installation
+
+To install =tla-trace-filter= GEM create a =Gemfile= -file with the
+content
+
+#+BEGIN_SRC ruby :eval no
+source "https://rubygems.org"
+gem 'tla-trace-filter'
+#+END_SRC
+
+and run
+
+#+BEGIN_SRC ruby :eval no
+bundle install
+#+END_SRC
+
+* Usage
+
+** Genrate traces						   :noexport:
+
+** Add links to trace file
+
+To add links to model checker trace output in file =gen/tlc.out=
+outputted when model checking TLA+ language formal model code in file
+=gen/setup1/tla/model.tla=
+
+#+BEGIN_SRC ruby :eval no-export
+bundle exec tla-trace-filter.rb add-links setup1
+#+END_SRC
+
+
+To embed links to trace output run:
+
+#+BEGIN_SRC ruby :eval no-export
+bundle exec tla-trace-filter.rb add-links setup1 --embed
+#+END_SRC
+
+
+To create API calls run:
+
+#+BEGIN_SRC ruby :eval no
+bundle exec tla-trace-filter.rb api-calls setup1	
+#+END_SRC
+	
+	
+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
+
+
+** Create API trace
+
+
+**  Documentation
+
+See [[https://cucumber.io][Cucumber]] tests in =features= -directory [[http://jarjuk.github.io/tla-trace-filter.html][github repo]].

data/VERSION

@@ -0,0 +1 @@
+0.0.3

data/bin/tla-trace-filter.rb

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require_relative "../lib/cli/cli.rb"
+
+TlaTraceFilter::Cli.start(ARGV)

data/lib/cli/cli.rb

@@ -0,0 +1,563 @@
+require_relative "../tla-trace-filter.rb"
+
+require 'thor'
+require 'yaml'
+
+module TlaTraceFilter
+  class Cli < Thor
+
+    include TlaTraceFilter::Util::MyLogger
+
+    API_CALL_INIT      = "api-call-init"    # name mustache template called once 
+    API_CALL_TEMPLATE  = "api-call"         # root template for command 'api-call'
+    ADD_LINKS_TEMPLATE = "add-links"        # root template for command 'add-links'
+
+    
+    
+    VERSION_BANNER =  <<~EOS
+    #{File.basename $0}: #{File.readlines( File.join File.dirname( __FILE__ ), "../../VERSION" ).first.gsub( /\n/, "" )}
+    EOS
+
+    MUSTACHE_DEFAULT = "mustache/"
+    MUSTACHE_OPTION= <<-EOS
+    Output is processed using mustache templates in directory 
+    #{File.dirname __FILE__}/../../mustache. Mustache templates can be
+    overridden using templates in directory pointeted by line option
+    :mustache. Default = #{MUSTACHE_DEFAULT}
+
+    Parameter values ending with /-character are directories,
+    otherwise it is GEM name, where partials are in 'mustache' 
+    sub-directory.
+  
+    EOS
+
+    # ------------------------------------------------------------------
+    # @!group Attributes 
+
+    no_commands do
+      
+      # @!attribute [Filter] filtering to manage filtering state
+      def filtering
+        @filtering ||= TlaTraceFilter::Filter.new( options )
+      end
+
+      #  @!attribute [Render] rendering tool outpu trace
+      #
+      #  @param options [Hash] options with property :mustache
+      #  prepended to partial search path
+      def rendering
+        @rendering ||= TlaTraceFilter::Render.new( options )
+      end
+      
+    end
+
+    # @!endgroup
+
+
+    # ------------------------------------------------------------------
+    # @!group Constructor
+
+    def initialize( *args )
+      super
+      @logger = getLogger( nil, options )
+      @logger.info "#{__method__}: initalized"
+    end
+    
+    # @!endgroup
+
+    # ------------------------------------------------------------------
+    # @!group Enable shared options
+
+    # make two thor tasks share options?
+    # http://stackoverflow.com/questions/14346285/how-to-make-two-thor-tasks-share-options
+    
+    class << self
+      def add_shared_option(name, options = {})
+        @shared_options = {} if @shared_options.nil?
+        @shared_options[name] =  options
+      end
+
+      def shared_options(*option_names)
+        option_names.each do |option_name|
+          opt =  @shared_options[option_name]
+          raise "Tried to access shared option '#{option_name}' but it was not previously defined" if opt.nil?
+          yield option_name, opt if block_given?
+          option option_name, opt
+        end
+      end
+    end
+
+    # @!endgroup
+
+    # ------------------------------------------------------------------
+    # @!group Shared options
+
+    class_option :log, :aliases => "-l", :type =>:string, :default => nil, 
+                  :enum => [ "DEBUG", "INFO", "WARN", "ERROR" ],
+                  :desc => "Set debug level "
+
+    
+    class_option :logfile, :type =>:string,
+                 :default => File.join(Dir.getwd, TlaTraceFilter::Util::MyLogger::LOGFILE),
+                 :desc => "Set file for log output"
+
+    add_shared_option :state_dump, :default=>false, :type=>:boolean,  :desc=>"Dump parsed state space states in JSON format"    
+    
+    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 :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"
+    
+    # @!endgroup
+
+
+
+    # ------------------------------------------------------------------
+    # @!group Commands
+
+    desc :version, "Output version"
+    def version()
+      puts VERSION_BANNER
+    end
+
+    desc "add-links SETUP [FILE]", "Add links for SETUP into trace output in FILE (- for STDIN)"
+    
+    long_desc <<-EOF
+
+    Filter tla+tools trace output FILE (default 'gen/<setup>/tlc.out') and add
+    links 1) for transitions found in FILE pointing to specification
+    code 'model.tla' in directory 'gen/SETUP/tla' (override using
+    option :tla-dir) and 2) for source code references found in FILE
+    pointing to source files in directory 'solidity' (override using
+    option 'src-dir').
+
+    Links to source files are resolved using 'interface.yaml' YAML
+    file located in specification code directory (option :tla-dir).
+
+    #{MUSTACHE_OPTION}
+    EOF
+    shared_options :mustache
+    shared_options :debug_mustache
+    shared_options :tla_dir
+    shared_options :src_dir
+    shared_options :state_dump
+    shared_options :filter_src    
+    shared_options :embed
+    shared_options :solc_line
+    def add_links( setup, file=nil )
+
+      # unfreeze 'options' && set defaults (:tla_dir)
+      setOptions( setup )
+      
+      # Default FILE vs. given on cmd line
+      file = traceFile( setup, file )
+      
+      template = "{{>#{ADD_LINKS_TEMPLATE}}}"
+      # no_strings = true && !options[:embed]
+
+      # read 'file' yielding String/Hash and parsedLines producing Hash
+      processInput( file ) do |data,parsedLines|
+        if data.is_a?(String)
+          # Not parseable line 
+          puts data if options[:embed]
+        elsif data.is_a?(Hash)
+          # template = "{{>add-links}}" or {{>api-calls}}
+          rendered =  rendering.render(template, data)
+          puts rendered if rendered.length > 0
+
+          # output parsedLines - producing 'data'
+          puts parsedLines.join( "" ) if options[:embed]
+
+        end
+
+      end
+
+    end # add_links
+
+    desc "api-calls SETUP [FILE]", "Create API calls tla+tools trace ouput in FILE (- for STDIN) for  SETUP"
+    long_desc <<-EOF
+
+    Create API calls using tla+tools trace output FILE (default 'gen/tlc.out').
+
+    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.
+      
+
+    #{MUSTACHE_OPTION}
+    EOF
+    
+    shared_options :mustache
+    shared_options :debug_mustache
+    shared_options :tla_dir
+    shared_options :src_dir
+    shared_options :state_dump
+    shared_options :filter_src
+    shared_options :solc_line
+    
+    def api_calls( setup, file=nil)
+
+      # unfreeze 'options' && set defaults (:tla_dir)
+      setOptions( setup )
+
+      # 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
+      
+      # Default FILE vs. given on cmd line
+      file = traceFile( setup, file )
+      
+      template = "{{>#{API_CALL_TEMPLATE} }}"
+      @logger.info "#{__method__}, template=#{template}"
+
+      # queue length of 1
+      q = nil
+      lastData = 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
+        elsif data.is_a?(Hash)
+          
+          # reason to output api-call
+          if data[:interface_started]
+
+            if q.nil?
+              # init qeueu
+              q = 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
+            end 
+            
+          end  # interface_started
+
+          # rememeber it
+          lastData = data
+          
+        end # elsif Hash?
+      end # block
+
+      if !q.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
+        
+      end # 
+      
+      
+    end
+    
+    
+    # @!endgroup
+    
+
+    # ------------------------------------------------------------------
+    # @!group No commans
+
+    no_commands do
+
+      # @param parsed [Hash] parsed model checking state
+      #      
+      # @param interfaceDefintion [type] interface for currently
+      #         running prorcess
+      #
+      # @param stepStarted [Boolean] true/false
+      #
+      # @param options [Hash] command line options to cli
+      #
+      #      
+      # @return [Hash] data with properties :options, :parsed,
+      #         :interface_started, :interface_executing, :interface,
+      #         :pc, :interface_opeation
+      def dataHash( parsed, stepStarted, interfaceDefintion, options )
+
+            data = {
+              :options =>  options,    # from command line
+              :parsed => parsed,       # from filter.rb: :line, :actionLine, :state_space
+              
+              # true/false = state_space[:step] ~ :interface_operation
+              :interface_started => stepStarted, # interfaceStarted?( interfaceDefintion[:interface_operation], parsed[:state_space] ),
+              :interface_executing => !stepStarted,  #interfaceExecuting?( interfaceDefintion[:interface_operation], parsed[:state_space] ),              
+              :interface => setInterfaceDefaults( getStep(parsed), interfaceDefintion ), # from interfaces.yaml
+              :pc => interfacePc( interfaceDefintion[:interface_operation], parsed[:state_space] ),
+              :interface_operation => interfaceOperation( interfaceDefintion[:interface_operation], parsed[:state_space] ),
+              #              :tst => ->( xx) { raise "tst #{xx}" },
+            }
+            @logger.debug "#{__method__}: data = #{data.to_yaml}" if @logger.debug?
+
+            data
+      end
+
+      # Process 'file', yield result
+      #
+      # @yields [String|Hash,Array<String>] data, parsedLines
+      def processInput( file  )
+
+        # toggle when step changes
+        currStep = nil
+        currTick = nil
+        
+        filterInput( file ) do |output|
+
+          # If string or a hash
+          
+          if output.is_a?( String)
+            # No change - or line changed in place
+            yield output, []  
+          elsif output.is_a?(Hash)
+            step = getStep( output[:state_space])
+            tick = getTick( output[:state_space] )
+            stepStarted = if currStep != step || currTick != tick then
+                            currStep = step
+                            currTick = tick
+                            true
+                          else
+                            false
+                          end
+            @logger.info "#{__method__}: step=#{step}, stepStarted=#{stepStarted}"
+
+            # Lookup in 'interfaces.yaml' for 'output[:state_space][:step]'
+            interfaceDefintion = getInterfaceDefinition(step, output[:state_space])
+            # data rendered: see mustache add-links.mustache and api-calls.mustache
+            data = dataHash( output, stepStarted, interfaceDefintion, options,  )
+            @logger.info "#{__method__}: interface_started=#{data[:interface_started]}, interface_executing=#{data[:interface_executing]}"
+
+            yield data, filtering.lines
+            # # template = "{{>add-links}}" or {{>api-calls}}
+            # rendered =  rendering.render(template, data)
+            # puts rendered if rendered.length > 0
+            # # Output original lines?
+            # puts filtering.lines.join( "" ) unless no_strings
+          else
+            raise "Unknown output.type #{output.class} for #{output}"
+          end
+        end # block for filterInput
+        
+      end # processInput
+
+      # Read input lines from file/stdin, filter these lines and yield
+      # filtered result
+      #
+      # @yield [String|Hash] filtered result where String is input
+      #        line (on line processed in place), Hash in parsed state
+      #        space
+      def filterInput( file )
+        input = if file != "-" then
+                  raise "Non existing file '#{file}'" unless File.exists?(file)
+                  File.open( file )
+                else
+                  STDIN
+                end
+        @logger.info "#{__method__}: starting, options=#{options}"
+        # $stdin.each_line do |line|        
+        input.each_line do |line|
+          @logger.debug "#{__method__}: read line #{line}" if @logger.debug?
+          filtered = filtering.filter(line)
+          @logger.debug "#{__method__}: filtered filtered=#{filtered}" if @logger.debug?
+          if !filtered.nil?
+            yield filtered
+          end
+        end
+        
+      end
+
+      # Implementation reads an array of interfaces from file
+      # 'interfaces.yaml' and converts it to a hash map
+      # interface[:interface_name] => interface read using
+      # "interfaces.yaml" file in 'tlaPath'.
+      #
+      # @return [Hash, {}] cached 'tlaPath/interfaces.yaml' file,
+      #         empty hash if :step not defined (for initial step)
+      
+      def getInterfaces( tlaPath )
+        return @interfaces if @interfaces
+        @logger.info "#{__method__}: tlaPath=#{tlaPath}"
+        @interfaces =
+          YAML.load_file( File.join( tlaPath, "interfaces.yaml")).inject( {}) do |memo,interface|
+          memo[interface[:interface_name]] = interface
+          memo
+        end || {}
+        @logger.info( "#{__method__}: @interfaces.keys=#{@interfaces.keys.join(',')}")        
+        @logger.debug( "#{__method__}: @interfaces=#{@interfaces.to_yaml}") if @logger.debug?
+        @interfaces
+      end
+
+      # @param step [String] step exectuting
+      #
+      # 
+      # @param stateSpace [Hash] hash containing state space dump from
+      #        trace file, particularly it defines property :step,
+      #        which is used as key to a hash from 'interfaces.yaml'.
+      #
+      # @return [Hash] definition of the interface
+      def getInterfaceDefinition( step, stateSpace )
+
+        @logger.debug "#{__method__}: stateSpace=#{stateSpace}" if @logger.debug?
+        # eg. p__customer_post_
+        return {} if step.nil?
+        
+        # e.g. _customer_post_
+        interfaceName = step2InterfaceName(step)
+        @logger.info "#{__method__}: interfaceName=#{interfaceName}"        
+
+        # expect 'interfaceName' to be defined in 'interfaces.yaml'
+        interfaceHash = getInterfaces(options[:tla_dir])[interfaceName] || {}
+        @logger.info "#{__method__}: interfaceName=#{interfaceName} -> interfaceHash=#{interfaceHash.to_yaml}"                
+
+        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
+      # 
+      # @param state_space [Hash] state space state parsed
+      #
+      #
+      # @return [String] state_space[pc][:step] of ??? if not possible
+      #         to find
+      def interfacePc(interface_operation, state_space)
+        return "??" if interface_operation.nil? || interface_operation.length == 0
+        return "??" if state_space[:pc][interface_operation].nil?
+        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 [String] interface_operation, ??? if not possible to
+      #         find
+      def interfaceOperation( interface_operation, state_space)
+        return "??" if interface_operation.nil? || interface_operation.length == 0
+        interface_operation
+      end
+
+      # def isStart?( interfaceOperation )
+      #   @logger.info "#{__method__}: interfaceOperation=#{interfaceOperation}"
+      #   return interfaceOperation.end_with? "_start"
+      # end
+
+      # @return [String] file, 'gen/<setup>/tlc.out' if file.nil?
+      def traceFile(setup, file)
+        file.nil? ? "gen/#{setup}/tlc.out" : file
+      end
+
+      # unfreeze 'options' && set defaults (:tla_dir)
+      def setOptions( setup )
+        # unfreeze options
+        new_options = options.dup
+        self.options = new_options
+        
+        # use default :tla_dir - unless given on cmd_line
+        options.merge!( :tla_dir => "gen/#{setup}/tla") if options[:tla_dir].nil?
+        
+      end
+
+      # @return [String] state space variable :step, which defines
+      #         sbuilder interface invoked by sbuilder environment
+      #         schedulr
+      def getStep( stateSpace)
+        stateSpace[:step]
+      end
+
+
+      # @return [String] step time tick
+      def getTick( stateSpace)
+        stateSpace[:now]
+      end
+
+
+      # Set defaults to interface definition to allow filtering to
+      # proceed
+      #
+      # @param step [String] Step, which parsed from state space dump 
+      # 
+      # @return [Hash] hash with :sourceModule guaranteed to exist
+      def setInterfaceDefaults( step, interfaceHash )
+        
+        interfaceHash[:interface_operation] ||= step || "** unidentified step ** "
+        interfaceHash[:source] ||= { }
+        interfaceHash[:source][:sourceModule] ||= false
+        interfaceHash[:source][:interface_operation] ||= "**undefined**"
+        interfaceHash
+      end
+
+      # @return [String] substring '_name' from 'p__name' 
+      def step2InterfaceName(step)
+        step[2..-1]
+      end
+
+    end # no_command
+
+    # @!endgroup no commans
+
+    
+        
+  end  
+end