pyfcstm.dsl.node

State Machine DSL Abstract Syntax Tree (AST) Nodes.

This module defines the Abstract Syntax Tree (AST) building blocks used by the State Machine Domain Specific Language (DSL). The classes provide a structured representation of DSL constructs such as states, transitions, expressions, and executable actions. Instances of these classes are typically produced by a parser and can be serialized back to DSL syntax via str().

The main public components include:

ASTNode - Root base class for all AST nodes.
Expr and Literal families - Expression nodes and literals.
StateDefinition - State declarations with nested structure.
TransitionDefinition and ForceTransitionDefinition - State transitions.
Import-related nodes such as ImportStatement, ImportDefMapping, and ImportEventMapping.
StateMachineDSLProgram - Root program container.
Statement and action blocks such as OperationAssignment, EnterStatement, ExitStatement, and DuringStatement.

Note

The AST classes are data-only and focus on structure. There is no evaluation or execution logic in this module.

Example:

>>> from pyfcstm.dsl.node import (
...     StateDefinition, TransitionDefinition, ChainID,
...     StateMachineDSLProgram, DefAssignment, Integer
... )
>>> def_var = DefAssignment("counter", "int", Integer("0"))
>>> trans = TransitionDefinition("idle", "active", ChainID(["idle", "start"]), None, [])
>>> root = StateDefinition("idle", transitions=[trans])
>>> program = StateMachineDSLProgram([def_var], root)
>>> print(program)
def int counter = 0;
state idle {
    idle -> active :: start;
}

all

pyfcstm.dsl.node.__all__ = ['ASTNode', 'Identifier', 'ChainID', 'Expr', 'Literal', 'Boolean', 'Integer', 'HexInt', 'Float', 'Constant', 'Name', 'Paren', 'UnaryOp', 'BinaryOp', 'ConditionalOp', 'UFunc', 'Statement', 'ConstantDefinition', 'InitialAssignment', 'DefAssignment', 'ImportMappingStatement', 'ImportDefSelector', 'ImportDefExactSelector', 'ImportDefSetSelector', 'ImportDefPatternSelector', 'ImportDefFallbackSelector', 'ImportDefTargetTemplate', 'ImportDefMapping', 'ImportEventMapping', 'ImportStatement', 'OperationalDeprecatedAssignment', 'Preamble', 'Operation', 'Condition', 'TransitionDefinition', 'ForceTransitionDefinition', 'StateDefinition', 'OperationalStatement', 'OperationAssignment', 'OperationIfBranch', 'OperationIf', 'EventDefinition', 'StateMachineDSLProgram', 'INIT_STATE', 'EXIT_STATE', 'ALL', 'EnterStatement', 'EnterOperations', 'EnterAbstractFunction', 'EnterRefFunction', 'ExitStatement', 'ExitOperations', 'ExitAbstractFunction', 'ExitRefFunction', 'DuringStatement', 'DuringOperations', 'DuringAbstractFunction', 'DuringRefFunction', 'DuringAspectStatement', 'DuringAspectOperations', 'DuringAspectAbstractFunction', 'DuringAspectRefFunction']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

INIT_STATE

pyfcstm.dsl.node.INIT_STATE = INIT_STATE

Special singleton marker representing the initial state in a state machine.

This is used to define transitions from the initial pseudo-state.

EXIT_STATE

pyfcstm.dsl.node.EXIT_STATE = EXIT_STATE

Special singleton marker representing the exit state in a state machine.

This is used to define transitions to the final pseudo-state.

ALL

pyfcstm.dsl.node.ALL = ALL

Special singleton marker representing all states in a state machine.

This is used to define transitions or actions that apply to all states.

ASTNode

class pyfcstm.dsl.node.ASTNode[source]

Abstract base class for all AST nodes in the state machine DSL.

This class provides a common ancestor for all nodes in the Abstract Syntax Tree, making it convenient to type-check and traverse mixed node collections.

Return type:: ASTNode

Identifier

class pyfcstm.dsl.node.Identifier[source]

Abstract base class for identifiers in the state machine DSL.

Identifiers are used to reference variables, states, and other named elements in the state machine definition.

Return type:: Identifier

ChainID

class pyfcstm.dsl.node.ChainID(path: List[str], is_absolute: bool = False)[source]

Represents a chained identifier (e.g., a.b.c) in the state machine DSL.

Parameters:

path (List[str]) – List of string components that make up the chained identifier
is_absolute (bool) – Whether the identifier is absolute (starts with /)

Return type:

ChainID

Example:

>>> chain_id = ChainID(['state1', 'event'])
>>> str(chain_id)
'state1.event'
>>> abs_id = ChainID(['root', 'event'], is_absolute=True)
>>> str(abs_id)
'/root.event'

__str__() → str[source]

Convert the ChainID to its string representation.

Returns:: String representation of the chained identifier
Return type:: str

Expr

