api_reference.md

FSMConfig API Reference

Table of Contents

• Types
• ConfigParser
• CallbackRegistry
• VariableManager
• EventDispatcher
• StateMachine
• State
• StateObserver

Types

VariableType

Enum defining the types of variables that can be stored.

enum class VariableType {
    INT,      ///< Integer type
    FLOAT,    ///< Floating point type
    STRING,   ///< String type
    BOOL      ///< Boolean type
};

VariableValue

Structure for storing values with support for multiple types. Implements the Rule of Five with proper move semantics.

struct VariableValue {
    VariableType type;
    union {
        int int_value;
        float float_value;
        std::string string_value;
        bool bool_value;
    };
    
    VariableValue();
    VariableValue(int v);
    VariableValue(float v);
    VariableValue(const std::string& v);
    VariableValue(bool v);
    ~VariableValue();
    
    VariableValue(const VariableValue& other);
    VariableValue& operator=(const VariableValue& other);
    
    VariableValue(VariableValue&& other) noexcept;
    VariableValue& operator=(VariableValue&& other) noexcept;
    
    int asInt() const;
    float asFloat() const;
    std::string asString() const;
    bool asBool() const;
    std::string toString() const;
};

Special Member Functions

Move Constructor

VariableValue(VariableValue&& other) noexcept;

Moves the internal value from other. After the move, other is left in a valid but unspecified state. For STRING type, performs a non-throwing move of the std::string.

Move Assignment Operator

VariableValue& operator=(VariableValue&& other) noexcept;

Moves the internal value from other. After the move, other is left in a valid but unspecified state. Properly handles self-assignment and cleans up existing resources before moving.

TransitionEvent

Structure representing a transition between states.

struct TransitionEvent {
    std::string event_name;
    std::string from_state;
    std::string to_state;
    std::map<std::string, VariableValue> data;
    std::chrono::system_clock::time_point timestamp;
    
    TransitionEvent();
};

StateInfo

Structure containing information about a state.

struct StateInfo {
    std::string name;
    std::map<std::string, VariableValue> variables;
    std::string on_enter_callback;
    std::string on_exit_callback;
    std::vector<std::string> actions;
    
    StateInfo();
    explicit StateInfo(const std::string& name);
};

TransitionInfo

Structure containing information about a transition.

struct TransitionInfo {
    std::string from_state;
    std::string to_state;
    std::string event_name;
    std::string guard_callback;
    std::string transition_callback;
    std::vector<std::string> actions;
    
    TransitionInfo();
};

ConfigParser

Constructor

ConfigParser();

Methods

loadFromFile

void loadFromFile(const std::string& file_path);

Load configuration from a YAML file.

Parameters:

• file_path - Path to the YAML configuration file

Throws:

• ConfigException if the file cannot be loaded or parsed

loadFromString

void loadFromString(const std::string& yaml_content);

Load configuration from a YAML string.

Parameters:

• yaml_content - YAML configuration as a string

Throws:

• ConfigException if the content cannot be parsed

getGlobalVariables

const std::map<std::string, VariableValue>& getGlobalVariables() const;

Get all global variables.

Returns: Reference to the map of global variables

getStates

const std::map<std::string, StateInfo>& getStates() const;

Get all state definitions.

Returns: Reference to the map of state definitions

getTransitions

const std::vector<TransitionInfo>& getTransitions() const;

Get all transition definitions.

Returns: Reference to the vector of transition definitions

hasState

bool hasState(const std::string& state_name) const;

Check if a state exists.

Parameters:

• state_name - Name of the state to check

Returns: true if the state exists, false otherwise

getState

const StateInfo& getState(const std::string& state_name) const;

Get information about a specific state.

Parameters:

• state_name - Name of the state

Returns: Reference to the state information

Throws:

• ConfigException if the state does not exist

getTransitionsFrom

std::vector<TransitionInfo> getTransitionsFrom(const std::string& state_name) const;

Get all transitions from a specific state.

Parameters:

• state_name - Name of the source state

Returns: Vector of transitions from the specified state

findTransition

const TransitionInfo* findTransition(const std::string& from_state, const std::string& event_name) const;

Find a transition by event name.

Parameters:

• from_state - Name of the source state
• event_name - Name of the event

Returns: Pointer to the transition, or nullptr if not found

clear

void clear();

Clear all loaded configuration.

CallbackRegistry

Constructor

CallbackRegistry();

Methods

registerStateCallback

void registerStateCallback(
    const std::string& state_name,
    const std::string& callback_type,
    StateCallback callback
);

Register a state callback.

Parameters:

• state_name - Name of the state
• callback_type - Type of callback ("on_enter" or "on_exit")
• callback - Callback function

registerTransitionCallback

void registerTransitionCallback(
    const std::string& from_state,
    const std::string& to_state,
    TransitionCallback callback
);

