tla-trace-arch 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9881430239c5bc604dcd31251f5d3d4f77f5cc50
-  data.tar.gz: 6ec39a64cbf83df55b596fd361cd477676a72cb9
+  metadata.gz: 391d89ba6d8725af0ffb27dc83c66e4b5829bdc1
+  data.tar.gz: e4b94cea107ae1cf970354839362263a01d54a6f
 SHA512:
-  metadata.gz: f48c2e3b8ae5dddb60c2c1cda737d396c6333976929130d094347c9d6e47c3c17a0c1399b24eb5771b7bb092849e150ce7c10192b7e8355e3de8e860a70f3684
-  data.tar.gz: 5241e5d5ba18f984fba05eecdf1953dc8b104f25520051000cf7a3c93e3375815aebf2dd7316a7421b320730e5a376b1b03abeea9d4c956a00130fa6823dfc11
+  metadata.gz: 86c061f880c452907783d9a9bb6ffc23689e1bc040f45884ff90eeef716ef2e5d7a89e6266372164765f01ed5a9eee81e28452dd24e24500148ada6260526731
+  data.tar.gz: 0972e2f0a7e1ca410e60e927a5ccf2e5eaedd1a74b6487876c5d0c4ce460c78929af48dd5c0d39e6192eaec426604dcb3dd3fafa4ca7a87f07dda3c937cbb1af

data/README.org

