FSM

https://pkg.go.dev/github.com/looplab/fsm
Admin
FSM is a finite state machine library for Go, providing a structured way to manage state transitions...
Tokens:7,857
Snippets:101
Trust Score:10
Update:8 months ago
Show doc for...
Tokens:
Raw
### Get Available Transitions with AvailableTransitions in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Returns a slice of strings representing all transitions that are currently available from the FSM's current state. This is useful for determining possible next actions.

```go
func (f *FSM) AvailableTransitions() []string
```

--------------------------------

### Use FSM as a Struct Field in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Illustrates how to embed an FSM within a Go struct, enabling state management for specific objects. This example shows a 'Door' struct with an embedded FSM and a callback function to log state changes. It depends on the 'context' and 'fmt' packages.

```go
package main

import (
    "context"
    "fmt"

    "github.com/looplab/fsm"
)

type Door struct {
    To  string
    FSM *fsm.FSM
}

func NewDoor(to string) *Door {
    d := &Door{
        To: to,
    }

    d.FSM = fsm.NewFSM(
        "closed",
        fsm.Events{
            {Name: "open", Src: []string{"closed"}, Dst: "open"},
            {Name: "close", Src: []string{"open"}, Dst: "closed"},
        },
        fsm.Callbacks{
            "enter_state": func(_ context.Context, e *fsm.Event) { d.enterState(e) },
        },
    )

    return d
}

func (d *Door) enterState(e *fsm.Event) {
    fmt.Printf("The door to %s is %s\n", d.To, e.Dst)
}

func main() {
    door := NewDoor("heaven")

    err := door.FSM.Event(context.Background(), "open")
    if err != nil {
        fmt.Println(err)
    }

    err = door.FSM.Event(context.Background(), "close")
    if err != nil {
        fmt.Println(err)
    }
}

```

--------------------------------

### Get Current State with Current in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Returns the current state of the FSM as a string. This method provides the active state within the machine.

```go
func (f *FSM) Current() string
```

--------------------------------

### Get Metadata with Metadata in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Retrieves a metadata value from the FSM's store based on its key. It returns the value and a boolean indicating whether the key was found. This function was added in v0.3.0.

```go
func (f *FSM) Metadata(key string) (interface{}, bool)
```

--------------------------------

### Create and Use FSM in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Demonstrates the basic usage of the fsm package by creating a new Finite State Machine, transitioning through states using events, and printing the current state. It requires the 'context' and 'fmt' packages for operation.

```go
package main

import (
    "context"
    "fmt"

    "github.com/looplab/fsm"
)

func main() {
    fsm := fsm.NewFSM(
        "closed",
        fsm.Events{
            {Name: "open", Src: []string{"closed"}, Dst: "open"},
            {Name: "close", Src: []string{"open"}, Dst: "closed"},
        },
        fsm.Callbacks{},
    )

    fmt.Println(fsm.Current())

    err := fsm.Event(context.Background(), "open")
    if err != nil {
        fmt.Println(err)
    }

    fmt.Println(fsm.Current())

    err = fsm.Event(context.Background(), "close")
    if err != nil {
        fmt.Println(err)
    }

    fmt.Println(fsm.Current())
}

```

--------------------------------

### Construct FSM with NewFSM in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Creates a new Finite State Machine (FSM) instance. It takes an initial state, a list of event descriptions, and a map of callbacks. Callbacks can be defined for various stages of event processing and state changes.

```go
func NewFSM(initial string, events []EventDesc, callbacks map[string]Callback) *FSM
```

--------------------------------

### FSM Constructor

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Constructs a new FSM instance with specified initial state, events, and callbacks.

```APIDOC
## NewFSM

### Description
Constructs a FSM from events and callbacks. The events and transitions are specified as a slice of Event structs. Callbacks are added as a map where the key is parsed as the callback event and called in order.

### Method
`func NewFSM(initial string, events []EventDesc, callbacks map[string]Callback) *FSM`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- `*FSM` (pointer to FSM) - The newly constructed FSM instance.

#### Response Example
None

### Callbacks Order
1. `before_<EVENT>`
2. `before_event`
3. `leave_<OLD_STATE>`
4. `leave_state`
5. `enter_<NEW_STATE>`
6. `enter_state`
7. `after_<EVENT>`
8. `after_event`

Shorthand versions like `<NEW_STATE>` and `<EVENT>` are also supported.
```

--------------------------------

### FSM Methods

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Provides methods for interacting with the FSM, including checking available transitions, current state, and initiating events.

