reduce-fsm — reduce-fsm 0.1.4

Generate and display functional finite state machines that accumulate state in the same way as reduce. This package allows you to:

• Create basic fsm's (see fsm)
• Create lazy sequences from state machines (see fsm-seq)
• Create stateful filter functions for use with filter/remove (see fsm-filter)
• Visualise state machines as

defsm clj macro

(defsm fsm-name states & opts)

A convenience macro to define a fsm, equivalent to (def fsm-name (fsm states opts) see reduce-fsm/fsm for details

defsm-filter clj macro

(defsm-filter name states & fsm-opts)

A convenience macro to define an fsm filter, equivalent to (def fsm-name (fsm-filter states opts) see reduce-fsm/fsm-filter for details

defsm-inc clj macro

(defsm-inc fsm-name states & opts)

A convenience macro to define an incremental fsm, equivalent to (def fsm-name (fsm-inc states opts) see reduce-fsm/fsm-inc for details

defsm-seq clj macro

(defsm-seq name states & fsm-opts)

A convenience macro to define an fsm sequence, equivalent to (def fsm-name (fsm-seq states opts) see reduce-fsm/fsm-seq for details

fsm clj macro

(fsm states & fsm-opts)

Returns an fsm function that reads a sequence of events and returns an accumulated value (like reduce). The returned function will have the following 2 arities: [events] - accepts a sequence of events [val events] - accepts an initial value for the accumulator and a sequence of events. [initial-state val events] - start the fsm in the specified state with an accumulator value and a sequence of events.

The generated function will return when one of the following is true:

• There are no more events in the event sequence
• The fsm reaches a terminal state
• The fsm reaches a state defined by a function and it returns a truthy value

Parameters: fsm - the fsm definition (see below for syntax) fsm-opts - the following options are recognised: :default-acc val - sets the initial value for the accumulator in the single arity version of the function :dispatch - changes the way events are matched, the follow options are accepted: - :event-only (default) - events are matched using the core.match/match syntax against the event only - :event-and-acc - events use the default match syntax and are matched against [acc-value event] - :event-acc-vec - events are matches against a single vector of [[acc-value event]]

FSM definitions: fsm's are defined as follows: [[state {:is-terminal true/false}? event -> {:action a-fn}? target-state event2 -> ...] [target-state ...]]

Where state - is a keyword or function state - options (:is-terminal) are optional event - is any legal core.match pattern (see https://github.com/clojure/core.match) action - is optional but must be a function if specified and the return value will be used as the new accumulated state.

State and Event Functions: State functions are called like so (state-fn acc) where acc is the current accumulated state. Event functions are called with (event-fn acc event from-state to-state) where acc - is the current accumulated state event - is the event that fired the transition from-state - the state we're transitioning from to-state - the state we're transitioning to

See https://github.com/cdorrat/reduce-fsm for examples and documentation

fsm-dorothy clj

(fsm-dorothy fsm)

Create a dorothy digraph definition for an fsm

fsm-dot clj

(fsm-dot fsm)

Create the graphviz dot output for an fsm

fsm-event clj

(fsm-event fsm event)

process a single event with an incremental finite state machine (those created with fsm-inc or defsm-inc) Returns a map with the following keys: :state - the current state of the fsm after processing the event :value - the current accumulator value :is-terminated? - true when the fsm is in a terminal state and no more events can be processed

fsm-filter clj macro

(fsm-filter states & fsm-opts)

Returns a function that returns fsm filters suitable for use with clojure.core/filter and remove. Each state in the fsm definition has a :pass attribute that will be returned from the generated function when it is in that state.

The returned function will have the following 2 arities: [] - creates a filter with the default accumulator state (nil or the value from :default-acc) [val] - accepts an initial value for the accumulator [initial-state val] - start the fsm in the given state with the specified accumulator value

Parameters: fsm - the fsm definition (see below for syntax) fsm-opts - the following options are recognised: :default-acc val - sets the initial value for the accumulator in the single arity version function :dispatch - changes the way events are matched, the follow options are accepted: - :event-only (default) - events are matched using the core.match/match syntax against the event only - :event-and-acc - events use the default match syntax and are matched against [acc-value event]

FSM definitions: filters are defined as follows: [[state {:pass true/false}? event -> {:action a-fn}? target-state] [target-state ...]]

Where state is a keyword state option (:pass) is optional, it defaults to true event is any legal core.match pattern (see https://github.com/clojure/core.match) action is optional but must be a function if specified and their return value will be used as the new accumulated state

Event functions are called with (event-fn acc event from-state to-state) where acc - is the current accumulated state event - is the event that fired the transition from-state - the state we're transitioning from to-state - the state we're transitioning to

Example: Suppress numbers after seeing a 3 until we see a 6.

(def f (fsm-filter [[:initial 3 -> :suppressing] [:suppressing {:pass false} 6 -> :initial]]))

(= [1 2 6 1 2] (filter (f) [1 2 3 4 5 1 2 6 1 2]))

fsm-inc clj macro

(fsm-inc states & fsm-opts)

Define an incremental finite state machine. State definitions and capabilities are the same as reduce-fsm/fsm but events are provided by calls to (fsm-event inc-fsm event) instead of a sequence. Returns a function that takes the intial accumulator value (or none for the default nil) and returns an incremental fsm. Subsequent chained calls to fsm-event will move the fsm thought it's states. (reduce fsm-event ((inc-fsm [... fsm def ..])) events) is equivalent to (fsm [... fsm def ..] events)

fsm-seq clj macro

(fsm-seq states & fsm-opts)

Returns an fsm function that produces lazy sequences from a finite state machine. The state machines can optionally add new values to the lazy sequence on transitions (with the :emit option) and may accumulate state in the same way as reduce.

The returned function will have the following 2 arities: [events] - accepts a sequence of events [val events] - accepts an initial value for the accumulator and a sequence of events. [initial-state vals events] - start the seq fsm with a given state and accumulator value

The generated function will produce a lazy sequence that ends when one of the following is true:

• There are no more events in the event sequence
• The fsm reaches a terminal state
• The fsm reaches a state defined by a function and it returns a truthy value

Parameters: fsm - the fsm definition (see below for syntax) fsm-opts - the following options are recognised: :default-acc val - sets the initial value for the accumulator in the single arity version of the function :dispatch - changes the way events are matched, the follow options are accepted: - :event-only (default) - events are matched using the core.match/match syntax against the event only - :event-and-acc - events use the default match syntax and are matched against [acc-value event]

FSM definitions: fsm's are defined as follows: [[state {:is-terminal true/false}? event -> {:emit emit-fn :action action-fn}? target-state event2 -> ...] [target-state ...]]

Where state is a keyword or function state options (:is-terminal) are optional event is any legal core.match pattern (see https://github.com/clojure/core.match) emit is optional but its value must be a function, the return value will be added to the lazy sequence action is optional but its value must be a function if specified and their return value will be used as the new accumulated state

State and Event Functions: State functions are called with the current accumulated statelike so (state-fn acc). Emit functions are called with (emit-fn acc event), Action functions are called with (action-fn acc event from-state to-state) where acc - is the current accumulated state event - is the event that fired the transition from-state - the state we're transitioning from to-state - the state we're transitioning to

See https://github.com/cdorrat/reduce-fsm for examples and documentation

lookup-state clj

(lookup-state state-fn-map the-state)

save-fsm-image clj

(save-fsm-image fsm filename)

Save the state transition diagram for an fsm as a png. Expects the following parameters:

• fsm - the fsm to render
• filename - the output file for the png.

show-fsm clj

(show-fsm fsm)

Display the fsm as a diagram using graphviz (see http://www.graphviz.org/)