Skip to content
This repository was archived by the owner on Sep 12, 2025. It is now read-only.

Adds assign element support #15

Merged
johnnyt merged 2 commits into from
Aug 25, 2025
Merged

Adds assign element support #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
22f1a17
Adds assign element support
johnnyt Aug 25, 2025
0866882
Updates documentation for assign element support
johnnyt Aug 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
139 changes: 139 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,145 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Added

#### Phase 1 Enhanced Expression Evaluation

- **Predicator v3.0 Integration**: Upgraded from v2.0 to v3.0 with enhanced capabilities
- **Enhanced Nested Property Access**: Deep dot notation support (`user.profile.settings.theme`)
- **Mixed Access Patterns**: Combined bracket/dot notation (`users['john'].active`)
- **Context Location Resolution**: New `context_location/2` function for assignment path validation
- **Value Evaluation**: Non-boolean expression evaluation for actual data values
- **Type-Safe Operations**: Improved type coercion and error handling
- **Graceful Fallback**: Returns `:undefined` for missing properties instead of errors

- **`SC.ValueEvaluator` Module**: Comprehensive value evaluation system for SCXML expressions
- **Expression Compilation**: `compile_expression/1` for reusable expression compilation
- **Value Evaluation**: `evaluate_value/2` extracts actual values (not just boolean results)
- **Location Path Resolution**: `resolve_location/1,2` validates assignment paths using predicator v3.0
- **Safe Assignment**: `assign_value/3` performs type-safe nested data model updates
- **Integrated Assignment**: `evaluate_and_assign/3` combines evaluation and assignment
- **SCXML Context Support**: Full integration with state machine context (events, configuration, datamodel)
- **Error Handling**: Comprehensive error handling with detailed logging

- **`<assign>` Element Support**: Full W3C SCXML assign element implementation
- **`SC.Actions.AssignAction` Struct**: Represents assign actions with location and expr attributes
- **Location-Based Assignment**: Validates assignment paths before execution
- **Expression Evaluation**: Uses SC.ValueEvaluator for complex expression processing
- **Nested Property Assignment**: Supports deep assignment (`user.profile.name = "John"`)
- **Mixed Notation Support**: Handles both dot and bracket notation in assignments
- **Context Integration**: Access to current event data and state configuration
- **Error Recovery**: Graceful error handling with logging, continues execution on failures
- **Action Integration**: Seamlessly integrates with existing action execution framework

#### StateChart Data Model Enhancement

- **Data Model Storage**: Added `data_model` field to `SC.StateChart` for variable persistence
- **Current Event Context**: Added `current_event` field for expression evaluation context
- **Helper Methods**: `update_data_model/2` and `set_current_event/2` for state management
- **SCXML Context Building**: Enhanced context building for comprehensive expression evaluation

#### Parser Extensions

- **Assign Element Parsing**: Extended SCXML parser to handle `<assign>` elements
- **Element Builder**: `build_assign_action/4` creates AssignAction structs with location tracking
- **Handler Integration**: Added assign element start/end handlers
- **StateStack Integration**: `handle_assign_end/1` properly collects assign actions
- **Mixed Action Support**: Parse assign actions alongside log/raise actions in onentry/onexit
- **Location Tracking**: Complete source location tracking for debugging

#### Feature Detection Updates

- **Assign Elements Support**: Updated `assign_elements` feature status to `:supported`
- **Feature Registry**: Enhanced feature detection for new capabilities
- **Test Infrastructure**: Tests now recognize assign element capability

### Changed

#### Dependency Updates

- **predicator**: Upgraded from `~> 2.0` to `~> 3.0` (major version upgrade)
- **Breaking Change**: Enhanced property access semantics
- **Migration**: Context keys with dots now require nested structure (e.g., `%{"user" => %{"email" => "..."}}` instead of `%{"user.email" => "..."}`)
- **Benefit**: More powerful and flexible data access patterns