class pyfcstm.dsl.node.Expr[source]

Abstract base class for expressions in the state machine DSL.

Expressions represent computations that produce values, which can be used in conditions, assignments, and other contexts within the state machine.

Return type:: Expr

Literal

class pyfcstm.dsl.node.Literal(raw: str)[source]

Base class for literal values in expressions.

Literal values are constants directly expressed in the code, such as numbers, booleans, or predefined constants.

Parameters:: raw (str) – The raw string representation of the literal
Return type:: Literal

__str__() → str[source]

Convert the literal to its string representation.

Returns:: String representation of the literal’s value
Return type:: str

property value: Any

Get the actual value of the literal.

Returns:: The evaluated value of the literal
Return type:: Any

Integer

class pyfcstm.dsl.node.Integer(raw: str)[source]

Represents an integer literal in the state machine DSL.

Parameters:: raw (str) – The raw string representation of the integer
Return type:: Integer

Example:

>>> int_val = Integer("42")
>>> int_val.value
42

HexInt

class pyfcstm.dsl.node.HexInt(raw: str)[source]

Represents a hexadecimal integer literal in the state machine DSL.

Parameters:: raw (str) – The raw string representation of the hexadecimal integer (e.g., "0xFF")
Return type:: HexInt

Example:

>>> hex_val = HexInt("0xFF")
>>> hex_val.value
255

__str__() → str[source]

Convert the hexadecimal integer to its string representation.

Returns:: Lowercase string representation of the hexadecimal value
Return type:: str

Float

class pyfcstm.dsl.node.Float(raw: str)[source]

Represents a floating-point literal in the state machine DSL.

Parameters:: raw (str) – The raw string representation of the float
Return type:: Float

Example:

>>> float_val = Float("3.14")
>>> float_val.value
3.14

__str__() → str[source]

Convert the float to its string representation.

Returns:: String representation of the float
Return type:: str

Boolean

class pyfcstm.dsl.node.Boolean(raw: str)[source]

Represents a boolean literal in the state machine DSL.

Parameters:: raw (str) – The raw string representation of the boolean ("true" or "false")
Return type:: Boolean

Example:

>>> bool_val = Boolean("true")
>>> bool_val.value
True

__post_init__() → None[source]: Normalize the raw value to lowercase after initialization.

Constant

class pyfcstm.dsl.node.Constant(raw: str)[source]

Represents a named mathematical constant in the state machine DSL.

Parameters:: raw (str) – The name of the constant (e.g., "pi", "E")
Return type:: Constant

Example:

>>> pi_const = Constant("pi")
>>> pi_const.value
3.141592653589793

__str__() → str[source]

Convert the constant to its string representation.

Returns:: The name of the constant
Return type:: str

Name

class pyfcstm.dsl.node.Name(name: str)[source]

Represents a named reference in the state machine DSL.

Names are used to reference variables, states, or other named elements.

Parameters:: name (str) – The identifier name
Return type:: Name

Example:

>>> var_name = Name("counter")
>>> str(var_name)
'counter'

__str__() → str[source]

Convert the name to its string representation.

Returns:: The name as a string
Return type:: str

Paren

class pyfcstm.dsl.node.Paren(expr: Expr)[source]

Represents a parenthesized expression in the state machine DSL.

Parentheses are used to control the order of operations in expressions.

Parameters:: expr (Expr) – The expression within the parentheses
Return type:: Paren

Example:

>>> inner_expr = BinaryOp(Name("a"), "+", Name("b"))
>>> paren_expr = Paren(inner_expr)
>>> str(paren_expr)
'(a + b)'

__str__() → str[source]

Convert the parenthesized expression to its string representation.

Returns:: The expression surrounded by parentheses
Return type:: str

UnaryOp

class pyfcstm.dsl.node.UnaryOp(op: str, expr: Expr)[source]

Represents a unary operation in the state machine DSL.

Unary operations apply a single operator to an expression.

Parameters:

op (str) – The unary operator (e.g., "!", "not", "-")
expr (Expr) – The expression to which the operator is applied

Return type:

UnaryOp

Example:

>>> not_expr = UnaryOp("not", Name("condition"))
>>> str(not_expr)
'!condition'

__post_init__() → None[source]: Replace any operator aliases with their canonical form.

__str__() → str[source]

Convert the unary operation to its string representation.

Returns:: String representation of the unary operation
Return type:: str

BinaryOp

class pyfcstm.dsl.node.BinaryOp(expr1: Expr, op: str, expr2: Expr)[source]

Represents a binary operation in the state machine DSL.

Binary operations apply an operator to two expressions.

Parameters:

expr1 (Expr) – The left-hand expression
op (str) – The binary operator (e.g., "+", "-", "and", "or")
expr2 (Expr) – The right-hand expression

Return type:

BinaryOp

Example:

