scjson 0.3.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e5458d979377d6bb8afc2d6ba6290f228d0b85602ab0c00885fd5f3a0c8f7055
+  data.tar.gz: 0a5889b05002e6944b82ae94814aaefa33d008519164486d7d4db5a03f4a8ed3
+SHA512:
+  metadata.gz: 762b5feb6ce8d91f42b99fe7358528a02e1c8a462bc41cfcdf6721e17cb8a12be73f1d0ad60185005a312da607fbf49699ec5f272cf3b94cd9a631930609f945
+  data.tar.gz: 7e936f6fb3bf500d10e4618d2e19f62af93d124eec40642d162e6c2c939793718f561d6e329bae5c18bc363cf2d1db8f9c9f8bdc2d36e01668a16bf635eedd17

data/bin/scjson

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# Agent Name: ruby-cli-runner
+#
+# Part of the scjson project.
+# Developed by Softoboros Technology Inc.
+# Licensed under the BSD 1-Clause License.
+
+require_relative '../lib/scjson/cli'
+Scjson.main

data/lib/scjson/cli.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+# Agent Name: ruby-cli
+#
+# Part of the scjson project.
+# Developed by Softoboros Technology Inc.
+# Licensed under the BSD 1-Clause License.
+
+require 'pathname'
+require 'optparse'
+require 'fileutils'
+require_relative '../scjson'
+
+module Scjson
+  ##
+  # Display the CLI program header.
+  #
+  # @return [void]
+  def self.splash
+    puts "scjson #{VERSION} - SCXML <-> scjson converter"
+  end
+
+  ##
+  # Command line interface for scjson conversions.
+  #
+  # @param [Array<String>] argv Command line arguments provided by the user.
+  # @return [void]
+  def self.main(argv = ARGV)
+    options = { recursive: false, verify: false, keep_empty: false }
+    cmd = argv.shift
+    if cmd.nil? || %w[-h --help].include?(cmd)
+      puts(help_text)
+      return
+    end
+    parser = OptionParser.new do |opts|
+      opts.banner = ''
+      opts.on('-o', '--output PATH', 'output file or directory') { |v| options[:output] = v }
+      opts.on('-r', '--recursive', 'recurse into directories') { options[:recursive] = true }
+      opts.on('-v', '--verify', 'verify conversion without writing output') { options[:verify] = true }
+      opts.on('--keep-empty', 'keep null or empty items when producing JSON') { options[:keep_empty] = true }
+    end
+    path = argv.shift
+    parser.parse!(argv)
+    unless path
+      puts(help_text)
+      return
+    end
+    splash
+    case cmd
+    when 'json'
+      handle_json(Pathname.new(path), options)
+    when 'xml'
+      handle_xml(Pathname.new(path), options)
+    when 'validate'
+      validate(Pathname.new(path), options[:recursive])
+    else
+      puts(help_text)
+    end
+  end
+
+  ##
+  # Render the help text describing CLI usage.
+  #
+  # @return [String] A one-line summary of the CLI purpose.
+  def self.help_text
+    'scjson - SCXML <-> scjson converter and validator'
+  end
+
+  ##
+  # Convert SCXML inputs to scjson outputs.
+  #
+  # Handles both file and directory inputs, preserving relative paths when
+  # writing to directories.
+  #
+  # @param [Pathname] path Source file or directory.
+  # @param [Hash] opt Options hash controlling output and recursion behaviour.
+  # @return [void]
+  def self.handle_json(path, opt)
+    if path.directory?
+      out_dir = opt[:output] ? Pathname.new(opt[:output]) : path
+      pattern = opt[:recursive] ? '**/*.scxml' : '*.scxml'
+      Dir.glob(path.join(pattern).to_s).each do |src|
+        rel = Pathname.new(src).relative_path_from(path)
+        dest = out_dir.join(rel).sub_ext('.scjson')
+        convert_scxml_file(src, dest, opt[:verify], opt[:keep_empty])
+      end
+    else
+      dest = if opt[:output]
+               p = Pathname.new(opt[:output])
+               p.directory? ? p.join(path.basename.sub_ext('.scjson')) : p
+             else
+               path.sub_ext('.scjson')
+             end
+      convert_scxml_file(path, dest, opt[:verify], opt[:keep_empty])
+    end
+  end
+
+  ##
+  # Convert scjson inputs to SCXML outputs.
+  #
+  # Handles both file and directory inputs.
+  #
+  # @param [Pathname] path Source file or directory.
+  # @param [Hash] opt Options hash controlling output and recursion behaviour.
+  # @return [void]
+  def self.handle_xml(path, opt)
+    if path.directory?
+      out_dir = opt[:output] ? Pathname.new(opt[:output]) : path
+      pattern = opt[:recursive] ? '**/*.scjson' : '*.scjson'
+      Dir.glob(path.join(pattern).to_s).each do |src|
+        rel = Pathname.new(src).relative_path_from(path)
+        dest = out_dir.join(rel).sub_ext('.scxml')
+        convert_scjson_file(src, dest, opt[:verify])
+      end
+    else
+      dest = if opt[:output]
+               p = Pathname.new(opt[:output])
+               p.directory? ? p.join(path.basename.sub_ext('.scxml')) : p
+             else
+               path.sub_ext('.scxml')
+             end
+      convert_scjson_file(path, dest, opt[:verify])
+    end
+  end
+
+  ##
+  # Convert a single SCXML document to scjson.
+  #
+  # @param [String, Pathname] src Input SCXML file path.
+  # @param [Pathname] dest Target path for scjson output.
+  # @param [Boolean] verify When true, only validate round-tripping without writing.
+  # @param [Boolean] keep_empty When true, retain empty containers in JSON output.
+  # @return [void]
+  def self.convert_scxml_file(src, dest, verify, keep_empty)
+    xml_str = File.read(src)
+    begin
+      json_str = Scjson.xml_to_json(xml_str, !keep_empty)
+      if verify
+        Scjson.json_to_xml(json_str)
+        puts "Verified #{src}"
+      else
+        FileUtils.mkdir_p(dest.dirname)
+        File.write(dest, json_str)
+        puts "Wrote #{dest}"
+      end
+    rescue StandardError => e
+      warn "Failed to convert #{src}: #{e}"
+    end
+  end
+
+  ##
+  # Convert a single scjson document to SCXML.
+  #
+  # @param [String, Pathname] src Input scjson file path.
+  # @param [Pathname] dest Target SCXML file path.
+  # @param [Boolean] verify When true, only validate round-tripping without writing.
+  # @return [void]
+  def self.convert_scjson_file(src, dest, verify)
+    json_str = File.read(src)
+    begin
+      xml_str = Scjson.json_to_xml(json_str)
+      if verify
+        Scjson.xml_to_json(xml_str)
+        puts "Verified #{src}"
+      else
+        FileUtils.mkdir_p(dest.dirname)
+        File.write(dest, xml_str)
+        puts "Wrote #{dest}"
+      end
+    rescue StandardError => e
+      warn "Failed to convert #{src}: #{e}"
+    end
+  end
+
+  ##
+  # Validate a file or directory tree of SCXML and scjson documents.
+  #
+  # @param [Pathname] path File or directory to validate.
+  # @param [Boolean] recursive When true, traverse subdirectories.
+  # @return [void]
+  def self.validate(path, recursive)
+    success = true
+    if path.directory?
+      pattern = recursive ? '**/*' : '*'
+      Dir.glob(path.join(pattern).to_s).each do |f|
+        next unless File.file?(f)
+        next unless f.end_with?('.scxml', '.scjson')
+        success &= validate_file(f)
+      end
+    else
+      success &= validate_file(path.to_s)
+    end
+    exit(1) unless success
+  end
+
+  ##
+  # Validate a single SCXML or scjson document by round-tripping.
+  #
+  # @param [String] src Path to the document to validate.
+  # @return [Boolean] True when the document validates successfully.
+  def self.validate_file(src)
+    begin
+      data = File.read(src)
+      if src.end_with?('.scxml')
+        json = Scjson.xml_to_json(data)
+        Scjson.json_to_xml(json)
+      elsif src.end_with?('.scjson')
+        xml = Scjson.json_to_xml(data)
+        Scjson.xml_to_json(xml)
+      else
+        return true
+      end
+      true
+    rescue StandardError => e
+      warn "Validation failed for #{src}: #{e}"
+      false
+    end
+  end
+end

