scjson 0.3.3 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5458d979377d6bb8afc2d6ba6290f228d0b85602ab0c00885fd5f3a0c8f7055
-  data.tar.gz: 0a5889b05002e6944b82ae94814aaefa33d008519164486d7d4db5a03f4a8ed3
+  metadata.gz: a958225a6d29fbafd51d046f9c38d7c65ff98aa80c7727e321c6c68ac952c00a
+  data.tar.gz: 13acb52ec061e0ab3c0c09c76a9ea172370938e6770efa7ee69a162183365fe9
 SHA512:
-  metadata.gz: 762b5feb6ce8d91f42b99fe7358528a02e1c8a462bc41cfcdf6721e17cb8a12be73f1d0ad60185005a312da607fbf49699ec5f272cf3b94cd9a631930609f945
-  data.tar.gz: 7e936f6fb3bf500d10e4618d2e19f62af93d124eec40642d162e6c2c939793718f561d6e329bae5c18bc363cf2d1db8f9c9f8bdc2d36e01668a16bf635eedd17
+  metadata.gz: b958161b70d561ccfdc324b1855a5f1a710edb0506798764c83e9dc8d26ef2989e2d8c1953a4a05834a01872b2b832adfde4d3a000e8e05f71b13f5c02a6e8a2
+  data.tar.gz: 5991fbfe49a89974bedf45a8030cdf5fead46e001fd3851ca14ac5f1131a8519ba3f16d487499a839d7a97c208e0652de82b6ffb7a48c439ab2cdb753f5e9188

data/LEGAL.md

@@ -0,0 +1,5 @@
+# Legal Information
+
+This package is part of the **scjson** project. All original Ruby source code is licensed under the BSD\u00A01-Clause license.
+
+Examples derived from the W3C SCXML specification and the Alex Zhornyak tutorial remain under their respective licenses, described in the repository root `LEGAL.md` file.

data/LICENSE

@@ -0,0 +1,21 @@
+BSD 1-Clause License
+
+Copyright (c) 2025, Softoboros Technology Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,37 @@
+<p align="center"><img src="https://raw.githubusercontent.com/SoftOboros/scjson/main/scjson.png" alt="scjson logo" width="200"/></p>
+
+# scjson Ruby Gem
+
+This directory contains the Ruby implementation of **scjson**. The gem provides a command line tool and library functions to convert between `.scxml` and `.scjson` files.
+
+## Installation
+
+```bash
+gem install scjson
+```
+
+You can also install from a local checkout:
+
+```bash
+cd ruby && gem build scjson.gemspec && gem install scjson-*.gem
+```
+
+## Command Line Usage
+
+```bash
+scjson json path/to/machine.scxml
+scjson xml path/to/machine.scjson
+scjson validate path/to/dir -r
+```
+
+## Library Usage
+
+```ruby
+require 'scjson'
+
+document = Scjson::Types::ScxmlProps.new
+json = document.to_json
+round_trip = Scjson::Types::ScxmlProps.from_json(json)
+```
+
+All source code in this directory is released under the BSD 1-Clause license. See [LICENSE](./LICENSE) and [LEGAL.md](./LEGAL.md) for details.

data/lib/scjson/cli.rb

@@ -10,6 +10,7 @@ require 'pathname'
 require 'optparse'
 require 'fileutils'
 require_relative '../scjson'
+require_relative 'engine'
 
 module Scjson
   ##
@@ -17,7 +18,7 @@ module Scjson
   #
   # @return [void]
   def self.splash
-    puts "scjson #{VERSION} - SCXML <-> scjson converter"
+    puts "scjson #{VERSION} - SCXML/SCML execution, SCXML <-> scjson converter & validator"
   end
 
   ##
@@ -32,6 +33,9 @@ module Scjson
       puts(help_text)
       return
     end
+    if cmd == 'engine-trace'
+      return engine_trace(argv)
+    end
     parser = OptionParser.new do |opts|
       opts.banner = ''
       opts.on('-o', '--output PATH', 'output file or directory') { |v| options[:output] = v }