### Technical Improvements

- **Test Coverage**: Maintained 92.9% overall code coverage with comprehensive new tests
- **New Test Modules**: SC.ValueEvaluatorTest, SC.Actions.AssignActionTest, SC.Parser.AssignParsingTest
- **556 Total Tests**: All tests pass including new assign functionality
- **Log Capture**: Added `@moduletag capture_log: true` for clean test output
- **Performance**: O(1) lookups maintained with new data model operations
- **Error Handling**: Enhanced error handling and logging throughout assign operations
- **Code Quality**: Maintained Credo compliance with proper alias ordering

### Examples

#### Basic Assign Usage

```xml
<?xml version="1.0" encoding="UTF-8"?>
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" initial="start">
<state id="start">
<onentry>
<assign location="userName" expr="'John Doe'"/>
<assign location="counter" expr="42"/>
<assign location="user.profile.name" expr="'Jane Smith'"/>
</onentry>
<transition target="working"/>
</state>
<state id="working">
<onentry>
<assign location="counter" expr="counter + 1"/>
<assign location="status" expr="'processing'"/>
</onentry>
</state>
</scxml>
```

#### Mixed Notation Assignment

```xml
<onentry>
<assign location="users['admin'].active" expr="true"/>
<assign location="settings.theme" expr="'dark'"/>
<assign location="counters[0]" expr="counters[0] + 1"/>
</onentry>
```

#### Event Data Assignment

```xml
<state id="processing">
<onentry>
<assign location="lastEvent" expr="_event.name"/>
<assign location="eventData" expr="_event.data.value"/>
</onentry>
</state>
```

#### Programmatic Usage

```elixir
# Value evaluation
{:ok, compiled} = SC.ValueEvaluator.compile_expression("user.profile.name")
{:ok, "John Doe"} = SC.ValueEvaluator.evaluate_value(compiled, context)

# Location validation
{:ok, ["user", "settings", "theme"]} = SC.ValueEvaluator.resolve_location("user.settings.theme")

# Combined evaluation and assignment
{:ok, updated_model} = SC.ValueEvaluator.evaluate_and_assign("result", "count * 2", context)
```

### Notes

- **Phase 1 Complete**: Enhanced Expression Evaluation phase is fully implemented
- **Foundation for Phase 2**: Data model and expression evaluation infrastructure ready
- **Backward Compatible**: All existing functionality preserved
- **Production Ready**: Comprehensive test coverage and error handling
- **SCION Progress**: `assign_elements` feature now supported (awaiting Phase 2 for full datamodel tests)

## [1.0.0] - 2025-08-23

