/ 
Machine-State-0.05
/ Machine::State::Simple

NAME

Machine::State::Simple - Simple State Machine DSL

VERSION

version 0.05

SYNOPSIS

package LightSwitch;

use Machine::State::Simple -dsl;

# light-switch circular-state example

topic 'typical light switch';

in_state 'is_off' => ( when => { turn_on => 'is_on' } );
at_state 'is_on'  => ( when => { turn_off => 'is_off' } );

sub _before_turn_on {
    my ($trans, $state, @args) = @_;
    # do something; maybe plug it in
}

sub _during_turn_on {
    my ($trans, $state, @args) = @_;
    # do something; maybe turn the knob or pull the lever
}

sub _after_turn_on {
    my ($trans, $state, @args) = @_;
    # do something else; maybe change adjust the positioning
}

package main;

my $lightswitch = LightSwitch->new;

$lightswitch->apply('turn_off');
$lightswitch->status; # is_off

DESCRIPTION

Machine::State::Simple is a micro-framework for defining simple state machines using Machine::State. Machine::State allows you to define a process, model interactions, and enforce the integrity of those interactions. State machines can also be used as a system for processing and reasoning about long-running asynchronous transactions. As an example of the functionality provided by this DSL, the follow is a demonstration of modeling a fictitious call-center process modeled using Machine::State::Simple. This library is a Moose-based implementation of the State::Machine library.

package CallCenter::Workflow::TelephoneCall;

use Machine::State::Simple -dsl;

topic 'support telephone call';

# initial state
at_state ringing => (
    # next transition
    next => 'connect',

    # applicable transitions
    when => {
        hangup  => 'disconnected', # transition -> resulting state
        connect => 'connected',    # transition -> resulting state
    }
);

in_state connected => (
    next => 'request_dept',
    when => {
        hangup       => 'disconnected',
        request_dept => 'transferred',
    }
);

in_state transferred => (
    next => 'answer',
    when => {
        hangup    => 'disconnected',
        voicemail => 'disconnected',
        answer    => 'answered',
    }
);

in_state answered => (
    next => 'hangup',
    when => {
        hangup => 'disconnected'
    }
);

in_state 'disconnected'; # end-state (cannot transition from)

EXPORTS

-dsl

The dsl export group exports all functions instrumental in modeling a simple state machine. The following is a list of functions exported by this group:

  • at_state

  • in_state

  • topic

FUNCTIONS

at_state

at_state name => (%attributes);

at_state answered => (when => { hangup => 'disconnected' });
# using the telephone example provided in the description, this state
# definition can be read as ... a $state (answered) $topic (support
# telephone call) $transition (hangup) and is now $state (disconnected)

The at_state function is analogous to the in_state function and additionally denotes that it's state definition is the root state (starting point).

in_state

in_state name => (%attributes);

in_state connected => (when => { request_dept => 'transferred' });
# using the telephone example provided in the description, this state
# definition can be read as ... a $state (connected) $topic (support
# telephone call) $transition (request_dept) and is now $state (transferred)

The in_state function defines a state and optionally it's transitions. The in_state function requires a state name as it's first argument, and optionally a list of attributes that will be used to configure other state behavior. The value of the when attribute should be a hashref whose keys are names of transitions, and whose values are names of states.

topic

topic 'process credit card';

The topic function takes an arbitrary string which describes the purpose or intent of the state machine.

AUTHOR

Al Newkirk <anewkirk@ana.io>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Al Newkirk.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.