@@ -63,7 +67,7 @@ module Scjson
   #
   # @return [String] A one-line summary of the CLI purpose.
   def self.help_text
-    'scjson - SCXML <-> scjson converter and validator'
+    'scjson - SCXML <-> scjson converter, validator, and engine trace'
   end
 
   ##
@@ -216,4 +220,84 @@ module Scjson
       false
     end
   end
+
+  ##
+  # Emit a standardized JSONL execution trace for a document.
+  #
+  # Mirrors the Python CLI flags where appropriate, using Ruby idioms.
+  #
+  # @param [Array<String>] argv Command line arguments following 'engine-trace'.
+  # @return [void]
+  def self.engine_trace(argv)
+    input = nil
+    events = nil
+    out = nil
+    is_xml = false
+    leaf_only = false
+    omit_actions = false
+    omit_delta = false
+    omit_transitions = false
+    advance_time = 0.0
+    ordering = 'tolerant'
+    max_steps = nil
+    strip_step0_noise = false
+    strip_step0_states = false
+    keep_cond = false
+    defer_done = true
+
+    parser = OptionParser.new do |opts|
+      opts.banner = 'scjson engine-trace [options]'
+      opts.on('-I', '--input PATH', 'SCJSON/SCXML document') { |v| input = v }
+      opts.on('-e', '--events PATH', 'JSONL stream of events') { |v| events = v }
+      opts.on('-o', '--out PATH', 'Destination trace file (stdout by default)') { |v| out = v }
+      opts.on('--xml', 'Treat input as SCXML') { is_xml = true }
+      opts.on('--leaf-only', 'Restrict configuration/entered/exited to leaf states') { leaf_only = true }
+      opts.on('--omit-actions', 'Omit actionLog entries from the trace') { omit_actions = true }
+      opts.on('--omit-delta', 'Omit datamodelDelta entries from the trace') { omit_delta = true }
+      opts.on('--omit-transitions', 'Omit firedTransitions entries from the trace') { omit_transitions = true }
+      opts.on('--advance-time N', Float, 'Advance time by N seconds before processing events') { |v| advance_time = v }
+      opts.on('--ordering MODE', ['tolerant', 'strict', 'scion'], 'Ordering policy (tolerant|strict|scion)') { |v| ordering = v }
+      opts.on('--defer-done', 'Defer done.invoke processing to next step (default)') { defer_done = true }
+      opts.on('--no-defer-done', 'Process done.invoke within the same step') { defer_done = false }
+      opts.on('--max-steps N', Integer, 'Maximum steps to process') { |v| max_steps = v }
+      opts.on('--strip-step0-noise', 'Clear datamodelDelta and firedTransitions at step 0') { strip_step0_noise = true }
+      opts.on('--strip-step0-states', 'Clear enteredStates and exitedStates at step 0') { strip_step0_states = true }
+      opts.on('--keep-cond', 'Keep transition cond fields (default scrubs cond)') { keep_cond = true }
+      opts.on('-h', '--help', 'Show help') do
+        puts opts
+        return
+      end
+    end
+
+    begin
+      parser.parse!(argv)
+    rescue OptionParser::ParseError => e
+      warn e.message
+      puts parser
+      return
+    end
+    unless input
+      warn 'Missing required --input'
+      puts parser
+      return
+    end
+
+    Scjson::Engine.trace(
+      input_path: input,
+      events_path: events,
+      out_path: out,
+      xml: is_xml,
+      leaf_only: leaf_only,
+      omit_actions: omit_actions,
+      omit_delta: omit_delta,
+      omit_transitions: omit_transitions,
+      advance_time: advance_time,
+      ordering: ordering,
+      max_steps: max_steps,
+      strip_step0_noise: strip_step0_noise,
+      strip_step0_states: strip_step0_states,
+      keep_cond: keep_cond,
+      defer_done: defer_done
+    )
+  end
 end