```APIDOC
## FSM Methods

### AvailableTransitions

#### Description
Returns a list of transitions available in the current state.

#### Method
`func (f *FSM) AvailableTransitions() []string`

### Can

#### Description
Returns true if the specified event can occur in the current state.

#### Method
`func (f *FSM) Can(event string) bool`

### Cannot

#### Description
Returns true if the specified event cannot occur in the current state. This is a convenience method for readability.

#### Method
`func (f *FSM) Cannot(event string) bool`

### Current

#### Description
Returns the current state of the FSM.

#### Method
`func (f *FSM) Current() string`

### Event

#### Description
Initiates a state transition with the named event. It can accept variable arguments that will be passed to callbacks. Returns an error if the transition is invalid or an internal error occurs.

#### Method
`func (f *FSM) Event(ctx context.Context, event string, args ...interface{}) error`

#### Errors
- `InTransitionError`: Asynchronous transition already in progress.
- `InvalidEventError`: Event inappropriate in the current state or does not exist.
- `InternalError`: Internal bug during state transition.

### Is

#### Description
Returns true if the FSM is currently in the specified state.

#### Method
`func (f *FSM) Is(state string) bool`

### SetState

#### Description
Allows the user to move to a given state from the current state without triggering any callbacks.

#### Method
`func (f *FSM) SetState(state string)`

### Transition

#### Description
Wraps the underlying transitioner's transition method.

#### Method
`func (f *FSM) Transition() error`
```

--------------------------------

### Initiate State Transition with Event in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Initiates a state transition based on the provided event name. It can accept a variable number of arguments that are passed to associated callbacks. Returns an error if the transition is invalid or an internal issue occurs.

```go
func (f *FSM) Event(ctx context.Context, event string, args ...interface{}) error
```

--------------------------------

### Visualize FSM in Graphviz Format (Go)

Source: https://pkg.go.dev/github.com/looplab/fsm/index

The Visualize function generates a string representation of the FSM in Graphviz format. This is useful for creating visual diagrams of the state machine's structure and transitions. It takes a pointer to an FSM as input.

```Go
func Visualize(fsm *FSM) string
```

--------------------------------

### Perform Transition with Transition in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Wraps the internal transitioner's transition method. This function is used to manually trigger a transition, potentially useful in specific scenarios where direct control is needed.

```go
func (f *FSM) Transition() error
```

--------------------------------

### FSM Metadata Management

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Methods for managing metadata associated with the FSM.

```APIDOC
## FSM Metadata Management

### DeleteMetadata

#### Description
Deletes the metadata value associated with the given key.

#### Method
`func (f *FSM) DeleteMetadata(key string)`

### Metadata

#### Description
Returns the value stored in metadata for the given key, along with a boolean indicating if the key was found.

#### Method
`func (f *FSM) Metadata(key string) (interface{}, bool)`

### SetMetadata

#### Description
Stores a data value in the FSM's metadata, indexed by the provided key.

#### Method
`func (f *FSM) SetMetadata(key string, dataValue interface{})`
```

--------------------------------

### Visualize FSM with Specified Type (Go)

Source: https://pkg.go.dev/github.com/looplab/fsm/index

The VisualizeWithType function allows for FSM visualization in a format determined by the VisualizeType parameter. If no type is specified, it defaults to GRAPHVIZ. This function returns the visualization string and an error. It takes an FSM pointer and a VisualizeType.

```Go
func VisualizeWithType(fsm *FSM, visualizeType VisualizeType) (string, error)
```

--------------------------------

### Visualize FSM in Mermaid Format (Go)

Source: https://pkg.go.dev/github.com/looplab/fsm/index

The VisualizeForMermaidWithGraphType function generates a visualization of the FSM in Mermaid format. Users can specify the desired graph type for the Mermaid diagram. This function returns the Mermaid string and an error if any occurs during generation. It requires an FSM pointer and a MermaidDiagramType.

```Go
func VisualizeForMermaidWithGraphType(fsm *FSM, graphType MermaidDiagramType) (string, error)
```

--------------------------------

### Manually Set State with SetState in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Allows the user to directly set the FSM to a specified state. This operation does not trigger any associated callbacks.

```go
func (f *FSM) SetState(state string)
```

--------------------------------

### Event Struct and Methods (Go)

Source: https://pkg.go.dev/github.com/looplab/fsm/index

The Event struct holds information about the current state transition, including the FSM instance, event name, source and destination states, any associated error, and arguments passed to callbacks. The Async method allows for asynchronous transitions, and the Cancel method can abort a transition.

