patterns.state.wren

State Machine

Utility classes for creating simple State Machines.

• References:

  • https://github.com/jakesgordon/javascript-state-machine
  • http://gameprogrammingpatterns.com/state.html

• Since: 1.0.0

• Example:

import "domepunk/patterns/state" for StateMachine, STB

// Create a new state machine
var water = StateMachine.new({
  "data": {
    "mydata":true
  },
  // Optional
  "ignoreErrors": false,

  "onError": Fn.new {|message, name, transition, machine|
    System.print("Error Handler")
    System.print(name)
    System.print(message)
  },

  "init": "solid",
  "transitions": [
    STB.new("melt").from("solid").to("liquid"),
    STB.new("freeze").from("liquid").to("solid"),
    STB.new("vaporize").from("liquid").to("gas"),
    STB.new("condense").from("gas").to("liquid"),
    STB.new("magnetize").from("solid").to("magnet").when {|transition|
      var canBeMagnetized = false
      System.print(transition)
      System.print("Can be magnetized? " + canBeMagnetized.toString)
      return canBeMagnetized
    }
  ],

  "methods": {
    "before": {
      "melt": Fn.new {|transition|
        System.print("Before Melting " + transition.toString)
      },
      "freeze": Fn.new{|transition|
        System.print("Before Freezing " + transition.toString)
      }
    },
    "on": {
      "melt": Fn.new{|transition|
        System.print("Is Melting " + transition.toString)
      }
    },
    "after": {
      "melt": Fn.new{|transition|
        System.print("After Melting " + transition.toString)
      }
    }
  }
})

// Start moving through states
System.print(water.state)
water.do("melt")
System.print(water.state)

water.do("vaporize")
System.print(water.state)

water.do("condense")
System.print(water.state)

// Go back to solid
water.do("freeze")
System.print(water.state)

// Condense is only possible from gas to liquid
// Current state should be solid
water.do("condense")

// State should remain solid
System.print(water.state)

// now should be liquid
water.do("melt")
System.print(water.state)

// And back to solid
water.reset()
System.print(water.state)

// This state is not possible
// since when condition is not true
water.do("magnetize")
System.print(water.state)

// This should be ignored
water.do("invalid")

---

Class StateMachine

import "domepunk/patterns/state" for StateMachine

// alias
import "domepunk/patterns/state" for SM

API

data

Get or set the state machine data

ignoreErrors

By default state errors triggers a fiber.abort(). use "ignoreErrors":true on the constructor's Map to ignore all errors.

onError

By default state errors triggers a fiber.abort(). use "onError": Fn.new {|message, name, transition, machine|} to catch errors.

error

Error message if available

• Signature: error:String?

state

Get the current state

isState(name)

Returns true if the provided name is equal to the current state name.

• Signature: is(name:String) -> Bool

states

Map of possible states

transitions

Map of possible transitions

do(name)

Tries to execute a transition by name.

• Signature: do(name:String) -> this
• Example: ice.do("melt")
• Throws: Fiber.abort() if ignoreErrors and onError properties are not set.

reset()

Resets the state to the init value.

construct new(machine)

Creates a new state machine.

• Signature: construct new(machine:Map) -> StateMachine.
• Throws: Fiber.abort() if machine is not a Map.

---

Class StateTransitionBuilder

import "domepunk/patterns/state" for StateTransitionBuilder

// alias
import "domepunk/patterns/state" for STB

API

from

Get or sets the from state

from = (value)

from(value)

Fluent interface

• Signature: from(value:<String|List>) -> this

any()

Fluent interface to set from = "*"

• Signature: any() -> this

to

Get or sets the to state

to = (value)

to(value)

Fluent interface

• Signature: to(value:String) -> this

name

Get or sets the name for the transition

name = (value)

name(value)

Fluent interface

• Signature: name(value:String) -> this

when

Get or set the when function to determine if the transition is possible

when(value)

Fluent interface

• Signature: when(value:Fn) -> this

construct new(name, from, to, when)

Creates a new transition.

• Signature: construct new(name:String?, from:String?, to:String?, when:Fn?) -> StateTransitionBuilder
• Example:

STB.new("melt").from("solid").to("liquid")

---

Class State

The basic State

API

name

The state name

machine

The machine where this state belongs

isInit

Is the initial state?

children

States to transition to

• Signature: children : [State]

parents

States from which this originates.

• Signature: parents : [State]

---

Class StateTransition

A state transition.

API

name

name of the transition

from

origin state

• Signature: from:<String|List>

to

final state

machine

state machine reference

before

Get or sets the before callback

before()

Executes the before callback

on

Get or sets the on callback

on()

Executes the on callback

after

Get or sets the before callback

after()

Executes the after callback

when

Get or sets the when callback. Return false if this transition should not be executed.

when()

Executes the when callback

step()

Triggers the on callback, then return the to property

construct new(name, from, to, when, machine)

Creates a new StateTransition