>>> add_expr = BinaryOp(Name("a"), "+", Name("b"))
>>> str(add_expr)
'a + b'
>>> and_expr = BinaryOp(Name("x"), "and", Name("y"))
>>> str(and_expr)
'x && y'

__post_init__() → None[source]: Replace any operator aliases with their canonical form.

__str__() → str[source]

Convert the binary operation to its string representation.

Returns:: String representation of the binary operation
Return type:: str

ConditionalOp

class pyfcstm.dsl.node.ConditionalOp(cond: Expr, value_true: Expr, value_false: Expr)[source]

Represents a conditional (ternary) operation in the state machine DSL.

The conditional operation evaluates a condition and returns one of two expressions based on whether the condition is true or false.

Parameters:

cond (Expr) – The condition expression
value_true (Expr) – The expression to evaluate if the condition is true
value_false (Expr) – The expression to evaluate if the condition is false

Return type:

ConditionalOp

Example:

>>> cond_op = ConditionalOp(Name("x"), Integer("1"), Integer("0"))
>>> str(cond_op)
'(x) ? 1 : 0'

__str__() → str[source]

Convert the conditional operation to its string representation.

Returns:: String representation of the conditional operation
Return type:: str

UFunc

class pyfcstm.dsl.node.UFunc(func: str, expr: Expr)[source]

Represents a unary function call in the state machine DSL.

Unary functions apply a named function to a single expression.

Parameters:

func (str) – The function name
expr (Expr) – The expression to which the function is applied

Return type:

UFunc

Example:

>>> func_call = UFunc("abs", Name("x"))
>>> str(func_call)
'abs(x)'

__str__() → str[source]

Convert the function call to its string representation.

Returns:: String representation of the function call
Return type:: str

Statement

class pyfcstm.dsl.node.Statement[source]

Abstract base class for statements in the state machine DSL.

Statements represent actions or declarations in the state machine definition.

Return type:: Statement

OperationalStatement

class pyfcstm.dsl.node.OperationalStatement[source]

Abstract base class for statements inside operation blocks.

Operation statements are the executable statements that may appear inside effect { ... }, enter { ... }, during { ... }, and exit { ... } blocks.

Return type:: OperationalStatement

ConstantDefinition

class pyfcstm.dsl.node.ConstantDefinition(name: str, expr: Expr)[source]

Represents a constant definition statement in the state machine DSL.

Parameters:

name (str) – The name of the constant
expr (Expr) – The expression defining the constant’s value

Return type:

ConstantDefinition

Example:

>>> const_def = ConstantDefinition("MAX_COUNT", Integer("100"))
>>> str(const_def)
'MAX_COUNT = 100;'

__str__() → str[source]

Convert the constant definition to its string representation.

Returns:: String representation of the constant definition
Return type:: str

InitialAssignment

class pyfcstm.dsl.node.InitialAssignment(name: str, expr: Expr)[source]

Represents an initial assignment statement in the state machine DSL.

Initial assignments are used to set initial values for variables.

Parameters:

name (str) – The name of the variable
expr (Expr) – The expression defining the variable’s initial value

Return type:

InitialAssignment

Example:

>>> init_assign = InitialAssignment("counter", Integer("0"))
>>> str(init_assign)
'counter := 0;'

__str__() → str[source]

Convert the initial assignment to its string representation.

Returns:: String representation of the initial assignment
Return type:: str

DefAssignment

class pyfcstm.dsl.node.DefAssignment(name: str, type: str, expr: Expr, _span: Span | None = None)[source]

Represents a definition assignment statement in the state machine DSL.

Definition assignments are used to declare and initialize typed variables.

Parameters:

name (str) – The name of the variable
type (str) – The type of the variable
expr (Expr) – The expression defining the variable’s value

Return type:

DefAssignment

Example:

>>> def_assign = DefAssignment("counter", "int", Integer("0"))
>>> str(def_assign)
'def int counter = 0;'

__str__() → str[source]

Convert the definition assignment to its string representation.

Returns:: String representation of the definition assignment
Return type:: str

OperationalDeprecatedAssignment

class pyfcstm.dsl.node.OperationalDeprecatedAssignment(name: str, expr: Expr)[source]

Represents a deprecated form of operational assignment in the state machine DSL.

Parameters:

name (str) – The name of the variable
expr (Expr) – The expression defining the variable’s value

Return type:

OperationalDeprecatedAssignment

Example:

>>> op_assign = OperationalDeprecatedAssignment(
...     "counter", BinaryOp(Name("counter"), "+", Integer("1"))
... )
>>> str(op_assign)
'counter := counter + 1;'

__str__() → str[source]

Convert the operational deprecated assignment to its string representation.

Returns:: String representation of the operational deprecated assignment
Return type:: str

Condition

class pyfcstm.dsl.node.Condition(expr: Expr)[source]

Represents a condition in the state machine DSL.

Conditions are used in transitions and other contexts to determine when actions should occur.

Parameters:: expr (Expr) – The expression defining the condition
Return type:: Condition

