aquam

A Ruby DSL for writing Finite State Machines and validate its transitions’

Dependencies

aquam requires Ruby 2.1.x or later. No more dependencies.

Installation

$ gem install aquam

Getting started

aquam helps you to define Finite State Machines with a very simple DSL which
also will validate events, states and the transition between them.

First of all, you must know that a State Machine should be a different object,
where you specify the valid states and the transitions fired by the events.

That being said, lets take a look how it works.

Machine

Basically a Machine consists on

• states
• events
• transitions

There are three key words in our DSL that will help you to write your
own Finite State Machine, plus the attribute method.

Example

class DoorStateMachine < Aquam::Machine
  state :opened, OpenedDoorState
  state :closed, ClosedDoorState

  event :open do
    transition from: :closed, to: :opened
  end

  event :close do
    transition from: :opened, to: :closed
  end

  event :knock do
    transition from: :opened, to: :opened
    transition from: :closed, to: :closed
  end
end

NOTE: OpenedDoorState and ClosedDoorState definitions are missing but
we will cover States definition later.

state

A state maps a symbol to a State class.
It tells to the machine it is a valid state and which class represents it.

state :opened, OpenedDoorState

event

An event is a method which triggers the transition from one state to another.
Each state object must define only the events that are specified here.

event :open do
  ...
end

transition

A transition moves the state machine from state A to state B.
It can only be defined inside an event and you can define multiple transitions.

transition from: :a_valid_state, to: :other_valid_state

attribute

The attribute holds the name of the accessor in your own class where
the state name (string or symbol) will be stored.

By default uses :state as method accessor.

attribute :state

Extra

Being a subclass of Aquam::Machine also gives you some helpful class methods:

Class Method	Description	Example (ruby)
states	Hash Valid states mapped to a class	{ opened: OpenedDoorState }
events	Hash Valid events with all its transitions	{ open: { closed: :opened } }
valid_state?	Boolean Check if it is a valid state	true
valid_event?	Boolean Check if it is a valid event	true

And for instance methods it defines:

Class Method	Description	Example (ruby)
current_state	Aquam::State Instance of current state	#<ClosedDoorState:0x007...>
trigger	Aquam::State Instance of the new state	#<ClosedDoorState:0x008...>
valid_state?	Boolean Check if it is a valid state	true
valid_event?	Boolean Check if it is a valid event	true
valid_transition?	Boolean Check if it is a valid event	true

State

For each state, we define a class that implements the corresponding events.
Every bit of behavior that is state-dependent should become a method in the class.
aquam uses metaprogramming to define methods for every single event listed
in the state machine used.

Example

class OpenedDoorState < Aquam::State
  use_machine DoorStateMachine

  def close
    # Do something

    @object.state = :closed
  end
end

class ClosedDoorState < Aquam::State
  use_machine DoorStateMachine

  def open
    # Do something

    @object.state = :opened
  end
end

use_machine

This is the only method that you must call from every State class,
in order to define the interface according to the state machine.
Basically, it defines a method for every event defined in the state machine.

use_machine DoorStateMachine

NOTE: You can not change its value and it is accessible from all subclasses.