API Reference
=============

`#include <tinyfsm.hpp>`


Class Diagram
-------------
                                           .......
    +--------------------------------------:  T  :
    | tinyfsm::FsmList                     :.....:
    +-----------------------------------------|
    | [+] set_initial_state()     <<static>>  |
    | [+] reset()                 <<static>>  |
    | [+] enter()                 <<static>>  |
    | [+] start()                 <<static>>  |
    | [+] dispatch(Event)         <<static>>  |
    +-----------------------------------------+


                                           .......
    +--------------------------------------:  T  :
    | tinyfsm::Fsm                         :.....:
    +-----------------------------------------|
    | [+] state<S>()              <<static>>  |
    | [+] set_initial_state()     <<static>>  |
    | [+] reset()                 <<static>>  |
    | [+] enter()                 <<static>>  |
    | [+] start()                 <<static>>  |
    | [+] dispatch(Event)         <<static>>  |
    | [#] transit<S>()                        |
    | [#] transit<S>(Action)                  |
    | [#] transit<S>(Action, Condition)       |
    +-----------------------------------------+
                         #
                         |
                         |
              +---------------------+
              | MyFSM               |
              +---------------------+
              | [+] entry()         |
              | [+] exit()          |
              | [+] react(EventX)   |
              | [+] react(EventY)   |
              | ...                 |
              +---------------------+
                         #
                         |
           +-------------+-------------+
           |             |             |
      +---------+   +---------+   +---------+
      | State_A |   | State_B |   | ...     |
      +---------+   +---------+   +---------+


    [#]  protected
    [+]  public
    [-]  private


template< typename F > class Fsm
--------------------------------

### State Machine Functions

 * `template< typename S > static constexpr S & state(void)`

   Returns a reference to a (implicitly instantiated) state S. Allows
   low-level access to all states;


 * `static void set_initial_state(void)`

   Function prototype, must be defined (explicit template
   specialization) for every state machine class (e.g. by using the
   `FSM_INITIAL_STATE(fsm, state`) macro). Sets current state to
   initial (start) state.


 * `static void reset(void)`

   Empty function, can be overridden by state machine class in order to
   perform custom initialization (e.g. set static state machine
   variables, or reset states using `StateList<MyStates...>::reset()`)
   or directly via the `state<MyState>()` instance).

   Note that this function is NOT called on start().

   See example: `/examples/api/resetting_switch.cpp`

 * `static void enter(void)`

   Helper function, usually not needed to be used directly:
   calls entry() function of current state.


 * `static void start()`

   Sets the initial (start) state and calls its entry() function.


 * `template< typename E > static void dispatch(E const &)`

   Dispatch an event to the current state of this state machine.


### State Transition Functions

 * `template< typename S > void transit(void)`

   Transit to a new state:

   1. Call exit() function on current state
   2. Set new current state to S
   3. Call entry() function on new state


 * `template< typename S, typename ActionFunction > void transit(ActionFunction)`

   Transit to a new state, with action function:

   1. Call exit() function on current state
   2. Call ActionFunction
   3. Set new current state to S
   4. Call entry() function on new state


 * `template< typename S, typename ActionFunction, typename ConditionFunction > void transit(ActionFunction, ConditionFunction)`

   Transit to a new state only if ConditionFunction returns true.
   Shortcut for: `if(ConditionFunction()) transit<S>(ActionFunction);`.


### Derived Classes

#### template< typename F > class MooreMachine

Moore state machines have entry actions, but no exit actions:

 * `virtual void entry(void) { }`

   Entry action, not enforcing. Can be enforced by declaring pure
   virtual: `virtual void entry(void) = 0`

 * `void exit(void) { }`

   No exit actions.

See example: `/examples/api/more_machine.cpp`

#### template< typename F > class MealyMachine

Mealy state machines do not have entry/exit actions:

 * `void entry(void) { }`

   No entry actions.

 * `void exit(void) { }`

   No exit actions.

*Input actions* are modeled in react(), conditional dependent of event
type or payload and using `transit<>(ActionFunction)`.

See example: `/examples/api/mealy_machine.cpp`


template< typename... FF > struct FsmList
-----------------------------------------

 * `static void set_initial_state(void)`

   Calls set_initial_state() on all state machines in the list.


 * `static void reset()`

   Calls reset() on all state machines in the list.


 * `static void enter()`

   Calls enter() on all state machines in the list.


 * `static void start()`

   Sets the initial (start) state for all state machines in list, then
   call all entry() functions.


 * `template< typename E > static void dispatch(E const &)`

   Dispatch an event to the current state of all the state machines in
   the list.


template< typename... SS > struct StateList
-------------------------------------------

 * `static void reset(void)`

   Re-instantiate all states in the list, using copy-constructor.

   See example: `/examples/api/resetting_switch.cpp`