pyfcstm.dsl.node
State Machine DSL AST Module
This module defines the Abstract Syntax Tree (AST) classes for a State Machine Domain Specific Language. It provides a comprehensive set of classes to represent various elements of state machines including:
States and transitions
Expressions and operations
Conditions and assignments
Event handling with enter, during, and exit actions
The AST classes enable parsing, manipulation, and generation of state machine definitions in a structured way, supporting both simple and hierarchical state machines.
ASTNode
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
- Return type:
Example:
>>> chain_id = ChainID(['state1', 'event']) >>> str(chain_id) 'state1.event'
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:
- __str__()[source]
Convert the literal to its string representation.
- Returns:
String representation of the literal’s value
- Return type:
str
- property value
Get the actual value of the literal.
- Returns:
The evaluated value of the literal
- Return type:
Any
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:
Example:
>>> bool_val = Boolean("true") >>> bool_val.value True
- __str__()
Convert the literal to its string representation.
- Returns:
String representation of the literal’s value
- Return type:
str
- property value
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:
Example:
>>> int_val = Integer("42") >>> int_val.value 42
- property value
Get the actual value of the literal.
- Returns:
The evaluated value of the literal
- Return type:
Any
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:
Example:
>>> hex_val = HexInt("0xFF") >>> hex_val.value 255
- __str__()[source]
Convert the hexadecimal integer to its string representation.
- Returns:
Lowercase string representation of the hexadecimal value
- Return type:
str
- property value
Get the actual value of the literal.
- Returns:
The evaluated value of the literal
- Return type:
Any
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:
Example:
>>> float_val = Float("3.14") >>> float_val.value 3.14
- __str__()[source]
Convert the float to its string representation.
- Returns:
String representation of the float
- Return type:
str
- property value
Get the actual value of the literal.
- Returns:
The evaluated value of the literal
- Return type:
Any
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:
Example:
>>> pi_const = Constant("pi") >>> pi_const.value 3.141592653589793
- __str__()[source]
Convert the constant to its string representation.
- Returns:
The name of the constant
- Return type:
str
- property value
Get the actual value of the literal.
- Returns:
The evaluated value of the literal
- Return type:
Any
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:
Example:
>>> var_name = Name("counter") >>> str(var_name) 'counter'
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.
Example:
>>> inner_expr = BinaryOp(Name("a"), "+", Name("b")) >>> paren_expr = Paren(inner_expr) >>> str(paren_expr) '(a + b)'
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:
Example:
>>> not_expr = UnaryOp("not", Name("condition")) >>> str(not_expr) '!condition'
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:
- Return type:
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'
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:
- Return type:
Example:
>>> cond_op = ConditionalOp(Name("x"), Integer("1"), Integer("0")) >>> str(cond_op) '(x) ? 1 : 0'
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:
Example:
>>> func_call = UFunc("abs", Name("x")) >>> str(func_call) 'abs(x)'
Statement
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:
Example:
>>> const_def = ConstantDefinition("MAX_COUNT", Integer("100")) >>> str(const_def) 'MAX_COUNT = 100;'
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:
Example:
>>> init_assign = InitialAssignment("counter", Integer("0")) >>> str(init_assign) 'counter := 0;'
DefAssignment
- class pyfcstm.dsl.node.DefAssignment(name: str, type: str, expr: Expr)[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:
Example:
>>> def_assign = DefAssignment("counter", "int", Integer("0")) >>> str(def_assign) 'def int counter = 0;'
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:
Example:
>>> op_assign = OperationalDeprecatedAssignment("counter", BinaryOp(Name("counter"), "+", Integer("1"))) >>> str(op_assign) 'counter := counter + 1;'
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:
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;
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:
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;
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.
Example:
>>> cond = Condition(BinaryOp(Name("counter"), ">=", Integer("10"))) >>> str(cond) 'counter >= 10'
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[OperationAssignment])[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[OperationAssignment]) – List of operations to perform after the transition
- Return type:
Example:
>>> # Transition from initial state to "idle" state >>> init_trans = TransitionDefinition(INIT_STATE, "idle", None, None, []) >>> # Transition from "idle" to "active" on "start" event >>> event_trans = TransitionDefinition("idle", "active", ChainID(["idle", "start"]), None, []) >>> # Transition with condition and operations >>> op = OperationAssignment("counter", Integer("0")) >>> cond_trans = TransitionDefinition("active", "idle", None, BinaryOp(Name("counter"), ">", Integer("10")), [op])
ForceTransitionDefinition
- class pyfcstm.dsl.node.ForceTransitionDefinition(from_state: str | _StateSingletonMark, to_state: str | _StateSingletonMark, event_id: ChainID | None, condition_expr: Expr | None)[source]
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:
Example:
>>> # Force transition from any state to "error" state >>> force_trans = ForceTransitionDefinition(ALL, "error", None, None) >>> str(force_trans) '! * -> error;'
StateDefinition
- class pyfcstm.dsl.node.StateDefinition(name: str, 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)[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
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
- Return type:
Example:
>>> # Simple state with no internal elements >>> simple_state = StateDefinition("idle", [], [], [], [], []) >>> str(simple_state) 'state idle;' >>> # State with transitions >>> trans = TransitionDefinition("idle", "active", ChainID(["idle", "start"]), None, []) >>> state_with_trans = StateDefinition("idle", [], [trans], [], [], [])
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:
Example:
>>> op_assign = OperationAssignment("counter", BinaryOp(Name("counter"), "+", Integer("1"))) >>> str(op_assign) 'counter = counter + 1;'
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:
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;
EnterStatement
EnterOperations
- class pyfcstm.dsl.node.EnterOperations(operations: List[OperationAssignment], name: str | None = None)[source]
Represents a block of operations to perform when entering a state.
- Parameters:
operations (List[OperationAssignment]) – List of operation assignments
- Return type:
Example:
>>> op = OperationAssignment("counter", Integer("0")) >>> enter_ops = EnterOperations([op]) >>> print(str(enter_ops)) enter { counter = 0; }
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:
Example:
>>> enter_func = EnterAbstractFunction("initState", "Initialize the state") >>> print(str(enter_func)) enter abstract initState /* Initialize the state */
ExitStatement
ExitOperations
- class pyfcstm.dsl.node.ExitOperations(operations: List[OperationAssignment], name: str | None = None)[source]
Represents a block of operations to perform when exiting a state.
- Parameters:
operations (List[OperationAssignment]) – List of operation assignments
- Return type:
Example:
>>> op = OperationAssignment("active", Boolean("false")) >>> exit_ops = ExitOperations([op]) >>> print(str(exit_ops)) exit { active = false; }
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:
Example:
>>> exit_func = ExitAbstractFunction("cleanupState", "Clean up resources") >>> print(str(exit_func)) exit abstract cleanupState /* Clean up resources */
DuringStatement
DuringOperations
- class pyfcstm.dsl.node.DuringOperations(aspect: str | None, operations: List[OperationAssignment], 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[OperationAssignment]) – List of operation assignments
- Return type:
Example:
>>> op = OperationAssignment("counter", BinaryOp(Name("counter"), "+", Integer("1"))) >>> during_ops = DuringOperations("do", [op]) >>> print(str(during_ops)) during do { counter = counter + 1; }
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:
Example:
>>> during_func = DuringAbstractFunction("processData", "do", "Process incoming data") >>> print(str(during_func)) during do abstract processData /* Process incoming data */
DuringAspectStatement
DuringAspectOperations
- class pyfcstm.dsl.node.DuringAspectOperations(aspect: str, operations: List[OperationAssignment], 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., “entry”, “do”, “exit”)
operations (List[OperationAssignment]) – List of operation assignments
name (Optional[str]) – Optional name for the operation block
- Return type:
Example:
>>> op = OperationAssignment("counter", BinaryOp(Name("counter"), "+", Integer("1"))) >>> during_ops = DuringAspectOperations("before", [op]) >>> print(str(during_ops)) >> during before { counter = counter + 1; }
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:
Example:
>>> during_func = DuringAspectAbstractFunction("processData", "before", "Process incoming data") >>> print(str(during_func)) >> during before abstract processData /* Process incoming data */
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.