Example:

>>> cond = Condition(BinaryOp(Name("counter"), ">=", Integer("10")))
>>> str(cond)
'counter >= 10'

__str__() → str[source]

Convert the condition to its string representation.

Returns:: String representation of the condition
Return type:: str

Preamble

class pyfcstm.dsl.node.Preamble(stats: List[ConstantDefinition | InitialAssignment])[source]

Represents a preamble section in the state machine DSL.

The preamble contains constant definitions and initial assignments that set up the state machine’s environment.

Parameters:: stats (List[Union[ConstantDefinition, InitialAssignment]]) – List of statements in the preamble
Return type:: Preamble

Example:

>>> const_def = ConstantDefinition("MAX", Integer("100"))
>>> init_assign = InitialAssignment("counter", Integer("0"))
>>> preamble = Preamble([const_def, init_assign])
>>> print(str(preamble))
MAX = 100;
counter := 0;

__str__() → str[source]

Convert the preamble to its string representation.

Returns:: String representation of the preamble
Return type:: str

Operation

class pyfcstm.dsl.node.Operation(stats: List[OperationalDeprecatedAssignment])[source]

Represents an operation block in the state machine DSL.

Operations are sequences of assignments that modify the state machine’s variables.

Parameters:: stats (List[OperationalDeprecatedAssignment]) – List of operational assignments
Return type:: Operation

Example:

>>> op1 = OperationalDeprecatedAssignment(
...     "counter", BinaryOp(Name("counter"), "+", Integer("1"))
... )
>>> op2 = OperationalDeprecatedAssignment("flag", Boolean("true"))
>>> operation = Operation([op1, op2])
>>> print(str(operation))
counter := counter + 1;
flag := true;

__str__() → str[source]

Convert the operation to its string representation.

Returns:: String representation of the operation
Return type:: str

ImportMappingStatement

class pyfcstm.dsl.node.ImportMappingStatement[source]

Abstract base class for mapping statements inside an import block.

Import mapping statements configure how imported variables and events should be exposed or remapped when the imported module is assembled into the host state tree.

Return type:: ImportMappingStatement

ImportDefSelector

class pyfcstm.dsl.node.ImportDefSelector[source]

Abstract base class for def mapping source selectors in import blocks.

Source selectors determine which imported variable names a def mapping rule applies to.

Return type:: ImportDefSelector

ImportDefExactSelector

class pyfcstm.dsl.node.ImportDefExactSelector(name: str)[source]

Represents an exact source variable selector in an import def mapping.

Parameters:: name (str) – Exact variable name to match
Return type:: ImportDefExactSelector

__str__() → str[source]

Convert the selector to its DSL representation.

Returns:: String representation of the selector
Return type:: str

ImportDefSetSelector

class pyfcstm.dsl.node.ImportDefSetSelector(names: List[str])[source]

Represents a set-based source selector in an import def mapping.

Parameters:: names (List[str]) – Exact variable names listed in the selector set
Return type:: ImportDefSetSelector

__str__() → str[source]

Convert the selector to its DSL representation.

Returns:: String representation of the selector
Return type:: str

ImportDefPatternSelector

class pyfcstm.dsl.node.ImportDefPatternSelector(pattern: str)[source]

Represents a wildcard-based source selector in an import def mapping.

The selector is intentionally preserved as raw DSL text rather than being decomposed into finer-grained AST nodes. This keeps the DSL layer permissive enough for patterns whose literal segments would not fit the plain ID token constraints, such as suffixes that start with digits.

Parameters:: pattern (str) – Raw selector pattern text
Return type:: ImportDefPatternSelector

__str__() → str[source]

Convert the selector to its DSL representation.

Returns:: String representation of the selector
Return type:: str

ImportDefFallbackSelector

class pyfcstm.dsl.node.ImportDefFallbackSelector[source]

Represents the fallback * selector in an import def mapping.

Return type:: ImportDefFallbackSelector

__str__() → str[source]

Convert the selector to its DSL representation.

Returns:: Wildcard text
Return type:: str

ImportDefTargetTemplate

class pyfcstm.dsl.node.ImportDefTargetTemplate(template: str)[source]

Represents the right-hand target template of an import def mapping.

The template is stored as raw DSL text at the AST layer. Placeholder and wildcard semantics are validated and interpreted in later assembly phases.

Parameters:: template (str) – Raw template text
Return type:: ImportDefTargetTemplate

__str__() → str[source]

Convert the template to its DSL representation.

Returns:: String representation of the target template
Return type:: str

ImportDefMapping

class pyfcstm.dsl.node.ImportDefMapping(selector: ImportDefSelector, target_template: ImportDefTargetTemplate)[source]

Represents a variable mapping rule inside an import block.

Parameters:

selector (ImportDefSelector) – Source selector of the mapping rule
target_template (ImportDefTargetTemplate) – Target template of the mapping rule

Return type:

