Introduction
This package provides an expressive way to specify, run and debug finite state machines in Javascript/Livescript/Coffeescript/Whatever:
Main features:
- Express compact state transitions with regular expressions
- Debug your FSM on line with a mini-server (powered by
socketio
).
Note: The fsm runs server-side! This is not compatible with browsers at the moment.
Installation
To install, use npm
:
npm install fsmexpress
Example
For a complete livescript example, check this link out.
Usage
To import in you program (livescript
code)[^1]:
fsm = require('fsmexpress').fsm;
any-of = require('fsmexpress').any-of;
Create fsm and instantiate states
Create a finite state machine:
fs = new fsm()
Define states (livescript
code):
fs.define-as-states([ 'II' 'SI' 'PI' 'OI'
'IS' 'SS' 'PS' 'OS'
'IP' 'SP' 'PP' 'OP'
'IC' 'SC' 'PC' 'OC' 'error' ])
fs.define-as-initial('II')
Define transitions
Define a transition (using a regular expression) from all states
beginning with 'I', excluding some states (IP
, IC
) on a specific event (an_event
) and register action action_to_trigger
(function) when that happens:
fs.from('I(.+)')
.but-not-from(any-of(['IP' 'IC']))
.on('an_event')
.next-is('S-')
.but-before-do(action_to_trigger)
Note: the target state S-
is a state beginning with S
and ending with the matched text in (.+)
in the from
expression. So the above statement will generate only two different state transitions (because 'IP' 'IC'
are not allowed from
states:
II -> SI
IS -> SS
You can also define what to do when the starting state is not among the allowed ones (by using the otherwise-is
function):
fs.from('(.+)S')
.but-not-from(any-of(['IS' 'SS' 'PS']))
.on('another_event')
.next-is('-P')
.otherwise-is('error')
In the above case, whenever the starting state is among ['IS' 'SS' 'PS']
, the next state associated with another_event
is error
.
Unfold and optimize
After the state transitions have been setup, invoke unfold
to generate actual state transition rules:
fs.unfold()
Prune states that are not reachable:
fs.optimize()
Linking to an event emitter
To register an event emitter:
fs.register-event-emitter(the_event_emitter)
So, everytime the_event_emitter
emits a signal the fsm is triggered according to the rules.
Practically, let's assume that we have the following event emitter:
class tester extends EventEmitter
run_op: ~>
@emit 'anEvent'
setTimeout(@run_tr, 300)
run_tr: ~>
@emit 'anEvent2'
setTimeout(@run_fl, 300)
run_fl: ~>
@emit 'anotherEvent'
setTimeout(@run_op, 300)
# @emit 'triggerOpen'
# @emit 'executedOpen'
Let's register it and start the finite state machine:
tst = new tester()
# Register event emitter and start the fsm
fs.register-event-emitter(tst)
fs.start()
# Start the event generation:
tst.run_op()
State transitions will happen according to the emitted events.
GUI debug
You can have a visual representation of the FSM that is served through a small web service (screenshot above):
red = "#9d261d"
gre = "#46a546"
blu = "#049cdb"
# GUI related stuff..
fs.prepare-emit()
fs.mark transition: '.+', with-color: 'lightgrey'
fs.mark transition: '.+Open', with-color: "#gre"
fs.mark transition: '.+Close', with-dashed-color: "#gre"
fs.mark transition: 'failed.+', with-color: "indianred"
fs.mark state: '.+', with-color: 'lightgrey'
fs.mark state: 'error', with-color: 'indianred'
fs.mark state: fs.initial, with-color: "#gre"
fs.mark state: fs.final, with-color: "lightsteelblue"
console.log fs.data
fs.serve(6970, 'my fsm')
You can see live state transitions (wherever the fsm is, even remotely, provided that the port can be accessed).
History
- 4/6/2013 - Release of 0.0.1
- 4/9/2013 - Update of Readme file
License
MIT
[^1]: In livescript, dashes "-" are used to create camelized Javascript identifiers. So, any-of
is translated to anyOf
by the livescript compiler.