Register a transition callback.

Parameters:

• from_state - Name of the source state
• to_state - Name of the target state
• callback - Callback function

registerGuard

void registerGuard(
    const std::string& from_state,
    const std::string& to_state,
    const std::string& event_name,
    GuardCallback callback
);

Register a guard callback.

Parameters:

• from_state - Name of the source state
• to_state - Name of the target state
• event_name - Name of the event
• callback - Guard callback function

registerAction

void registerAction(
    const std::string& action_name,
    ActionCallback callback
);

Register an action callback.

Parameters:

• action_name - Name of the action
• callback - Action callback function

callStateCallback

void callStateCallback(
    const std::string& state_name,
    const std::string& callback_type
) const;

Call a state callback.

Parameters:

• state_name - Name of the state
• callback_type - Type of callback ("on_enter" or "on_exit")

callTransitionCallback

void callTransitionCallback(
    const std::string& from_state,
    const std::string& to_state,
    const TransitionEvent& event
) const;

Call a transition callback.

Parameters:

• from_state - Name of the source state
• to_state - Name of the target state
• event - Transition event data

callGuard

bool callGuard(
    const std::string& from_state,
    const std::string& to_state,
    const std::string& event_name
) const;

Call a guard callback.

Parameters:

• from_state - Name of the source state
• to_state - Name of the target state
• event_name - Name of the event

Returns: true if guard allows transition, false otherwise (or if guard not found)

callAction

void callAction(const std::string& action_name) const;

Call an action callback.

Parameters:

• action_name - Name of the action

hasStateCallback

bool hasStateCallback(
    const std::string& state_name,
    const std::string& callback_type
) const;

Check if a state callback exists.

Parameters:

• state_name - Name of the state
• callback_type - Type of callback

Returns: true if callback exists, false otherwise

hasTransitionCallback

bool hasTransitionCallback(
    const std::string& from_state,
    const std::string& to_state
) const;

Check if a transition callback exists.

Parameters:

• from_state - Name of the source state
• to_state - Name of the target state

Returns: true if callback exists, false otherwise

hasGuard

bool hasGuard(
    const std::string& from_state,
    const std::string& to_state,
    const std::string& event_name
) const;

Check if a guard callback exists.

Parameters:

• from_state - Name of the source state
• to_state - Name of the target state
• event_name - Name of the event

Returns: true if guard exists, false otherwise

hasAction

bool hasAction(const std::string& action_name) const;

Check if an action callback exists.

Parameters:

• action_name - Name of the action

Returns: true if action exists, false otherwise

clear

void clear();

Clear all registered callbacks.

VariableManager

Constructor

VariableManager();

Methods

setGlobalVariable

void setGlobalVariable(const std::string& name, const VariableValue& value);

Set a global variable.

Parameters:

• name - Variable name
• value - Variable value

setStateVariable

void setStateVariable(
    const std::string& state_name,
    const std::string& name,
    const VariableValue& value
);

Set a state-local variable.

Parameters:

• state_name - Name of the state
• name - Variable name
• value - Variable value

getVariable

std::optional<VariableValue> getVariable(
    const std::string& state_name,
    const std::string& name
) const;

Get a variable (checks state-local first, then global).

Parameters:

• state_name - Name of the state
• name - Variable name

Returns: Optional variable value

getGlobalVariable

std::optional<VariableValue> getGlobalVariable(const std::string& name) const;

Get a global variable.

Parameters:

• name - Variable name

Returns: Optional variable value

getStateVariable

std::optional<VariableValue> getStateVariable(
    const std::string& state_name,
    const std::string& name
) const;

Get a state-local variable.

Parameters:

• state_name - Name of the state
• name - Variable name

Returns: Optional variable value

hasVariable

bool hasVariable(
    const std::string& state_name,
    const std::string& name
) const;

Check if a variable exists (checks state-local first, then global).

Parameters:

• state_name - Name of the state
• name - Variable name

Returns: true if variable exists, false otherwise

hasGlobalVariable

bool hasGlobalVariable(const std::string& name) const;

Check if a global variable exists.

Parameters:

• name - Variable name

Returns: true if variable exists, false otherwise

hasStateVariable

bool hasStateVariable(
    const std::string& state_name,
    const std::string& name
) const;

Check if a state-local variable exists.

Parameters:

• state_name - Name of the state
• name - Variable name

Returns: true if variable exists, false otherwise

removeVariable

bool removeVariable(
    const std::string& state_name,
    const std::string& name
);

Remove a variable (checks state-local first, then global).

Parameters:

• state_name - Name of the state
• name - Variable name

Returns: true if variable was removed, false if not found

removeGlobalVariable

bool removeGlobalVariable(const std::string& name);

Remove a global variable.

Parameters:

