machina.BehavioralFsm

machina.BehavioralFsm

machina.BehavioralFsm instance members

BehavioralFsm instances receive properties provided by machina.utils.getDefaultOptions (as defaults) in addition to what you provide to the constructor's options argument. The most common instance members you'll utilize are as follows:

Member	Description
initialState	A string value indicating the initial state in which the FSM should exist. Defaults to uninitialized.
eventListeners	An object which holds event subscribers for events emitted from the FSM. It is an object that has a key for any event emitted, and the value of the key is an array of subscriber callbacks. Normally, subscribers get added by calling fsmInstance.on("eventName", callback), but providing this argument allows you to set multiple subscribers up in advance as part of creating the FSM.
states	An object where each top-level (own) property is a 'state', and each state property is an object containing the input handlers the FSM should utilize while in that state. Input handlers can be functions, a string value that matches another state name, or one of the special handlers (_onEnter, _onExit or the * catch-All handler). Please note that not including a states object will render your FSM useless (unless it's being used a base for more constructor extensions).
namespace	A string value used as a namespace for the FSM, should it be (for example) wired into a message bus.

machina.BehavioralFsm prototype members

Member	Description
initialize()	The prototype implementation is simply a no-op. The intention is for the developer to override this method if needed.
emit(eventName [, arg1, arg2…])	Method used to trigger/emit an event. The first argument is the string name of the event. Subsequent arguments are optional, and will be passed to the subscriber callback(s) in the same order.
handle( client, inputType [, arg1, arg2…])	The handle call is the primary way you tell the FSM to handle input. The client is the state you want the behavioral FSM to act upon. The inputType argument is the name of the input (maps to the handler name). Subsequent arguments will be passed to the handler method (if one exists) for that inputType. Calling handle tells the FSM to look in the current state for an explicit handler for the inputType. If one does not exist, the FSM checks the current state for a * ('catch-all') handler, and if one isn't found, it checks the FSM for a top level * handler. If none of these are found, the FSM will ignore the input other than emitting a nohandler event.
transition(client, state)	The method used to transition the FSM to a new state. The client is the state you want the behavioral FSM to act upon. This should always be used instead of manually assigning the state instance property. transition will cause the current state's _onExit handler to run (if applicable), the new state's _onEnter handler to run, and for any queued events to be run in the new state.
processQueue(client)	Called internally by machina during a transition. It iterates over any queued events (in the client's inputQueue array) and replays any that fit the constraints of the new state. The client is the state you want the behavioral FSM to act upon.
clearQueue( client [, stateName] )	Helper method that empties part or all of the client's inputQueue array. The client is the state you want the behavioral FSM to act upon. Not providing the stateName argument will empty the entire queue. If you optionally provide the stateName (string) argument value, it will clear the queue of any events that have been deferred until a state transition into the state matching stateName.
deferUntilTransition( client, [ stateName ] )	Calling this method inside an input handler will defer the current input until the next state transition. The client is the state you want the behavioral FSM to act upon. Providing the optional stateName argument allows you to tell the FSM to wait until it transitions into that state at a later time before it attempts to replay the input. Input that is deferred is replayed after the new state's _onEnter handler has executed.
deferAndTransition( client, stateName )	Defers the current input and immediately transitions to the specified state. The same as calling deferUntilTransition( client, targetState) and transition( client, targetState ) in that order.
compositeState( client )	Returns the client's "composite" state for an FSM hierarchy, where each state is separated by a period. For example, if a crosswalk FSM has a parent state of vehiclesEnabled and the child FSM for that parent state has a state value of green, then the composite state will be vehiclesEnabled.green.
on( eventName, callback )	Method that adds a new subscriber callback to be fired whenever the FSM triggers an event matching the eventName. This method returns an object which contains a reference to the callback, eventName and an off method that can be invoked to unsubscribe the listener.
off( [eventName [, callback]] )	In addition to being able to unsubscribe via the object returned by calling on(), this method can also be used to unsubscribe events. Not providing any arguments will clear ALL event listeners from the FSM. Providing only the eventName argument will clear all callbacks for that event. Providing both eventName and callback will unsubscribe the specific listener.

###BehavioralFsm Clients Since BehavioralFsm instances don't track their own state, but instead are meant to act upon external state passed in as a 'client', these client instances get stamped with a __machina__ property to track machina-related metadata. This property contains the following:

Member	Description
targetReplayState	A value used internally as the FSM transitions - it tells the FSM which state should be used to play any queued events when a single transition could result in multiple transitions in one call stack.
state	The current state in which the FSM resides.
priorState	The state the FSM was in prior to the current state.
priorAction	The last action/input the FSM handled.
currentAction	The action/input the FSM is currently handling.
currentActionArgs	The arguments passed to the handler (does not include the client passed as the first arg).
initialize	A function that is executed once the instance of the FSM has been created. This gives you a chance to perform any initialization concerns on the FSM before machina itself triggers the newfsm event and before the FSM transitions into the initialState.
inputQueue	An array containing any queued input handler actions (queued by calling deferUntilTransition).
inExitHandler	A bool value that's marked as true when the FSM's executing behavior being applied to the client is in a state's _onExit handler.