varch/doc/fsm.en.md

### Introduction
The `fsm` is related to a general-purpose finite state machine module. It defines data structures related to state transitions and provides key function interfaces such as state machine initialization and execution, helping developers easily build and use finite state machines in C language projects to handle business scenarios with different states and state transition logics.

### Interfaces

#### Functions
```c
int fsm_init(FSM* fsm, StateTransform* trans, int count, int state);
int fsm_execute(FSM* fsm, int event);
```

**`fsm_init` Function**:
This function is used to initialize a finite state machine. It takes the following parameters:
- `FSM* fsm`: A pointer to the `FSM` structure that represents the state machine itself. The `FSM` structure usually holds information about the current state, the state transition table, etc.
- `StateTransform* trans`: A pointer to an array of `StateTransform` structures. This array defines the possible state transitions for the state machine. Each `StateTransform` element typically contains details such as the source state, the destination state, the triggering event, and an associated action (which is `NULL` in the provided example).
- `int count`: The number of elements in the `StateTransform` array, indicating how many possible state transitions are defined for this state machine.
- `int state`: The initial state in which the state machine should start.

**`fsm_execute` Function**:
This function is responsible for executing the state machine based on a given event. When called with an `int event` parameter, it checks the current state of the state machine and searches through the defined state transition table (`StateTransform` array) to see if the provided event triggers a state transition. If a valid transition is found based on the current state and the input event, the state of the state machine is updated accordingly.

**Usage Example**:
```c
#include <stdio.h>
#include "fsm.h"

enum
{
    TestState_Init = 0,
    TestState_Stanby,
    TestState_Run,
    TestState_Error,
    TestState_Exit,
};

enum
{
    TestEvent_Init = 0,
    TestEvent_ToRun,
    TestEvent_ToStanby,
    TestEvent_Error,
    TestEvent_Exit,
};

/* State transition diagram
+-----------+          +-----------+              +-----------+
|           |          |           | -----------> |           |
|   init    | -------> |  standby  |              |    run    |
|           |          |           | <----------  |           |
+-----------+          +-----------+              +-----------+
                             |       \          /       |
                             |        \        /        |
                             |         \      /         |
                             |          \    /          |
                             |           \  /           |
                             |            \/            |
                             |            /\            |
                             |           /  \           |
                             |          /    \          |
                             |         /      \         |
                             |        /        \        |
                             |       /          \       |
                             v      v            v      v
                       +-----------+              +-----------+
                       |           |              |           |
                       |   error   | -----------> |   exit    |
                       |           |              |           |
                       +-----------+              +-----------+
*/
StateTransform TestFsmTable[] = 
{   /*  from,               to,                 event,              action */
    {TestState_Init,    TestState_Stanby,   TestEvent_Init,     NULL},
    {TestState_Stanby,  TestState_Run,      TestEvent_ToRun,    NULL},
    {TestState_Stanby,  TestState_Error,    TestEvent_Error,    NULL},
    {TestState_Stanby,  TestState_Exit,     TestEvent_Exit,     NULL},
    {TestState_Run,     TestState_Stanby,   TestEvent_ToStanby, NULL},
    {TestState_Run,     TestState_Error,    TestEvent_Error,    NULL},
    {TestState_Run,     TestState_Exit,     TestEvent_Exit,     NULL},
    {TestState_Error,   TestState_Exit,     TestEvent_Exit,     NULL},
};

int main(int argc, char* argv[])
{
    FSM TestFsm;
    int event[] = { TestState_Init, TestEvent_ToRun, TestState_Exit };

    fsm_init(&TestFsm, TestFsmTable, 8, TestState_Init);

    printf("%d\r\n", TestFsm.count);

    for (int i = 0, n = sizeof(event) / sizeof(event[0]); i < n; i++)
    {
        fsm_execute(&TestFsm, event[i]);
        printf("state %d\r\n", TestFsm.state);
    }

    printf("%c", getchar());
    return 0;
}
```