• name - Variable name

Returns: true if variable was removed, false if not found

removeStateVariable

bool removeStateVariable(
    const std::string& state_name,
    const std::string& name
);

Remove a state-local variable.

Parameters:

• state_name - Name of the state
• name - Variable name

Returns: true if variable was removed, false if not found

getGlobalVariables

std::map<std::string, VariableValue> getGlobalVariables() const;

Get all global variables.

Returns: Copy of the global variables map

Note: Returns a copy to ensure thread safety. The returned map is a snapshot of the variables at the time of the call and will not reflect subsequent changes.

getStateVariables

std::map<std::string, VariableValue> getStateVariables(
    const std::string& state_name
) const;

Get all state-local variables for a state.

Parameters:

• state_name - Name of the state

Returns: Copy of the state-local variables map

Note: Returns a copy to ensure thread safety. The returned map is a snapshot of the variables at the time of the call and will not reflect subsequent changes.

clear

void clear();

Clear all variables.

clearStateVariables

void clearStateVariables(const std::string& state_name);

Clear all state-local variables for a state.

Parameters:

• state_name - Name of the state

clearGlobalVariables

void clearGlobalVariables();

Clear all global variables.

copyStateVariables

void copyStateVariables(
    const std::string& from_state,
    const std::string& to_state
);

Copy variables from one state to another.

Parameters:

• from_state - Source state name
• to_state - Target state name

EventDispatcher

Constructor

EventDispatcher();

Methods

dispatchEvent

void dispatchEvent(
    const std::string& event_name,
    const TransitionEvent& event
);

Dispatch an event for processing.

Parameters:

• event_name - Name of the event
• event - Transition event data

processEvents

void processEvents();

Process all events in the queue (synchronously).

processOneEvent

bool processOneEvent();

Process one event from the queue.

Returns: true if an event was processed, false if queue was empty

getEventQueueSize

size_t getEventQueueSize() const;

Get the number of events in the queue.

Returns: Number of events in the queue

clearEventQueue

void clearEventQueue();

Clear the event queue.

hasPendingEvents

bool hasPendingEvents() const;

Check if there are pending events in the queue.

Returns: true if there are pending events, false otherwise

setEventHandler

void setEventHandler(EventHandler handler);

Set the event handler function.

Parameters:

• handler - Event handler function

hasEventHandler

bool hasEventHandler() const;

Check if an event handler is set.

Returns: true if handler is set, false otherwise

start

void start();

Start the dispatcher (for future async support).

stop

void stop();

Stop the dispatcher.

isRunning

bool isRunning() const;

Check if the dispatcher is running.

Returns: true if running, false otherwise

waitForEmptyQueue

void waitForEmptyQueue() const;

Wait for the event queue to become empty.

StateMachine

Constructors

explicit StateMachine(const std::string& config_path);
explicit StateMachine(const std::string& yaml_content, bool is_content);

Create a state machine from a YAML configuration file or string.

Parameters:

• config_path - Path to the YAML configuration file
• yaml_content - YAML configuration as a string
• is_content - Set to true if yaml_content is YAML content

Throws:

• ConfigException if the configuration cannot be loaded or parsed

Destructor

~StateMachine();

Methods

start

void start();

Start the state machine (transition to initial state).

Throws:

• StateException if the machine is already started or if initial state not found

stop

void stop();

Stop the state machine.

reset

void reset();

Reset the state machine to initial state.

getCurrentState

std::string getCurrentState() const;

Get the current state name.

Returns: Current state name

hasState

bool hasState(const std::string& state_name) const;

Check if a state exists.

Parameters:

• state_name - Name of the state to check

Returns: true if the state exists, false otherwise

getAllStates

std::vector<std::string> getAllStates() const;

Get all state names.

Returns: Vector of all state names

triggerEvent

void triggerEvent(const std::string& event_name);
void triggerEvent(const std::string& event_name, const std::map<std::string, VariableValue>& data);

Trigger an event.

Parameters:

• event_name - Name of the event
• data - Optional event data

Throws:

• StateException if the machine is not started or if transition is not valid

registerStateCallback

template<typename T>
void registerStateCallback(
    const std::string& state_name,
    const std::string& callback_type,
    void (T::*callback)(),
    T* instance
);

Register a state callback.

Parameters:

• state_name - Name of the state
• callback_type - Type of callback ("on_enter" or "on_exit")
• callback - Member function pointer
• instance - Pointer to the object instance

registerTransitionCallback

template<typename T>
void registerTransitionCallback(
    const std::string& from_state,
    const std::string& to_state,
    void (T::*callback)(const TransitionEvent&),
    T* instance
);

Register a transition callback.

Parameters:

• from_state - Name of the source state
• to_state - Name of the target state
• callback - Member function pointer
• instance - Pointer to the object instance