### Added
Expand Down
71 changes: 64 additions & 7 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,14 +115,17 @@ Also use this initial Elixir implementation as reference: <https://github.com/ca
- **Optimal Transition Set**: SCXML-compliant transition conflict resolution where child state transitions take priority over ancestors
- **Compound state support**: Automatically enters initial child states recursively
- **Parallel state support**: Proper concurrent execution with cross-boundary exit semantics and parallel region preservation
- **Conditional transitions**: Full `cond` attribute support with Predicator v2.0 expression evaluation and SCXML `In()` function
- **Conditional transitions**: Full `cond` attribute support with Predicator v3.0 expression evaluation and SCXML `In()` function
- **Assign action support**: Complete `<assign>` element execution with data model integration
- **Cycle Detection**: Prevents infinite loops in eventless transitions with configurable iteration limits (100 iterations default)
- **O(1 lookups**: Uses `Document.find_state/2` and `Document.get_transitions_from_state/2`
- Separates `active_states()` (leaf only) from `active_ancestors()` (includes parents)
- Provides `{:ok, result}` or `{:error, reason}` responses
- **`SC.StateChart`** - Runtime container for SCXML state machines
- Combines document, configuration, and event queues
- Combines document, configuration, event queues, and data model
- Maintains internal and external event queues per SCXML specification
- **Data model storage**: Persistent variable storage with `data_model` field
- **Current event context**: Tracks current event for expression evaluation
- **`SC.Configuration`** - Active state configuration management
- Stores only leaf states for efficient memory usage
- Computes ancestor states dynamically via `active_ancestors/2` using O(1) document lookups
Expand All @@ -132,6 +135,39 @@ Also use this initial Elixir implementation as reference: <https://github.com/ca
- Supports event data and origin tracking
- Used for state machine event processing

### Expression Evaluation and Data Model

- **`SC.ValueEvaluator`** - Comprehensive value evaluation system for SCXML expressions
- **Expression compilation**: `compile_expression/1` for reusable predicator compilation
- **Value evaluation**: `evaluate_value/2` extracts actual values (not just boolean results)
- **Location path resolution**: `resolve_location/1,2` validates assignment paths using predicator v3.0's `context_location`
- **Safe assignment operations**: `assign_value/3` performs type-safe nested data model updates
- **Integrated assignment**: `evaluate_and_assign/3` combines evaluation and assignment
- **SCXML context support**: Full integration with state machine context (events, configuration, datamodel)
- **Nested property access**: Support for deep property access (`user.profile.settings.theme`)
- **Mixed access patterns**: Combined bracket/dot notation (`users['john'].active`)
- **Error handling**: Comprehensive error handling with detailed logging
- **`SC.ConditionEvaluator`** - Enhanced with predicator v3.0 integration
- **Predicator v3.0**: Upgraded from v2.0 with enhanced nested property access capabilities
- **SCXML functions**: Maintains `In()` function and SCXML-specific context building
- **Type-safe operations**: Improved type coercion and graceful fallback for missing properties

### Actions and Executable Content

- **`SC.Actions.AssignAction`** - SCXML `<assign>` element implementation
- **Location-based assignment**: Validates assignment paths using SC.ValueEvaluator
- **Expression evaluation**: Uses SC.ValueEvaluator for complex expression processing
- **Nested property assignment**: Supports deep assignment (`user.profile.name = "John"`)
- **Mixed notation support**: Handles both dot and bracket notation in assignments
- **Context integration**: Access to current event data and state configuration
- **Error recovery**: Graceful error handling with logging, continues execution on failures
- **`SC.Actions.LogAction`** - SCXML `<log>` element implementation for debugging
- **`SC.Actions.RaiseAction`** - SCXML `<raise>` element implementation for internal events
- **`SC.Actions.ActionExecutor`** - Centralized action execution system
- **Phase tracking**: Executes actions during appropriate state entry/exit phases
- **Mixed action support**: Handles log, raise, assign, and future action types
- **StateChart integration**: Actions can modify state chart data model and event queues

### Architecture Flow

The implementation follows a clean **Parse → Validate → Optimize** architecture:
Expand Down Expand Up @@ -178,7 +214,7 @@ All parsed SCXML elements include precise source location information for valida

## Dependencies

- **`predicator`** (~> 2.0) - Safe condition (boolean predicate) evaluator
- **`predicator`** (~> 3.0) - Safe condition and value evaluator with enhanced nested property access
- **`saxy`** (~> 1.6) - Fast, memory-efficient SAX XML parser with position tracking support

## Development Dependencies
Expand Down Expand Up @@ -219,6 +255,21 @@ This project includes comprehensive test coverage:
- Tests both single-line and multiline XML element definitions
- Ensures proper location tracking for nested elements and datamodel elements

### Expression Evaluation Tests

- **`test/sc/value_evaluator_test.exs`** - Comprehensive tests for SC.ValueEvaluator module
- Value evaluation, location resolution, assignment operations
- Nested property access and mixed notation support
- SCXML context integration and error handling
- **`test/sc/actions/assign_action_test.exs`** - Complete assign action functionality
- Action creation, execution, and error handling
- Data model integration and context evaluation
- Mixed action execution and state chart modification
- **`test/sc/parser/assign_parsing_test.exs`** - SCXML assign element parsing
- Assign element parsing in onentry/onexit contexts
- Mixed action parsing (log, raise, assign together)
- Complex expression and location parsing

## Code Style

- All generated files have no trailing whitespace
Expand Down Expand Up @@ -257,7 +308,10 @@ XML content within triple quotes uses 4-space base indentation.
- ✅ **Parallel states** with concurrent execution and proper exit semantics
- ✅ **SCXML-compliant processing** - Proper microstep/macrostep execution model with exit set computation and LCCA algorithms
- ✅ **Eventless transitions** - Automatic transitions without event attributes (also called NULL transitions in SCXML spec)
- ✅ **Conditional transitions** - Full `cond` attribute support with Predicator v2.0 expression evaluation and SCXML `In()` function
- ✅ **Conditional transitions** - Full `cond` attribute support with Predicator v3.0 expression evaluation and SCXML `In()` function
- ✅ **Assign elements** - Complete `<assign>` element support with location-based assignment and nested property access
- ✅ **Value evaluation** - Non-boolean expression evaluation using Predicator v3.0 for actual data values
- ✅ **Data model support** - StateChart data model integration with dynamic variable assignment
- ✅ **Optimal Transition Set** - SCXML-compliant transition conflict resolution where child state transitions take priority over ancestors
- ✅ Hierarchical states with O(1) optimized lookups
- ✅ Event-driven state changes
Expand All @@ -271,7 +325,7 @@ XML content within triple quotes uses 4-space base indentation.
- **Document parsing failures**: Complex SCXML with history states, executable content
- **Validation too strict**: Rejecting valid but complex SCXML documents
- **Missing SCXML features**: Targetless transitions, internal transitions
- **Missing executable content**: `<script>`, `<assign>`, `<send>`, `<raise>`, `<onentry>`, `<onexit>`
- **Missing executable content**: `<script>`, `<send>` (assign, raise, onentry, onexit now supported)
- **Missing datamodel features**: Enhanced expression evaluation, additional functions

## Implementation Status
Expand All @@ -286,12 +340,15 @@ XML content within triple quotes uses 4-space base indentation.
- **Parallel state support** with concurrent execution and proper cross-boundary exit semantics
- **SCXML-compliant processing model** with proper microstep/macrostep execution, exit set computation, and LCCA algorithms
- **Eventless transitions** - Automatic transitions without event attributes (also called NULL transitions in SCXML spec)
- **Conditional transitions** - Full `cond` attribute support with Predicator v2.0 expression evaluation and SCXML `In()` function
- **Conditional transitions** - Full `cond` attribute support with Predicator v3.0 expression evaluation and SCXML `In()` function
- **Assign elements** - Complete `<assign>` element support with SC.ValueEvaluator and location-based assignment
- **Value evaluation system** - SC.ValueEvaluator module for non-boolean expression evaluation and data model operations
- **Enhanced expression evaluation** - Predicator v3.0 integration with nested property access and mixed notation support
- **Optimal Transition Set** - SCXML-compliant transition conflict resolution where child state transitions take priority over ancestors
- **Exit Set Computation** - W3C SCXML exit set calculation algorithm for proper state exit semantics
- **LCCA Algorithm** - Full Least Common Compound Ancestor computation for accurate transition conflict resolution
- **O(1 performance optimizations** via state and transition lookup maps
- Comprehensive test suite integration (SCION + W3C) - 444 tests, 63 regression tests, 92.3% coverage
- Comprehensive test suite integration (SCION + W3C) - 556 tests, 85 regression tests, 92.9% coverage
- Test infrastructure with SC.Case module using interpreter
- **Pattern matching in tests** instead of multiple individual assertions
- XML parsing with namespace support and precise source location tracking
Expand Down
Loading