ImportDefMapping

__str__() → str[source]

Convert the mapping rule to its DSL representation.

Returns:: String representation of the mapping rule
Return type:: str

ImportEventMapping

class pyfcstm.dsl.node.ImportEventMapping(source_event: ChainID, target_event: ChainID, extra_name: str | None = None)[source]

Represents an event mapping rule inside an import block.

Parameters:

source_event (ChainID) – Source event path inside the imported module
target_event (ChainID) – Target event path in the host state tree
extra_name (Optional[str]) – Optional display-name override for the target event

Return type:

ImportEventMapping

__str__() → str[source]

Convert the event mapping to its DSL representation.

Returns:: String representation of the event mapping
Return type:: str

ImportStatement

class pyfcstm.dsl.node.ImportStatement(source_path: str, alias: str, extra_name: str | None = None, mappings: List[ImportMappingStatement] | None = None)[source]

Represents a single import statement inside a composite state.

Parameters:

source_path (str) – Import source path string from the DSL
alias (str) – Local alias name of the imported root state
extra_name (Optional[str]) – Optional display-name override for the imported state
mappings (List[ImportMappingStatement]) – Mapping rules declared inside the import block

Return type:

ImportStatement

__post_init__() → None[source]: Initialize default empty lists for optional parameters.

__str__() → str[source]

Convert the import statement to its DSL representation.

Returns:: String representation of the import statement
Return type:: str

TransitionDefinition

class pyfcstm.dsl.node.TransitionDefinition(from_state: str | _StateSingletonMark, to_state: str | _StateSingletonMark, event_id: ChainID | None, condition_expr: Expr | None, post_operations: List[OperationalStatement], _span: Span | None = None)[source]

Represents a transition definition in the state machine DSL.

Transitions define how the state machine moves from one state to another in response to events and conditions.

Parameters:

from_state (Union[str, _StateSingletonMark]) – The source state name or INIT_STATE singleton
to_state (Union[str, _StateSingletonMark]) – The target state name or EXIT_STATE singleton
event_id (Optional[ChainID]) – Optional event identifier that triggers the transition
condition_expr (Optional[Expr]) – Optional condition expression that must be true for the transition
post_operations (List[OperationalStatement]) – List of operation statements to perform after the transition

Return type:

TransitionDefinition

Example:

>>> init_trans = TransitionDefinition(INIT_STATE, "idle", None, None, [])
>>> event_trans = TransitionDefinition(
...     "idle", "active", ChainID(["idle", "start"]), None, []
... )
>>> op = OperationAssignment("counter", Integer("0"))
>>> cond_trans = TransitionDefinition(
...     "active", "idle", None,
...     BinaryOp(Name("counter"), ">", Integer("10")),
...     [op],
... )

__str__() → str[source]

Convert the transition definition to its string representation.

Returns:: String representation of the transition definition
Return type:: str

ForceTransitionDefinition

Represents a forced transition definition in the state machine DSL.

Forced transitions override normal transitions and are used for special cases like error handling or interrupts.

Parameters:

from_state (Union[str, _StateSingletonMark]) – The source state name or ALL singleton
to_state (Union[str, _StateSingletonMark]) – The target state name or EXIT_STATE singleton
event_id (Optional[ChainID]) – Optional event identifier that triggers the transition
condition_expr (Optional[Expr]) – Optional condition expression that must be true for the transition

Return type:

ForceTransitionDefinition

Example:

>>> force_trans = ForceTransitionDefinition(ALL, "error", None, None)
>>> str(force_trans)
'! * -> error;'

__str__() → str[source]

Convert the force transition definition to its string representation.

Returns:: String representation of the force transition definition
Return type:: str

StateDefinition

class pyfcstm.dsl.node.StateDefinition(name: str, extra_name: str | None = None, events: List[EventDefinition] | None = None, imports: List[ImportStatement] | None = None, substates: List[StateDefinition] | None = None, transitions: List[TransitionDefinition] | None = None, enters: List[EnterStatement] | None = None, durings: List[DuringStatement] | None = None, exits: List[ExitStatement] | None = None, during_aspects: List[DuringAspectStatement] | None = None, force_transitions: List[ForceTransitionDefinition] | None = None, is_pseudo: bool = False, _span: Span | None = None)[source]

Represents a state definition in the state machine DSL.

States are the fundamental building blocks of state machines, containing transitions, substates, and actions to be performed on entry, during, and exit.

Parameters:

name (str) – The name of the state
extra_name (Optional[str]) – Optional additional name for the state
events (List[EventDefinition]) – List of events defined within this state
imports (List[ImportStatement]) – List of import statements declared within this state
substates (List[StateDefinition]) – List of nested state definitions
transitions (List[TransitionDefinition]) – List of transitions from this state
enters (List[EnterStatement]) – List of actions to perform when entering the state
durings (List[DuringStatement]) – List of actions to perform while in the state
exits (List[ExitStatement]) – List of actions to perform when exiting the state
during_aspects (List[DuringAspectStatement]) – List of aspect-specific actions to perform while in the state
force_transitions (List[ForceTransitionDefinition]) – List of forced transitions from this state
is_pseudo (bool) – Whether this is a pseudo state