registerGuard

template<typename T>
void registerGuard(
    const std::string& from_state,
    const std::string& to_state,
    const std::string& event_name,
    bool (T::*callback)(),
    T* instance
);

Register a guard callback.

Parameters:

• from_state - Name of the source state
• to_state - Name of the target state
• event_name - Name of the event
• callback - Member function pointer
• instance - Pointer to the object instance

registerAction

template<typename T>
void registerAction(
    const std::string& action_name,
    void (T::*callback)(),
    T* instance
);

Register an action callback.

Parameters:

• action_name - Name of the action
• callback - Member function pointer
• instance - Pointer to the object instance

setVariable

void setVariable(const std::string& name, const VariableValue& value);

Set a variable (global or state-local).

Parameters:

• name - Variable name
• value - Variable value

getVariable

VariableValue getVariable(const std::string& name) const;

Get a variable (checks state-local first, then global).

Parameters:

• name - Variable name

Returns: Variable value

Throws:

• StateException if the variable is not found

hasVariable

bool hasVariable(const std::string& name) const;

Check if a variable exists (checks state-local first, then global).

Parameters:

• name - Variable name

Returns: true if variable exists, false otherwise

registerStateObserver

void registerStateObserver(const std::shared_ptr<StateObserver>& observer);

Register a state observer.

Parameters:

• observer - Shared pointer to the observer

Note: The observer is stored as a std::weak_ptr internally to prevent dangling pointers. If the observer is destroyed, it will be automatically removed from the notification list on the next notification cycle. This ensures safe lifetime management and prevents memory leaks.

Example:

auto observer = std::make_shared<MyObserver>();
fsm.registerStateObserver(observer);
// No manual cleanup needed - automatic when observer goes out of scope

unregisterStateObserver

void unregisterStateObserver(const std::shared_ptr<StateObserver>& observer);

Unregister a state observer.

Parameters:

• observer - Shared pointer to the observer

Note: Removes the observer from the notification list.

setErrorHandler

void setErrorHandler(ErrorHandler handler);

Set the error handler function.

Parameters:

• handler - Error handler function

State

Constructor

explicit State(const StateInfo& info);

Create a state from state information.

Parameters:

• info - State information

Methods

getName

const std::string& getName() const;

Get the state name.

Returns: Reference to the state name

getVariables

const std::map<std::string, VariableValue>& getVariables() const;

Get the state variables.

Returns: Reference to the state variables map

getOnEnterCallback

const std::string& getOnEnterCallback() const;

Get the on_enter callback name.

Returns: Reference to the callback name

getOnExitCallback

const std::string& getOnExitCallback() const;

Get the on_exit callback name.

Returns: Reference to the callback name

getActions

const std::vector<std::string>& getActions() const;

Get the state actions.

Returns: Reference to the actions vector

hasVariable

bool hasVariable(const std::string& name) const;

Check if a variable exists in the state.

Parameters:

• name - Variable name

Returns: true if variable exists, false otherwise

getVariable

VariableValue getVariable(const std::string& name) const;

Get a variable from the state.

Parameters:

• name - Variable name

Returns: Variable value

Throws:

• StateException if the variable is not found

setVariable

void setVariable(const std::string& name, const VariableValue& value);

Set a variable in the state.

Parameters:

• name - Variable name
• value - Variable value

getAllVariables

const std::map<std::string, VariableValue>& getAllVariables() const;

Get all variables in the state.

Returns: Reference to the variables map

StateObserver

Virtual Methods

virtual void onStateEnter(const std::string& state_name) = 0;
virtual void onStateExit(const std::string& state_name) = 0;
virtual void onTransition(const TransitionEvent& event) = 0;
virtual void onError(const std::string& error_message) = 0;

Observer methods that must be implemented by derived classes.

Parameters:

• state_name - Name of the state
• event - Transition event data
• error_message - Error message

Type Definitions

StateCallback

using StateCallback = std::function<void()>;

Type for state callbacks (on_enter, on_exit).

TransitionCallback

using TransitionCallback = std::function<void(const TransitionEvent&)>;

Type for transition callbacks.

GuardCallback

using GuardCallback = std::function<bool()>;

Type for guard callbacks.

ActionCallback

using ActionCallback = std::function<void()>;

Type for action callbacks.

EventHandler

using EventHandler = std::function<void(const std::string& event_name, const TransitionEvent& event)>;

Type for event handlers.

ErrorHandler

using ErrorHandler = std::function<void(const std::string&)>;

Type for error handlers.

Exceptions

ConfigException

class ConfigException : public std::runtime_error {
public:
    explicit ConfigException(const std::string& message);
};

Exception thrown for configuration errors.

StateException

class StateException : public std::runtime_error {
public:
    explicit StateException(const std::string& message);
};

Exception thrown for state machine errors.