```Go
type Event struct {
	// FSM is an reference to the current FSM.
	FSM *FSM

	// Event is the event name.
	Event string

	// Src is the state before the transition.
	Src string

	// Dst is the state after the transition.
	Dst string

	// Err is an optional error that can be returned from a callback.
	Err error

	// Args is an optional list of arguments passed to the callback.
	Args []interface{}
	// contains filtered or unexported fields
}

func (e *Event) Async()

func (e *Event) Cancel(err ...error)
```

--------------------------------

### FSM Struct (Go)

Source: https://pkg.go.dev/github.com/looplab/fsm/index

The FSM struct represents the Finite State Machine itself. It holds the current state and must be initialized using the NewFSM function to ensure proper operation.

```Go
type FSM struct {
	// contains filtered or unexported fields
}
```

--------------------------------

### Define Visualization Types in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Defines the VisualizeType string type and its constants for specifying different visualization formats like Graphviz and various Mermaid styles (stateDiagram, flow chart). These types control how the FSM's structure is rendered.

```go
type VisualizeType string

const (
	// GRAPHVIZ the type for graphviz output (http://www.webgraphviz.com/)
	GRAPHVIZ VisualizeType = "graphviz"
	// MERMAID the type for mermaid output (https://mermaid-js.github.io/mermaid/#/stateDiagram) in the stateDiagram form
	MERMAID VisualizeType = "mermaid"
	// MermaidStateDiagram the type for mermaid output (https://mermaid-js.github.io/mermaid/#/stateDiagram) in the stateDiagram form
	MermaidStateDiagram VisualizeType = "mermaid-state-diagram"
	// MermaidFlowChart the type for mermaid output (https://mermaid-js.github.io/mermaid/#/flowchart) in the flow chart form
	MermaidFlowChart VisualizeType = "mermaid-flow-chart"
)
```

--------------------------------

### Callback Function Type (Go)

Source: https://pkg.go.dev/github.com/looplab/fsm/index

The Callback type defines the signature for functions that can be used as callbacks within the FSM. Callbacks receive the current event information, including context and event details.

```Go
type Callback func(context.Context, *Event)
```

--------------------------------

### EventDesc Struct (Go)

Source: https://pkg.go.dev/github.com/looplab/fsm/index

The EventDesc struct defines a single event transition within the FSM. It specifies the event's name, the valid source state(s), and the destination state upon successful transition. This is used when initializing the FSM.

```Go
type EventDesc struct {
	// Name is the event name used when calling for a transition.
	Name string

	// Src is a slice of source states that the FSM must be in to perform a
	// state transition.
	Src []string

	// Dst is the destination state that the FSM will be in if the transition
	// succeeds.
	Dst string
}
```

--------------------------------

### Set Metadata with SetMetadata in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Stores a data value in the FSM's metadata, indexed by a given key. This function was added in v0.3.0.

```go
func (f *FSM) SetMetadata(key string, dataValue interface{})
```

--------------------------------

### AsyncError Type and Methods (Go)

Source: https://pkg.go.dev/github.com/looplab/fsm/index

The AsyncError struct is returned when a callback initiates an asynchronous state transition. It includes the underlying error, context, and a function to cancel the transition. The Error method provides a string representation of the error, and Unwrap returns the underlying error.

```Go
type AsyncError struct {
	Err error

	Ctx              context.Context
	CancelTransition func()
}

func (e AsyncError) Error() string

func (e AsyncError) Unwrap() error
```

--------------------------------

### Check if Current State Matches with Is in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Checks if the FSM's current state is equal to the provided state string. Returns true if they match, false otherwise.

```go
func (f *FSM) Is(state string) bool
```

--------------------------------

### Callbacks Map Type (Go)

Source: https://pkg.go.dev/github.com/looplab/fsm/index

The Callbacks type is a map used for defining callbacks when creating a new FSM. It maps event names (strings) to their corresponding Callback functions.

```Go
type Callbacks map[string]Callback
```

--------------------------------

### InTransitionError Error Method in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Implements the error interface for the InTransitionError type, providing a string representation of the error.

```go
func (e InTransitionError) Error() string
```

--------------------------------

### FSM Error Types

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Defines the error types returned by FSM operations.

```APIDOC
## FSM Error Types

### InTransitionError

#### Description
Returned by `FSM.Event()` when an asynchronous transition is already in progress.

#### Struct Definition
`type InTransitionError struct {
	Event string
}`

#### Error Method
`func (e InTransitionError) Error() string`

### InternalError

#### Description
Returned by `FSM.Event()` and should ideally never occur, indicating a potential internal bug.

#### Struct Definition
`type InternalError struct{}`

#### Error Method
`func (e InternalError) Error() string`

### InvalidEventError

#### Description
Returned by `FSM.Event()` when the event cannot be called in the current state.

#### Struct Definition
`type InvalidEventError struct {
	Event string
	State string
}`

#### Error Method
`func (e InvalidEventError) Error() string`
```