Return type:

StateDefinition

Example:

>>> simple_state = StateDefinition("idle")
>>> str(simple_state)
'state idle;'

>>> trans = TransitionDefinition(
...     "idle", "active", ChainID(["idle", "start"]), None, []
... )
>>> state_with_trans = StateDefinition("idle", transitions=[trans])

__post_init__() → None[source]: Initialize default empty lists for optional parameters.

__str__() → str[source]

Convert the state definition to its string representation.

Returns:: String representation of the state definition
Return type:: str

OperationAssignment

class pyfcstm.dsl.node.OperationAssignment(name: str, expr: Expr)[source]

Represents an operation assignment in the state machine DSL.

Operation assignments are used to modify variables during transitions or state actions.

Parameters:

name (str) – The name of the variable
expr (Expr) – The expression defining the new value

Return type:

OperationAssignment

Example:

>>> op_assign = OperationAssignment(
...     "counter", BinaryOp(Name("counter"), "+", Integer("1"))
... )
>>> str(op_assign)
'counter = counter + 1;'

__str__() → str[source]

Convert the operation assignment to its string representation.

Returns:: String representation of the operation assignment
Return type:: str

OperationIfBranch

class pyfcstm.dsl.node.OperationIfBranch(condition: Expr | None, statements: List[OperationalStatement])[source]

Represents a single branch inside an operation-block if statement.

Parameters:

condition (Optional[Expr]) – Branch condition, or None for the final else branch.
statements (List[OperationalStatement]) – Statements executed when the branch is selected.

Return type:

OperationIfBranch

OperationIf

class pyfcstm.dsl.node.OperationIf(branches: List[OperationIfBranch])[source]

Represents an if / else if / else statement inside an operation block.

Parameters:: branches (List[OperationIfBranch]) – Ordered branch list. The last branch may have condition=None to represent else.
Return type:: OperationIf

__str__() → str[source]

Convert the operation if statement to its DSL representation.

Returns:: String representation of the operation if statement.
Return type:: str

EventDefinition

class pyfcstm.dsl.node.EventDefinition(name: str, extra_name: str | None = None)[source]

Represents an event definition in the state machine DSL.

Events are signals that can trigger transitions or other actions within the state machine.

Parameters:

name (str) – The name of the event
extra_name (Optional[str]) – Optional additional name for the event

Return type:

EventDefinition

Example:

>>> event = EventDefinition("start")
>>> str(event)
'event start;'
>>> named_event = EventDefinition("start", "Start Event")
>>> str(named_event)
'event start named "Start Event";'

__str__() → str[source]

Convert the event definition to its string representation.

Returns:: String representation of the event definition
Return type:: str

StateMachineDSLProgram

class pyfcstm.dsl.node.StateMachineDSLProgram(definitions: List[DefAssignment], root_state: StateDefinition)[source]

Represents a complete state machine DSL program.

A program consists of variable definitions and a root state that contains the entire state machine hierarchy.

Parameters:

definitions (List[DefAssignment]) – List of variable definitions
root_state (StateDefinition) – The root state of the state machine

Return type:

StateMachineDSLProgram

Example:

>>> def_var = DefAssignment("counter", "int", Integer("0"))
>>> root = StateDefinition("root")
>>> program = StateMachineDSLProgram([def_var], root)
>>> print(str(program))
def int counter = 0;
state root;

__str__() → str[source]

Convert the state machine program to its string representation.

Returns:: String representation of the state machine program
Return type:: str

EnterStatement

class pyfcstm.dsl.node.EnterStatement[source]

Abstract base class for enter statements in the state machine DSL.

Enter statements define actions to be performed when entering a state.

Return type:: EnterStatement

EnterOperations

class pyfcstm.dsl.node.EnterOperations(operations: List[OperationalStatement], name: str | None = None)[source]

Represents a block of operations to perform when entering a state.

Parameters:

operations (List[OperationalStatement]) – List of operation statements
name (Optional[str]) – Optional name for the operation block

Return type:

EnterOperations

Example:

>>> op = OperationAssignment("counter", Integer("0"))
>>> enter_ops = EnterOperations([op])
>>> print(str(enter_ops))
enter {
    counter = 0;
}

__str__() → str[source]

Convert the enter operations to their string representation.

Returns:: String representation of the enter operations
Return type:: str

EnterAbstractFunction

class pyfcstm.dsl.node.EnterAbstractFunction(name: str | None, doc: str | None)[source]

Represents an abstract function to call when entering a state.

Abstract functions are placeholders for implementation-specific behavior.

Parameters:

