fsm

README

fsm

Package fsm allows you to add finite-state machines to your Go code.

States and Events are defined as int consts :

const (
    StateFoo fsm.State = iota
    StateBar
)

const (
    EventFoo fsm.Event = iota
    EventBar
)

f := fsm.New(StateFoo)
f.Transition(
    fsm.On(EventFoo), fsm.Src(StateFoo),
    fsm.Dst(StateBar),
)

You can have custom checks or actions :

f.Transition(
    fsm.Src(StateFoo), fsm.Check(func () bool {
        // check something
    }),
    fsm.Call(func () {
        // do something
    }),
)

Transitions can be triggered the second time an event occurs :

f.Transition(
    fsm.On(EventFoo), fsm.Src(StateFoo), fsm.Times(2),
    fsm.Dst(StateBar),
)

Functions call be called when entering or leaving a state :

f.EnterState(StateFoo, func() {
    // do something	
})
f.Enter(func(state fsm.State) {
    // do something	
})
f.ExitState(StateFoo, func() {
    // do something	
})
f.Exit(func(state fsm.State) {
    // do something	
})

Installation

go get github.com/cocoonspace/fsm

Contribution guidelines

Contributions are welcome, as long as:

• unit tests & comments are included,
• no external package is used.

License

MIT - See LICENSE

Documentation

Overview

Package fsm allows you to add Finite State Machines to your code.

const (
	StateFoo fsm.State = iota
	StateBar
)

const (
	EventFoo fsm.Event = iota
)

f := fsm.New(StateFoo)
f.Transition(
	fsm.On(EventFoo), fsm.Src(StateFoo),
	fsm.Dst(StateBar),
)

You can have custom checks or actions :

f.Transition(
	fsm.Src(StateFoo), fsm.Check(func() bool {
		// check something
	}),
	fsm.Call(func() {
		// do something
	}),
)

Index

• type Event
• type FSM
  • func New(initial State) *FSM
  • func (f *FSM) Current() State
  • func (f *FSM) Enter(fn func(state State))
  • func (f *FSM) EnterState(state State, fn func())
  • func (f *FSM) Event(e Event) bool
  • func (f *FSM) Exit(fn func(state State))
  • func (f *FSM) ExitState(state State, fn func())
  • func (f *FSM) Reset()
  • func (f *FSM) Transition(opts ...Option)
• type Option
  • func Call(fn func()) Option
  • func Check(fn func() bool) Option
  • func Dst(s State) Option
  • func NotCheck(fn func() bool) Option
  • func On(e Event) Option
  • func Src(s ...State) Option
  • func Times(n int) Option
• type State

Examples

• Call
• Check
• Times

Types

type Event

type Event int

Event is the event type. You can define your own values as

const (
	EventFoo fsm.Event = iota
	EventBar
)

type FSM

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

FSM is a finite state machine.

func New

func New(initial State) *FSM

New creates a new finite state machine having the specified initial state.

func (*FSM) Current

func (f *FSM) Current() State

Current returns the current state.

func (*FSM) Enter

func (f *FSM) Enter(fn func(state State))

Enter sets a func that will be called when entering a state.

func (*FSM) EnterState

func (f *FSM) EnterState(state State, fn func())

EnterState sets a func that will be called when entering a state.

func (*FSM) Event

func (f *FSM) Event(e Event) bool

Event send an Event to a machine, applying at most one transition. true is returned if a transition is applied.

func (*FSM) Exit

func (f *FSM) Exit(fn func(state State))

Exit sets a func that will be called when entering a state.

func (*FSM) ExitState

func (f *FSM) ExitState(state State, fn func())

ExitState sets a func that will be called when entering a state.

func (*FSM) Reset

func (f *FSM) Reset()

Reset resets the machine to its initial state.

func (*FSM) Transition

func (f *FSM) Transition(opts ...Option)

Transition creates a new transition, usually having trigger On an Event, from a Src State, to a Dst State.

type Option

type Option func(*transition)

Option defines a transition option.

func Call

func Call(fn func()) Option

Call defines a function that is called when a Transition occurs.

Example

package main

import (
	"fmt"

	"github.com/cocoonspace/fsm"
)

const (
	StateFoo fsm.State = iota
	StateBar
)

const (
	EventFoo fsm.Event = iota
	EventBar
)

func main() {
	f := fsm.New(StateFoo)
	f.Transition(
		fsm.On(EventFoo), fsm.Src(StateFoo),
		fsm.Dst(StateBar), fsm.Call(func() {
			fmt.Println("Call called")
		}),
	)
}

func Check

func Check(fn func() bool) Option

Check is an external condition that allows a Transition only if fn returns true.

Example

package main

import (
	"github.com/cocoonspace/fsm"
)

const (
	StateFoo fsm.State = iota
	StateBar
)

const (
	EventFoo fsm.Event = iota
	EventBar
)

func main() {
	f := fsm.New(StateFoo)
	f.Transition(
		fsm.On(EventFoo), fsm.Src(StateFoo), fsm.Check(func() bool {
			return true
		}),
		fsm.Dst(StateBar),
	)
}

func Dst

func Dst(s State) Option

Dst defines the new State the machine switches to after a Transition.

func NotCheck

func NotCheck(fn func() bool) Option

NotCheck is an external condition that allows a Transition only if fn returns false.

func On

func On(e Event) Option

On defines the Event that triggers a Transition.

func Src

func Src(s ...State) Option

Src defines the source States for a Transition.

func Times

func Times(n int) Option

Times defines the number of consecutive times conditions must be valid before a Transition occurs. Times will not work if multiple Transitions are possible at the same time.

Example

package main

import (
	"github.com/cocoonspace/fsm"
)

const (
	StateFoo fsm.State = iota
	StateBar
)

const (
	EventFoo fsm.Event = iota
	EventBar
)

func main() {
	f := fsm.New(StateFoo)
	f.Transition(
		fsm.On(EventFoo), fsm.Src(StateFoo), fsm.Times(2),
		fsm.Dst(StateBar),
	)

	_ = f.Event(EventFoo) // no transition
	_ = f.Event(EventFoo) // transition to StateBar
}

type State

type State int

State is the state type. You can define your own values as

const (
	StateFoo fsm.State = iota
	StateBar
)