Crate harel 

Harel - SCXML Parser and Serializer for Rust

Harel is a Rust crate that provides a comprehensive implementation for parsing, validating, and serializing SCXML (State Chart XML) documents in accordance with the W3C SCXML 1.0 specification.

SCXML is an XML-based markup language for describing state machines, commonly used in applications requiring complex state management, such as voice response systems, user interfaces, and workflow engines.

Key Features

• Parsing: Parse SCXML from strings or files into structured Rust types, with support for both strict and relaxed namespace handling.
• Validation: Perform structural and semantic validation to ensure compliance with the SCXML specification, including checks for unique IDs, valid transition targets, and datamodel constraints.
• Serialization: Convert parsed SCXML structures back to well-formatted XML strings, preserving the original structure and attributes.
• Relaxed Parsing Mode: Optionally parse SCXML documents without requiring namespace declarations, useful for legacy or non-standard files.
• Comprehensive Element Support: Handles core SCXML elements, transitions, data models, executable content, and external invocations.

Usage

Add Harel to your Cargo.toml:

[dependencies]
harel = "0.1.0"  # Replace with the actual version

Quick Example

use harel::{parse_scxml, validate, to_xml, ParseOptions};

let xml = r#"<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" initial="start">
    <state id="start">
        <transition event="go" target="end"/>
    </state>
    <final id="end"/>
</scxml>"#;

// Parse the SCXML document
let scxml = parse_scxml(xml).expect("Failed to parse SCXML");

// Validate the parsed structure
validate(&scxml).expect("SCXML validation failed");

// Serialize back to XML
let xml_output = to_xml(&scxml);
println!("{}", xml_output);

Supported SCXML Elements

• Core Constructs: <scxml>, <state>, <parallel>, <final>, <initial>, <history>
• Transitions: <transition> with support for events, conditions, targets, types, and executable content
• Data Model: <datamodel>, <data> with expressions, sources, and inline content
• Executable Content: <raise>, <if>, <foreach>, <send>, <script>, <assign>, <log>, <cancel>
• External Communications: <invoke>, <param>, <finalize>, <content>

Error Handling

Parsing and validation errors are handled via custom error types (ParseError and ValidationError) that provide detailed information about the issues encountered.

Limitations and Future Work

• Currently supports SCXML 1.0 only; future versions may add support for later drafts or extensions.
• Custom or unsupported executable elements are captured as Executable::Other for forward compatibility.
• No runtime interpretation of SCXML state machines; this crate focuses on parsing, validation, and serialization.

Structs

Content

Represents a <content> element.

Data

Represents a <data> element in the datamodel.

Final

Represents a <final> element, indicating an end state.

Finalize

Represents a <finalize> element within <invoke>.

History

Represents a <history> pseudo-state.

Initial

Represents an <initial> element within a compound state.

Invoke

Represents an <invoke> element for external processes.

Parallel

Represents a <parallel> element for concurrent substates.

Param

Represents a <param> element within <invoke>.

ParseOptions

Options for customizing SCXML parsing behavior.

Scxml

Represents the root <scxml> element, containing the overall state machine definition.

State

Represents a <state> element, which can contain substates and transitions.

Transition

Represents a <transition> element.

Enums

Executable

Enum representing executable content elements.

ParseError

Errors that can occur during SCXML parsing.

StateLike

Enum representing state-like elements: <state>, <parallel>, <final>, or <history>.

ValidationError

Errors that can occur during SCXML validation.

Functions

parse_scxml

Parses an SCXML document from a string using default options.

parse_scxml_with_options

Parses an SCXML document from a string with custom options.

to_xml

Serializes the SCXML structure back to an XML string.

validate

Validates the parsed SCXML structure for compliance with the specification.