name (Optional[str]) – Optional name of the function
doc (Optional[str]) – Optional documentation for the function

Return type:

EnterAbstractFunction

Example:

>>> enter_func = EnterAbstractFunction("initState", "Initialize the state")
>>> print(str(enter_func))
enter abstract initState /*
    Initialize the state
*/

__str__() → str[source]

Convert the enter abstract function to its string representation.

Returns:: String representation of the enter abstract function
Return type:: str

EnterRefFunction

class pyfcstm.dsl.node.EnterRefFunction(name: str | None, ref: ChainID)[source]

Represents a reference function to call when entering a state.

Reference functions point to existing functions defined elsewhere.

Parameters:

name (Optional[str]) – Optional name of the function
ref (ChainID) – Chain identifier referencing the function

Return type:

EnterRefFunction

Example:

>>> ref_func = EnterRefFunction("init", ChainID(["common", "initialize"]))
>>> str(ref_func)
'enter init ref common.initialize;'

__str__() → str[source]

Convert the enter reference function to its string representation.

Returns:: String representation of the enter reference function
Return type:: str

ExitStatement

class pyfcstm.dsl.node.ExitStatement[source]

Abstract base class for exit statements in the state machine DSL.

Exit statements define actions to be performed when exiting a state.

Return type:: ExitStatement

ExitOperations

class pyfcstm.dsl.node.ExitOperations(operations: List[OperationalStatement], name: str | None = None)[source]

Represents a block of operations to perform when exiting a state.

Parameters:

operations (List[OperationalStatement]) – List of operation statements
name (Optional[str]) – Optional name for the operation block

Return type:

ExitOperations

Example:

>>> op = OperationAssignment("active", Boolean("false"))
>>> exit_ops = ExitOperations([op])
>>> print(str(exit_ops))
exit {
    active = false;
}

__str__() → str[source]

Convert the exit operations to their string representation.

Returns:: String representation of the exit operations
Return type:: str

ExitAbstractFunction

class pyfcstm.dsl.node.ExitAbstractFunction(name: str | None, doc: str | None)[source]

Represents an abstract function to call when exiting a state.

Abstract functions are placeholders for implementation-specific behavior.

Parameters:

name (Optional[str]) – Optional name of the function
doc (Optional[str]) – Optional documentation for the function

Return type:

ExitAbstractFunction

Example:

>>> exit_func = ExitAbstractFunction("cleanupState", "Clean up resources")
>>> print(str(exit_func))
exit abstract cleanupState /*
    Clean up resources
*/

__str__() → str[source]

Convert the exit abstract function to its string representation.

Returns:: String representation of the exit abstract function
Return type:: str

ExitRefFunction

class pyfcstm.dsl.node.ExitRefFunction(name: str | None, ref: ChainID)[source]

Represents a reference function to call when exiting a state.

Reference functions point to existing functions defined elsewhere.

Parameters:

name (Optional[str]) – Optional name of the function
ref (ChainID) – Chain identifier referencing the function

Return type:

ExitRefFunction

Example:

>>> ref_func = ExitRefFunction("cleanup", ChainID(["common", "cleanup"]))
>>> str(ref_func)
'exit cleanup ref common.cleanup;'

__str__() → str[source]

Convert the exit reference function to its string representation.

Returns:: String representation of the exit reference function
Return type:: str

DuringStatement

class pyfcstm.dsl.node.DuringStatement[source]

Abstract base class for during statements in the state machine DSL.

During statements define actions to be performed while in a state.

Return type:: DuringStatement

DuringOperations

class pyfcstm.dsl.node.DuringOperations(aspect: str | None, operations: List[OperationalStatement], name: str | None = None)[source]

Represents a block of operations to perform while in a state.

Parameters:

aspect (Optional[str]) – Optional aspect name (e.g., "entry", "do", "exit")
operations (List[OperationalStatement]) – List of operation statements
name (Optional[str]) – Optional name for the operation block

Return type:

DuringOperations

Example:

>>> op = OperationAssignment("counter", BinaryOp(Name("counter"), "+", Integer("1")))
>>> during_ops = DuringOperations("do", [op])
>>> print(str(during_ops))
during do {
    counter = counter + 1;
}

__str__() → str[source]

Convert the during operations to their string representation.

Returns:: String representation of the during operations
Return type:: str

DuringAbstractFunction

class pyfcstm.dsl.node.DuringAbstractFunction(name: str | None, aspect: str | None, doc: str | None)[source]

Represents an abstract function to call while in a state.

Abstract functions are placeholders for implementation-specific behavior.

Parameters:

name (Optional[str]) – Optional name of the function
aspect (Optional[str]) – Optional aspect name (e.g., "entry", "do", "exit")
doc (Optional[str]) – Optional documentation for the function

Return type:

DuringAbstractFunction

Example:

>>> during_func = DuringAbstractFunction("processData", "do", "Process incoming data")
>>> print(str(during_func))
during do abstract processData /*
    Process incoming data
*/