data/lib/scjson/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Agent Name: ruby-scjson-version
+#
+# Part of the scjson project.
+# Developed by Softoboros Technology Inc.
+# Licensed under the BSD 1-Clause License.
+
+module Scjson
+  VERSION = '0.1.4'
+end

data/lib/scjson.rb

@@ -0,0 +1,477 @@
+# frozen_string_literal: true
+
+# Agent Name: ruby-scjson
+#
+# Part of the scjson project.
+# Developed by Softoboros Technology Inc.
+# Licensed under the BSD 1-Clause License.
+
+require 'json'
+require 'nokogiri'
+
+require_relative 'scjson/version'
+
+# Canonical SCXML <-> scjson conversion for the Ruby agent.
+module Scjson
+  XMLNS = 'http://www.w3.org/2005/07/scxml'.freeze
+
+  ATTRIBUTE_MAP = {
+    'datamodel' => 'datamodel_attribute',
+    'initial' => 'initial_attribute',
+    'type' => 'type_value',
+    'raise' => 'raise_value'
+  }.freeze
+
+  COLLAPSE_ATTRS = %w[expr cond event target delay location name src id].freeze
+
+  SCXML_ELEMENTS = %w[
+    scxml state parallel final history transition invoke finalize datamodel data
+    onentry onexit log send cancel raise assign script foreach param if elseif
+    else content donedata initial
+  ].freeze
+
+  STRUCTURAL_FIELDS = %w[
+    state parallel final history transition invoke finalize datamodel data
+    onentry onexit log send cancel raise assign script foreach param if_value
+    elseif else_value raise_value content donedata initial
+  ].freeze
+
+  module_function
+
+  ##
+  # Convert an SCXML document to its canonical scjson form.
+  #
+  # @param [String] xml_str SCXML source document.
+  # @param [Boolean] omit_empty Remove empty containers when true.
+  # @return [String] Canonical scjson output.
+  def xml_to_json(xml_str, omit_empty = true)
+    doc = Nokogiri::XML(xml_str) { |cfg| cfg.strict.nonet }
+    root = locate_root(doc)
+    raise ArgumentError, 'Document missing <scxml> root element' unless root
+
+    map = element_to_hash(root)
+    collapse_whitespace(map)
+    remove_empty(map) if omit_empty
+    JSON.pretty_generate(map)
+  end
+
+  ##
+  # Convert a canonical scjson document back to SCXML.
+  #
+  # @param [String] json_str Canonical scjson input.
+  # @return [String] XML document encoded as UTF-8.
+  def json_to_xml(json_str)
+    data = JSON.parse(json_str)
+    remove_empty(data)
+    doc = Nokogiri::XML::Document.new
+    doc.encoding = 'utf-8'
+    root = build_element(doc, 'scxml', data)
+    doc.root = root
+    doc.to_xml
+  end
+
+  # ----------------------------
+  # Conversion helpers
+  # ----------------------------
+
+  def locate_root(doc)
+    doc.at_xpath('/*[local-name()="scxml"]')
+  end
+  private_class_method :locate_root
+
+  def local_name(node)
+    (node.name || '').split(':').last
+  end
+  private_class_method :local_name
+
+  def append_child(hash, key, value)
+    if hash.key?(key)
+      existing = hash[key]
+      if existing.is_a?(Array)
+        existing << value
+      else
+        hash[key] = [existing, value]
+      end
+    else
+      hash[key] = [value]
+    end
+  end
+  private_class_method :append_child
+
+  def wrap_list(value)
+    return [] if value.nil?
+    value.is_a?(Array) ? value : [value]
+  end
+  private_class_method :wrap_list
+
+  def any_element_to_hash(node)
+    result = { 'qname' => node.name }
+    text = node.text
+    result['text'] = text.to_s if text
+    unless node.attribute_nodes.empty?
+      attrs = {}
+      node.attribute_nodes.each do |attr|
+        attrs[attr.name] = attr.value
+      end
+      result['attributes'] = attrs unless attrs.empty?
+    end
+    unless node.element_children.empty?
+      children = node.element_children.map { |child| any_element_to_hash(child) }
+      result['children'] = children unless children.empty?
+    end
+    result
+  end
+  private_class_method :any_element_to_hash
+
+  def element_to_hash(node)
+    map = {}
+    local = local_name(node)
+
+    node.attribute_nodes.each do |attr|
+      name = local_name(attr)
+      value = attr.value
+      if local == 'transition' && name == 'target'
+        map['target'] = value.split(/\s+/)
+      elsif name == 'initial'
+        tokens = value.split(/\s+/)
+        key = local == 'scxml' ? 'initial' : 'initial_attribute'
+        map[key] = tokens
+      elsif name == 'version'
+        number = begin
+          Float(value)
+        rescue StandardError
+          nil
+        end
+        map['version'] = number ? number : value
+      elsif name == 'datamodel'
+        map['datamodel_attribute'] = value
+      elsif name == 'type'
+        map['type_value'] = value
+      elsif name == 'raise'
+        map['raise_value'] = value
+      elsif local == 'send' && name == 'delay'
+        map['delay'] = value
+      elsif local == 'send' && name == 'event'
+        map['event'] = value
+      elsif name == 'xmlns'
+        next
+      else
+        map[name] = value
+      end
+    end
+
+    if local == 'assign'
+      map['type_value'] ||= 'replacechildren'
+    end
+    if local == 'send'
+      map['type_value'] ||= 'scxml'
+      map['delay'] ||= '0s'
+    end
+    if local == 'invoke'
+      map['type_value'] ||= 'scxml'
+      map['autoforward'] ||= 'false'
+    end
+    if local == 'assign' && map.key?('id')
+      (map['other_attributes'] ||= {})['id'] = map.delete('id')
+    end
+    if map.key?('intial')
+      (map['other_attributes'] ||= {})['intial'] = map.delete('intial')
+    end
+
+    text_items = []
+    node.children.each do |child|
+      if child.element?
+        child_local = local_name(child)
+        if SCXML_ELEMENTS.include?(child_local)
+          key = case child_local
+                when 'if' then 'if_value'
+                when 'else' then 'else_value'
+                when 'raise' then 'raise_value'
+                else child_local
+                end
+          child_map = element_to_hash(child)
+          target_key = if child_local == 'scxml' && local != 'scxml'
+                         'content'
+                       elsif local == 'content' && child_local == 'scxml'
+                         'content'
+                       else
+                         key
+                       end
+          if %w[initial history].include?(local) && child_local == 'transition'
+            map[target_key] = child_map
+          else
+            append_child(map, target_key, child_map)
+          end
+        else
+          append_child(map, 'content', any_element_to_hash(child))
+        end
+      elsif child.text?
+        value = child.text
+        text_items << value if value && !value.strip.empty?
+      end
+    end
+
+    text_items.each { |text| append_child(map, 'content', text) }
+
+    if local == 'scxml'
+      map['version'] ||= 1.0
+      map['datamodel_attribute'] ||= 'null'
+    elsif local == 'donedata'
+      content = map['content']
+      if content.is_a?(Array) && content.length == 1
+        map['content'] = content.first
+      end
+    end
+
+    map
+  end
+  private_class_method :element_to_hash
+
+  def collapse_whitespace(value)
+    case value
+    when Array
+      value.each { |item| collapse_whitespace(item) }
+    when Hash
+      value.each do |key, val|
+        if (key.end_with?('_attribute') || COLLAPSE_ATTRS.include?(key)) && val.is_a?(String)
+          value[key] = val.tr("\n\r\t", ' ')
+        else
+          collapse_whitespace(val)
+        end
+      end
+    end
+  end
+  private_class_method :collapse_whitespace
+
+  PRESERVE_EMPTY_KEYS = %w[expr cond event target id name label text].freeze
+
+  ALWAYS_KEEP_KEYS = %w[else_value else final onentry].freeze
+
+  def remove_empty(value, key = nil)
+    case value
+    when Hash
+      value.keys.each do |key|
+        remove = remove_empty(value[key], key)
+        value.delete(key) if remove
+      end
+      value.empty? && !ALWAYS_KEEP_KEYS.include?(key)
+    when Array
+      value.reject! { |item| remove_empty(item, key) }
+      value.empty? && !ALWAYS_KEEP_KEYS.include?(key)
+    when NilClass
+      true
+    when String
+      if value.empty?
+        preserve_empty_string?(key) ? false : true
+      else
+        false
+      end
+    else
+      false
+    end
+  end
+  private_class_method :remove_empty
+
+  def preserve_empty_string?(key)
+    return false if key.nil?
+
+    key.end_with?('_attribute') ||
+      key.end_with?('_value') ||
+      PRESERVE_EMPTY_KEYS.include?(key)
+  end
+  private_class_method :preserve_empty_string?
+
+  def join_tokens(value)
+    case value
+    when Array
+      return unless value.all? { |item| item.is_a?(String) || item.is_a?(Numeric) }
+      value.map(&:to_s).join(' ')
+    when String
+      value
+    when Numeric
+      value.to_s
+    else
+      nil
+    end
+  end
+  private_class_method :join_tokens
+
+  def scxml_like?(hash)
+    return false unless hash.is_a?(Hash)
+
+    hash.key?('state') || hash.key?('parallel') || hash.key?('final') ||
+      hash.key?('datamodel') || hash.key?('datamodel_attribute') || hash.key?('version')
+  end
+  private_class_method :scxml_like?
+
+  def build_element(doc, name, map)
+    if map.is_a?(Array) && map.length == 1
+      return build_element(doc, name, map.first)
+    end
+
+    if map.is_a?(String)
+      element = Nokogiri::XML::Element.new(name, doc)
+      element.content = map
+      return element
+    end
+
+    raise ArgumentError, 'Expected object for element construction' unless map.is_a?(Hash)
+
+    element_name = map['qname'] || name
+    element = Nokogiri::XML::Element.new(element_name, doc)
+
+    if name == 'scxml'
+      element['xmlns'] ||= XMLNS
+    elsif !element_name.include?(':') && !SCXML_ELEMENTS.include?(element_name)
+      element['xmlns'] ||= ''
+    end
+
+    if map['text']
+      element.add_child(Nokogiri::XML::Text.new(map['text'], doc))
+    end
+
+    if map['attributes'].is_a?(Hash)
+      map['attributes'].each do |attr_name, attr_value|
+        element[attr_name] = attr_value if attr_value
+      end
+    end
+
+    map.each do |key, value|
+      next if %w[qname text attributes].include?(key)
+
+      case key
+      when 'content'
+        handle_content_nodes(doc, element, value, element_name)
+      when 'children'
+        wrap_list(value).each do |child_map|
+          next unless child_map.is_a?(Hash)
+          child_name = child_map['qname'] || 'content'
+          element.add_child(build_element(doc, child_name, child_map))
+        end
+      when 'other_attributes'
+        next unless value.is_a?(Hash)
+        value.each do |attr_name, attr_value|
+          element[attr_name] = join_tokens(attr_value) || attr_value.to_s
+        end
+      when ->(k) { k.end_with?('_attribute') }
+        attr_name = key.sub(/_attribute\z/, '')
+        joined = join_tokens(value)
+        element[attr_name] = joined if joined
+      when 'datamodel_attribute'
+        joined = join_tokens(value)
+        element['datamodel'] = joined if joined
+      when 'type_value'
+        joined = join_tokens(value)
+        element['type'] = joined if joined
+      when 'target'
+        joined = join_tokens(value)
+        element['target'] = joined if joined
+      when 'delay', 'event'
+        joined = join_tokens(value)
+        element[key] = joined if joined
+      when 'initial'
+        joined = join_tokens(value)
+        if joined
+          element['initial'] = joined
+        else
+          wrap_list(value).each do |child|
+            element.add_child(build_element(doc, 'initial', child))
+          end
+          next
+        end
+      when 'version'
+        element['version'] = value.to_s
+      else
+        child_name = case key
+                      when 'if_value' then 'if'
+                      when 'else_value' then 'else'
+                      when 'raise_value' then 'raise'
+                      else key
+                      end
+
+        if STRUCTURAL_FIELDS.include?(key) || %w[if_value else_value raise_value].include?(key)
+          wrap_list(value).each do |child|
+            element.add_child(build_element(doc, child_name, child))
+          end
+        elsif value.is_a?(Array) && value.all? { |item| !item.is_a?(Hash) }
+          element[key] = join_tokens(value)
+        elsif value.is_a?(Hash)
+          element.add_child(build_element(doc, child_name, value))
+        elsif !value.nil?
+          element[key] = value.to_s
+        end
+      end
+    end
+
+    element
+  end
+  private_class_method :build_element
+
+  def handle_content_nodes(doc, element, value, parent_name)
+    items = wrap_list(value)
+    items.each do |item|
+      if item.is_a?(String)
+        if parent_name == 'script'
+          element.add_child(Nokogiri::XML::Text.new(item, doc))
+        elsif parent_name == 'data'
+          element.add_child(Nokogiri::XML::Text.new(item, doc))
+        else
+          content_element = Nokogiri::XML::Element.new('content', doc)
+          content_element.add_child(Nokogiri::XML::Text.new(item, doc))
+          element.add_child(content_element)
+        end
+        next
+      end
+
+      next unless item.is_a?(Hash)
+
+      if parent_name == 'send' && item.keys == ['content']
+        wrap_list(item['content']).each do |inner|
+          content_element = Nokogiri::XML::Element.new('content', doc)
+          if inner.is_a?(String)
+            content_element.add_child(Nokogiri::XML::Text.new(inner, doc))
+          elsif inner.is_a?(Hash)
+            content_element.add_child(build_element(doc, 'content', inner))
+          end
+          element.add_child(content_element)
+        end
+        next
+      end
+
+      if parent_name == 'donedata' && item.keys == ['content']
+        content_element = Nokogiri::XML::Element.new('content', doc)
+        wrap_list(item['content']).each do |inner|
+          if inner.is_a?(String)
+            content_element.add_child(Nokogiri::XML::Text.new(inner, doc))
+          elsif inner.is_a?(Hash)
+            content_element.add_child(build_element(doc, 'content', inner))
+          end
+        end
+        element.add_child(content_element)
+        next
+      end
+
+      if item.key?('qname')
+        child = build_element(doc, item['qname'], item)
+        element.add_child(child)
+        next
+      end
+
+      child_name = if scxml_like?(item)
+                     'scxml'
+                   elsif parent_name == 'script'
+                     'content'
+                   else
+                     'content'
+                   end
+
+      if parent_name == 'data' && child_name == 'content'
+        element.add_child(Nokogiri::XML::Text.new(item['content'].to_s, doc))
+      else
+        child_element = build_element(doc, child_name, item)
+        element.add_child(child_element)
+      end
+    end
+  end
+  private_class_method :handle_content_nodes
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: scjson
+version: !ruby/object:Gem::Version
+  version: 0.3.3
+platform: ruby
+authors:
+- Softoboros Technology Inc.
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-10-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description:
+email:
+- info@softoboros.com
+executables:
+- scjson
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/scjson
+- lib/scjson.rb
+- lib/scjson/cli.rb
+- lib/scjson/version.rb
+homepage:
+licenses:
+- BSD-1-Clause
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: SCXML <-> scjson converter and validator
+test_files: []