--------------------------------

### Check if Event Can Occur with Can in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Checks if a given event can be triggered in the current state of the FSM. Returns true if the event is valid for the current state, false otherwise.

```go
func (f *FSM) Can(event string) bool
```

--------------------------------

### Define UnknownEventError in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Defines the UnknownEventError struct and its Error method. This error is returned by FSM.Event() when an event is encountered that is not defined within the FSM's configuration.

```go
type UnknownEventError struct {
	Event string
}

func (e UnknownEventError) Error() string {
	// Implementation omitted for brevity
}
```

--------------------------------

### InternalError Error Method in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Implements the error interface for the InternalError type, providing a string representation of the error.

```go
func (e InternalError) Error() string
```

--------------------------------

### Events Slice Type (Go)

Source: https://pkg.go.dev/github.com/looplab/fsm/index

The Events type is a slice of EventDesc structs, providing a convenient way to define multiple event transitions for initializing an FSM.

```Go
type Events []EventDesc
```

--------------------------------

### Check if Event Cannot Occur with Cannot in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Checks if a given event cannot be triggered in the current state of the FSM. This is a convenience method for readability, equivalent to !fsm.Can(event).

```go
func (f *FSM) Cannot(event string) bool
```

--------------------------------

### Define NotInTransitionError in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Defines the NotInTransitionError struct and its Error method. This error is returned by FSM.Transition() when attempting to perform a transition when an asynchronous transition is not currently in progress.

```go
type NotInTransitionError struct{}

func (e NotInTransitionError) Error() string {
	// Implementation omitted for brevity
}
```

--------------------------------

### CanceledError Type and Methods (Go)

Source: https://pkg.go.dev/github.com/looplab/fsm/index

The CanceledError struct is returned when a state transition is canceled by a callback. It wraps the underlying error that caused the cancellation. The Error method provides a string representation, and Unwrap returns the wrapped error.

```Go
type CanceledError struct {
	Err error
}

func (e CanceledError) Error() string

func (e CanceledError) Unwrap() error
```

--------------------------------

### Define Mermaid Diagram Types in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Defines the MermaidDiagramType string type and its associated constants for specifying different Mermaid diagram styles like FlowChart and StateDiagram. These are used to control the output format of generated diagrams.

```go
type MermaidDiagramType string

const (
	// FlowChart the diagram type for output in flowchart style (https://mermaid-js.github.io/mermaid/#/flowchart) (including current state)
	FlowChart MermaidDiagramType = "flowChart"
	// StateDiagram the diagram type for output in stateDiagram style (https://mermaid-js.github.io/mermaid/#/stateDiagram)
	StateDiagram MermaidDiagramType = "stateDiagram"
)
```

--------------------------------

### Delete Metadata with DeleteMetadata in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Deletes a metadata value associated with a given key from the FSM's metadata store. This function was added in v1.0.0.

```go
func (f *FSM) DeleteMetadata(key string)
```

--------------------------------

### Define NoTransitionError in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Defines the NoTransitionError struct and its associated Error and Unwrap methods. This error is returned by FSM.Event() when no state transition occurs, typically when the source and destination states are identical.

```go
type NoTransitionError struct {
	Err error
}

func (e NoTransitionError) Error() string {
	// Implementation omitted for brevity
}

func (e NoTransitionError) Unwrap() error {
	// Implementation omitted for brevity
}
```

--------------------------------

### InvalidEventError Error Method in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Implements the error interface for the InvalidEventError type, providing a string representation of the error.

```go
func (e InvalidEventError) Error() string
```

--------------------------------

### InvalidEventError Type in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Represents an error returned by FSM.Event() when the specified event cannot be called in the FSM's current state. It includes the event name and the current state for context.

```go
type InvalidEventError struct {
	Event string
	State string
}
```

--------------------------------

### InTransitionError Type in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Represents an error returned by FSM.Event() when an asynchronous transition is already in progress. It indicates that a new event cannot be processed until the current one completes.

```go
type InTransitionError struct {
	Event string
}
```

--------------------------------

### InternalError Type in Go

Source: https://pkg.go.dev/github.com/looplab/fsm/index

Represents an internal error that should ideally never occur during FSM operations. Its occurrence typically indicates a bug within the FSM implementation.

```go
type InternalError struct{}
```
Tokens:
Raw