__str__() → str[source]

Convert the during abstract function to its string representation.

Returns:: String representation of the during abstract function
Return type:: str

DuringRefFunction

class pyfcstm.dsl.node.DuringRefFunction(name: str | None, aspect: str | None, ref: ChainID)[source]

Represents a reference function to call while in a state.

Reference functions point to existing functions defined elsewhere.

Parameters:

name (Optional[str]) – Optional name of the function
aspect (Optional[str]) – Optional aspect name (e.g., "entry", "do", "exit")
ref (ChainID) – Chain identifier referencing the function

Return type:

DuringRefFunction

Example:

>>> ref_func = DuringRefFunction("process", "do", ChainID(["common", "process"]))
>>> str(ref_func)
'during do process ref common.process;'

__str__() → str[source]

Convert the during reference function to its string representation.

Returns:: String representation of the during reference function
Return type:: str

DuringAspectStatement

class pyfcstm.dsl.node.DuringAspectStatement[source]

Abstract base class for during aspect statements in the state machine DSL.

During aspect statements define aspect-specific actions to be performed while in a state.

Return type:: DuringAspectStatement

DuringAspectOperations

class pyfcstm.dsl.node.DuringAspectOperations(aspect: str, operations: List[OperationalStatement], name: str | None = None)[source]

Represents a block of aspect-specific operations to perform while in a state.

Parameters:

aspect (str) – The aspect name (e.g., "before", "after")
operations (List[OperationalStatement]) – List of operation statements
name (Optional[str]) – Optional name for the operation block

Return type:

DuringAspectOperations

Example:

>>> op = OperationAssignment("counter", BinaryOp(Name("counter"), "+", Integer("1")))
>>> during_ops = DuringAspectOperations("before", [op])
>>> print(str(during_ops))
>> during before {
    counter = counter + 1;
}

__str__() → str[source]

Convert the during aspect operations to their string representation.

Returns:: String representation of the during aspect operations
Return type:: str

DuringAspectAbstractFunction

class pyfcstm.dsl.node.DuringAspectAbstractFunction(name: str | None, aspect: str, doc: str | None)[source]

Represents an abstract function to call for a specific aspect while in a state.

Abstract functions are placeholders for implementation-specific behavior.

Parameters:

name (Optional[str]) – Optional name of the function
aspect (str) – The aspect name (e.g., "before", "after")
doc (Optional[str]) – Optional documentation for the function

Return type:

DuringAspectAbstractFunction

Example:

>>> during_func = DuringAspectAbstractFunction(
...     "processData", "before", "Process incoming data"
... )
>>> print(str(during_func))
>> during before abstract processData /*
    Process incoming data
*/

__str__() → str[source]

Convert the during aspect abstract function to its string representation.

Returns:: String representation of the during aspect abstract function
Return type:: str

DuringAspectRefFunction

class pyfcstm.dsl.node.DuringAspectRefFunction(name: str | None, aspect: str, ref: ChainID)[source]

Represents a reference function to call for a specific aspect while in a state.

Reference functions point to existing functions defined elsewhere.

Parameters:

name (Optional[str]) – Optional name of the function
aspect (str) – The aspect name (e.g., "before", "after")
ref (ChainID) – Chain identifier referencing the function

Return type:

DuringAspectRefFunction

Example:

>>> ref_func = DuringAspectRefFunction(
...     "process", "before", ChainID(["common", "process"])
... )
>>> str(ref_func)
'>> during before process ref common.process;'

__str__() → str[source]

Convert the during aspect reference function to its string representation.

Returns:: String representation of the during aspect reference function
Return type:: str

pyfcstm.dsl.node

__all__

INIT_STATE

EXIT_STATE

ALL

ASTNode

Identifier

ChainID

Expr

Literal

Integer

HexInt

Float

Boolean

Constant

Name

Paren

UnaryOp

BinaryOp

ConditionalOp

UFunc

Statement

OperationalStatement

ConstantDefinition

InitialAssignment

DefAssignment

OperationalDeprecatedAssignment

Condition

Preamble

Operation

ImportMappingStatement

ImportDefSelector

ImportDefExactSelector

ImportDefSetSelector

ImportDefPatternSelector

ImportDefFallbackSelector

ImportDefTargetTemplate

ImportDefMapping

ImportEventMapping

ImportStatement

TransitionDefinition

ForceTransitionDefinition

StateDefinition

OperationAssignment

OperationIfBranch

OperationIf

EventDefinition

StateMachineDSLProgram

EnterStatement

EnterOperations

EnterAbstractFunction

EnterRefFunction

ExitStatement

ExitOperations

ExitAbstractFunction

ExitRefFunction

DuringStatement

DuringOperations

DuringAbstractFunction

DuringRefFunction

DuringAspectStatement

DuringAspectOperations

DuringAspectAbstractFunction

DuringAspectRefFunction

all