@@ -2,7 +2,8 @@
 
 A set of [[https://mustache.github.io/mustache.5.html][mustache]] templates extending [[https://github.com/jarjuk/tla-trace-filter][tla-trace-filter]] -tool to create
 a self extracting achieve for API traces generated, when [[http://research.microsoft.com/en-us/um/people/lamport/tla/tools.html][model
-checking]] formal models created by [[https://github.com/jarjuk/tla-sbuilder][Sbuilder]] -tool.
+checking]] formal models created by [[https://github.com/jarjuk/tla-sbuilder][Sbuilder]] -tool. Includes also APIs
+for iterating files extracted from the archive.
 
 ** Use case 
 
@@ -31,18 +32,24 @@ being developed by the developer.
   - [X] SHA1 hash to guarantee achieve integrity
   - [X] Archive creation time stamp, hostname and userid
   - [ ] Name of property generating API Trace
-- Archive content for each Api Trace Step
+- Content of Api Trace step in the archive
   - [X] Before state 
   - [X] Name of interface operation and parameter values
   - [X] Return values and return status
   - [X] After state
+  - [X] Defaults YAML dump for =beforeState=, =ap_input=, =api_return=, =afterState=
 - Archive commands
   - [X] Help
   - [X] List steps
   - [X] Extract by step number
   - [X] Extract by interface name
-- Archive options
+- Name of extracted file
+  - [X] File name pattern <step>-<inp|api|ret|out>-<interface>.<SHA1>
+- Archive extract options
   - [X] Define target directory for achieve extract
+- API to acess the extracted files 
+  - [X] =Sbuilder::TlaTraceArch::IterateArchiveFiles.iteratateTestCases=
+  - [X] =Sbuilder::TlaTraceArch::ExtractArchiveFile.parserTestCaseFile=
 - Extension points
   - [X] Control content of Api Trace Step elements per interface name
 
@@ -66,8 +73,15 @@ and run
 bundle install
 #+END_SRC
 
+
 ** Usage
 
+For a complete example, starting with installation of sbuilder- tool
+and creating a formal model, refer to  [[./test-trace.org][test-trace.org]].
+
+
+*** Create Archive
+
 =tla-trace-filter= uses TLA+tools model checker log output and a YAML
 file mapping model checker log output to application interfaces.
 
@@ -107,6 +121,8 @@ export SETUP=setup1;  bundle exec  tla-trace-filter.rb api-calls $SETUP --src-di
 chmod +x arch.sh
 #+END_SRC
 
+*** Using the Archive 
+
 To show instructions for using the archive run
 
 #+name: exe-arch
@@ -144,8 +160,35 @@ $ usage
     
 #+end_example
 
-For a complete example, starting with installation of sbuilder- tool
-and with creating a formal model, refer [[./test-trace.org][test-trace.org]].
+To extract files in the archive =arch.sh= for API trace step =1= into
+an existing directory =tmp= run
+
+#+BEGIN_SRC sh :eval no
+./arch.sh --dir tmp  step 1
+#+END_SRC
+
+
+*** Iterate extracted archive files in Ruby
+
+Files extracted from an archive can be iterated and parsed using APIs
+in =tla_trace_arch= GEM.
+
+#+BEGIN_SRC ruby :eval no
+require 'tla_trace_arch'
+require 'set'
+
+# Iterate api-steps for 'interface' extracted into directory 'ARGV[0]'
+Sbuilder::TlaTraceArch::ReadArchiveFile.iterateApiTraceSteps(  ARGV[0], interface ) do |sha1,apiTraceStep|
+  # parse YAML data && output
+  puts "sha1 : #{sha1} = #{apiTraceStep["00-step"]["sha1"]} step=#{apiTraceStep["00-step"]["step"]} interface=#{apiTraceStep["00-step"]["interface"]}" 
+  puts "beforeState #{apiTraceStep["01-inp"]}"
+  puts "api_input   #{apiTraceStep["02-api"]}"
+  puts "api_return  #{apiTraceStep["03-ret"]}"
+  puts "afterState  #{apiTraceStep["04-out"]}"
+end
+
+#+END_SRC
+
 
 ** Extension point =api-call-init=
 

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/lib/test-runner/configuration.rb

@@ -0,0 +1,18 @@
+
+module Sbuilder
+  module TlaTraceArch
+    class Configuration
+
+      # @# @!attribute [type] extract_filename_parser set regexp
+      #             parser to parse names of extracted archive files
+      attr_writer :extract_filename_parser
+
+      # @return [String] regexp parser to parse names of extracted
+      #             archive files
+      def extract_filename_parser
+        self.extract_filename_parser = @extract_filename_parser || Sbuilder::TlaTraceArch::EXTRACT_FILENAME_PARSER
+      end
+
+    end
+  end
+end

data/lib/test-runner/iterate_archive_files.rb

@@ -0,0 +1,85 @@
+
+module Sbuilder
+  module TlaTraceArch
+    module IterateArchiveFiles
+
+      # # ------------------------------------------------------------------
+      # @!group PUblic services
+
+      # iterate apiTraceStep -files files in 'dir' and combine files
+      # with same SHA1 value to ApiTraceStep test hashes. These hashes
+      # are validated using 'validateTestCase' method.
+      #
+      # @param interface [String] if given process only files for
+      #       'interface'
+      #      
+      #
+      #
+      # @return [Hash] of test case keyed by sha1
+      def iteratateSbuilderTestCases( dir, interface=nil )
+        testCases = {}
+        iterateFiles(dir) do |fileName|
+          # valid file name parses 'sha1' and type 'type' 
+          testInputMatch = matchTestCase( fileName )
+          next if testInputMatch.nil? || !interface.nil? && testInputMatch["interface"] != interface
+          if ( testInputMatch ) then
+            testCases[testInputMatch["sha1"] ] ||= {}
+            testCases[ testInputMatch["sha1"] ][testInputMatch["type"]] = testInputMatch.merge({ "dir" => dir, "fileName" => fileName } )
+          end
+        end
+
+        # report error if no data found
+        raise "No test input found in directory '#{dir}'" if testCases == {}
+        
+        # Validata test case - raise error for invalid
+        testCases.each do |sha1,testCase|
+          validateTestCase testCase, sha1
+        end
+        
+        testCases
+      end
+      module_function :iteratateSbuilderTestCases
+      public :iteratateSbuilderTestCases
+
+
+      # @!endgroup
+
+      # # ------------------------------------------------------------------
+      # @!group Helpers
+
+      # check if 'fileName' can parsed with api_step_mask
+      
+      def matchTestCase fileName
+        regu  = Sbuilder::TlaTraceArch.configuration.extract_filename_parser
+        regu  = "(?<step>\\d{3})-(?<type>\\d+-\\w{3})-(?<interface>[^\\.]+)\\.(?<sha1>[0-9a-fA-F]{40})"
+        found = fileName.match( /#{regu}/ )
+        found = found.names.zip( found.captures).to_h unless found.nil?
+        found
+      end
+      module_function :matchTestCase
+
+
+      # yield files in
+      # #{Sbuilder::TestRunner.configuration.api_step_directory}
+      # directory
+      def iterateFiles( dir = Sbuilder::TestRunner.configuration.api_step_directory )
+        raise "No such directory #{dir}" unless Dir.exists?( dir )
+        Dir.foreach( dir ).
+          select { |e| File.file?("#{dir}/#{e}") } .
+          each { |f| yield f }
+      end
+      module_function :iterateFiles
+
+      # Validate that test case 'testCase' defines 4 keys (for
+      # beforeState, api_input, api_return and  afterState)
+      def validateTestCase( testCase, sha1 )
+        raise "Missing test input for sha1=#{sha1}, found input #{testCase.keys.join(',')}"  if testCase.keys.length != 4
+      end
+      module_function :validateTestCase
+
+      
+      # @!endgroup
+      
+    end
+  end
+end

data/lib/test-runner/read_archive_file.rb

@@ -0,0 +1,68 @@
+require 'yaml'
+module Sbuilder
+  module TlaTraceArch
+    
+    class ParserErrorException < Exception; end
+    module ReadArchiveFile
+
+      # Read (and parse) API trace step from files pointed by
+      # 'apiStepFiles' hash.
+      #
+      # @param apiStepFiles [Hash] hash with values pointing to a file to
+      #     read (parse) API trace step
+      #      
+      #
+      # @return [Hash] A hash with values in 'apiStepFiles' replaces by
+      #                data parsed from files pointed by apiStepFiles
+      #                'dir' and 'fileNmae' properties. The has
+      #                includes also a new key "00-step" with value
+      #                hash with properties 'interface' and 'sha'
+      def readApiTraceStep( apiStepFiles )
+        apiStepFiles.inject( { "00-step" => {} } ) do |ret, (k,v)|
+          if ret.keys.length == 1
+            ret[ret.keys.first] = {
+              "interface" => v["interface"],
+              "sha1" => v["sha1"],
+              "step" => v["step"],              
+            }
+          end
+          ret[k] = parseArchiveFile(  File.join( v["dir"], v["fileName"] ))
+          ret
+        end
+      end
+      module_function :readApiTraceStep
+      public :readApiTraceStep
+
+
+      # 
+      def iterateApiTraceSteps( dir, interface )
+        IterateArchiveFiles.iteratateSbuilderTestCases( dir, interface).each do |sha1,apiStepFiles|
+          apiTraceStep = readApiTraceStep( apiStepFiles )
+          yield sha1, apiTraceStep
+        end
+      end
+      module_function :iterateApiTraceSteps
+      public :iterateApiTraceSteps
+
+      # Load YAML data from 'filePath'. Raise exception if 'filePath'
+      # does not exist or YAML -load error.
+      def parseArchiveFile( filePath )
+
+        raise "No such file #{filePath}" unless File.exists? filePath
+        begin 
+          YAML.load_file( filePath )
+        rescue Exception => err
+            msg = <<-HERE
+            Could not parse file #{filePath}
+
+            #{err}: when trying to parse YAML
+            HERE
+            raise ParserErrorException,  msg, err.backtrace
+        end
+      end
+      module_function :parseArchiveFile
+      public :parseArchiveFile
+      
+    end
+  end
+end

data/lib/tla_trace_arch.rb

@@ -0,0 +1,26 @@
+require_relative "test-runner/configuration.rb"
+require_relative "test-runner/iterate_archive_files.rb"
+require_relative "test-runner/read_archive_file.rb"
+
+
+module Sbuilder
+  module TlaTraceArch
+
+    # Default regexp to parse extracted files
+    EXTRACT_FILENAME_PARSER = "xx"
+    
+    def self.configuration
+      @configuration ||= Sbuilder::TlaTraceArch::Configuration.new
+    end
+
+    
+    # Configure Sbuilder::TestRunner
+    def self.configure
+      yield configuration if block_given?
+    end
+    # module_function :configure
+
+    
+    
+  end
+end

data/mustache/api-call-init.mustache

@@ -1,28 +1,31 @@
 {{!
 
-   Override api-call-init.mustache in tla-trace-filter GEM
+   Override api-call-init.mustache in tla-trace-filter GEM.
+
+   Default creates yaml-dumps for step beforeState, api_input,
+   api_return, and afterState.
 
 }}
 {{#API_BEFORE_STATE_INIT}}
-default: arch-demo-beforeState
+default: arch-yaml-beforeState
 {{/API_BEFORE_STATE_INIT}}{{!
 
  Configure templates to render API CALL
  
 }}{{#API_CALL_INIT}}
-default: arch-demo-api_input
+default: arch-yaml-api_input
 {{/API_CALL_INIT}}{{!
 
  Configure templates to render API_RETURN
  
 }}{{#API_RETURN_INIT}}
-default: arch-demo-api_return
+default: arch-yaml-api_return
 {{/API_RETURN_INIT}}{{!
 
     Configure templates to render state after API call
     
 }}{{#API_AFTER_STATE_INIT}}
-default: arch-demo-afterState
+default: arch-yaml-afterState
 {{/API_AFTER_STATE_INIT}}{{!
 
   Do not output new-line

data/mustache/api-call-post.mustache

@@ -3,5 +3,7 @@
  api-call-post.mustache: Override this template to change wrapping around api-calls
 
 }}__END_OF_PAY_LOAD__
+Extracting archive created on {{META.timestamp}} 
 {{{sha1.inspect}}}
+Next line is the SHA1 for 1 .. __END_OF_PAY_LOAD__
 {{{sha1.hexdigest}}}

data/mustache/arch-call-script.mustache

@@ -7,7 +7,7 @@ arch-call-script.mustache: self extracting stcript
 #!/bin/bash
 
 echo ""
-echo "Self extracting archive created on {{META.timestamp}} by {{META.user}}@{{META.hostname}}"
+echo "Self create by {{META.user}}@{{META.hostname}}"
 echo ""
 
 # functions
@@ -83,6 +83,9 @@ EOF
              print msg
          }
       }
+      function isListCmd() {
+      	     return cmd == "list"
+      }
       function escape_pattern(pat,   safe) {
 	safe = pat
 	gsub(/[][^$.*?+{}\\()|]/, "\\\\&", safe)
@@ -91,7 +94,7 @@ EOF
       # @return [String] name of of file where to extract
       function extractFileName( dir, prefix ) {
          # current_step using 3 digits
-         return dir "/" sprintf("%03d", current_step) "-" prefix "-"  current_interface_implementation  "-" sha1Archive
+         return dir "/" sprintf("%03d", current_step) "-" prefix "-"  current_interface_implementation  "." sha1Archive
       }
       BEGIN {
          extract_file=""
@@ -105,6 +108,7 @@ EOF
 	    # step_start= step_start ".*interface=" escape_pattern(interface,interface)
 	    step_start= step_start ".*interface=" interface
          }
+	 dbg( "cmd==" cmd " for interface=" interface ", isListCmd=" isListCmd() )
          dbg( "step_start=" step_start " for interface=" interface )
          # identify rules
 	 step_end="^__END_OF_STEP__"
@@ -139,25 +143,33 @@ EOF
       # choose extract file 
       in_step && match( $0, beforeState_start ) {
 	  extract_file = extractFileName( extract_dir, "01-inp" )
-          print "" > extract_file 
+	  if ( isListCmd() )  {
+              print "" > extract_file 
+          }
           dbg( "in_step && beforeState_start:" $0 ", extract_file=" extract_file)
 	  next # getline
       } 
       in_step && match( $0, api_call_start ) {
 	  extract_file = extractFileName( extract_dir, "02-api" )
-          print "" > extract_file 
+	  if ( isListCmd() )  {
+              print "" > extract_file 
+          }
           dbg( "in_step && api_call_start:" $0 ", extract_file=" extract_file )
 	  next # getline
       } 
       in_step && match( $0, api_return_start ) {
 	  extract_file = extractFileName( extract_dir, "03-ret" )
-          print "" > extract_file 
+	  if ( isListCmd() )  {
+              print "" > extract_file 
+          }
           dbg( "in_step && api_return_start:" $0 ", extract_file=" extract_file )
 	  next # getline
       } 
       in_step && match( $0, afterState_start ) {
 	  extract_file = extractFileName( extract_dir, "04-out" )
-          print "" > extract_file 
+	  if ( isListCmd() )  {
+              print "" > extract_file 
+          }
           dbg( "in_step && afterState_start:" $0 ", extract_file=" extract_file  )
 	  next # getline
       } 
@@ -183,7 +195,7 @@ EOF
 	  next # getline
       }
       # extract?
-      cmd != "list" && length(extract_file) > 0 {
+      ( ! isListCmd() && length(extract_file) > 0 ) {
           print $0 >> extract_file 
       }
       # done

data/mustache/arch-yaml-afterState.mustache

@@ -0,0 +1,11 @@
+{{!
+   arch-yaml-afterState: default template outputting YAML dump for
+   API trace `afterState`
+}}#
+# Step {{now}} call to {{interface.interface_operation}} afterState
+{{#DUMP_YAML}}afterState{{/DUMP_YAML}}
+{{!
+Local Variables:
+require-final-newline: nil
+End:
+}}

data/mustache/arch-yaml-api_input.mustache

@@ -0,0 +1,11 @@
+{{!
+   arch-yaml-api_input: default template outputting YAML dump for
+   API trace `api_input`
+}}#
+# Step {{now}} call to {{interface.interface_operation}} api_input
+{{#DUMP_YAML}}api_input{{/DUMP_YAML}}
+{{!
+Local Variables:
+require-final-newline: nil
+End:
+}}

data/mustache/arch-yaml-api_return.mustache

@@ -0,0 +1,11 @@
+{{!
+   arch-yaml-api_return: default template outputting YAML dump for
+   API trace `api_return`
+}}#
+# Step {{now}} call to {{interface.interface_operation}} api_return
+{{#DUMP_YAML}}api_return{{/DUMP_YAML}}
+{{!
+Local Variables:
+require-final-newline: nil
+End:
+}}

data/mustache/arch-yaml-beforeState.mustache

@@ -0,0 +1,12 @@
+{{!
+   arch-yaml-beforeState: default template outputting YAML dump for
+   API trace `beforeState`
+}}#
+#
+# Step {{now}} call to {{interface.interface_operation}} beforeState
+{{#DUMP_YAML}}beforeState{{/DUMP_YAML}}
+{{!
+Local Variables:
+require-final-newline: nil
+End:
+}}

data/tla-trace-arch.gemspec

@@ -22,6 +22,9 @@ Gem::Specification.new do |s|
     to create a self extracting achieve for API traces generated, when
     model checking formal models created by [tla-Sbuilder] -tool.
 
+    Also includes Ruby classes to extract test cases from archive
+    extract.
+
     Use case:
 
     Formal models, built using [tla-sbuilder], and model checked using
@@ -52,13 +55,13 @@ Gem::Specification.new do |s|
 EOF
 
   s.authors         = ["jarjuk"]
-  s.files           = ["README.org", "VERSION", "#{s.name}.gemspec" ]  | Dir.glob("mustache/**/*") 
+  s.files           = ["README.org", "VERSION", "#{s.name}.gemspec" ]  | Dir.glob("mustache/**/*") | Dir.glob("lib/**/*") 
   s.require_paths   = [ "lib" ]
   # s.executables     = [ "tla-trace-filter.rb" ]
   s.license         = 'MIT'
 
   s.required_ruby_version = '~> 2', ">=2.3"
 
-  s.add_runtime_dependency 'tla-trace-filter', '~>0.0', ">=0.0.4"  
+  s.add_runtime_dependency 'tla-trace-filter', '~>0.0', ">=0.0.6"  
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tla-trace-arch
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - jarjuk
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-01-03 00:00:00.000000000 Z
+date: 2018-02-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tla-trace-filter
@@ -19,7 +19,7 @@ dependencies:
         version: '0.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.0.4
+        version: 0.0.6
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,10 +29,11 @@ dependencies:
         version: '0.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.0.4
+        version: 0.0.6
 description: "\n    A set of [mustache] templates extending [tla-trace-filter] -tool\n
   \   to create a self extracting achieve for API traces generated, when\n    model
-  checking formal models created by [tla-Sbuilder] -tool.\n\n    Use case:\n\n    Formal
+  checking formal models created by [tla-Sbuilder] -tool.\n\n    Also includes Ruby
+  classes to extract test cases from archive\n    extract.\n\n    Use case:\n\n    Formal
   models, built using [tla-sbuilder], and model checked using\n    [TLA+tools]], can
   generate /API Traces/, which represent\n    end-to-end scenarios executing across
   system services in the\n    formal model. An API Trace is composed of steps, with
@@ -56,6 +57,10 @@ extra_rdoc_files: []
 files:
 - README.org
 - VERSION
+- lib/test-runner/configuration.rb
+- lib/test-runner/iterate_archive_files.rb
+- lib/test-runner/read_archive_file.rb
+- lib/tla_trace_arch.rb
 - mustache/api-call-after-state-post.mustache
 - mustache/api-call-after-state-pre.mustache
 - mustache/api-call-before-state-post.mustache
@@ -72,10 +77,10 @@ files:
 - mustache/api-call-step-post.mustache
 - mustache/api-call-step-pre.mustache
 - mustache/arch-call-script.mustache
-- mustache/arch-demo-afterState.mustache
-- mustache/arch-demo-api_input.mustache
-- mustache/arch-demo-api_return.mustache
-- mustache/arch-demo-beforeState.mustache
+- mustache/arch-yaml-afterState.mustache
+- mustache/arch-yaml-api_input.mustache
+- mustache/arch-yaml-api_return.mustache
+- mustache/arch-yaml-beforeState.mustache
 - tla-trace-arch.gemspec
 homepage: 
 licenses:

data/mustache/arch-demo-afterState.mustache

@@ -1,7 +0,0 @@
-now: {{{outputState.now.to_yaml}}}
-eth_address: {{{outputState.eth_address.to_yaml}}}
-{{!
-Local Variables:
-require-final-newline: nil
-End:
-}}

data/mustache/arch-demo-api_input.mustache

@@ -1,6 +0,0 @@
-input: {{{api_input}}}
-{{!
-Local Variables:
-require-final-newline: nil
-End:
-}}

data/mustache/arch-demo-api_return.mustache

@@ -1,6 +0,0 @@
-{{{api_return}}}
-{{!
-Local Variables:
-require-final-newline: nil
-End:
-}}

data/mustache/arch-demo-beforeState.mustache

@@ -1,9 +0,0 @@
-now: {{{beforeState.now}}}
-eth_address: {{{beforeState.eth_accounts.to_a}}}
-eth_storageRoot: {{{beforeState.eth_storageRoot.to_a}}}
-eth_addressPool: {{{beforeState.eth_addressPool.to_a}}}
-{{!
-Local Variables:
-require-final-newline: nil
-End:
-}}