NAME

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

VERSION

version 0.07

SYNOPSIS

    package LightSwitch;

    use State::Machine::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

State::Machine::Simple is a micro-framework for defining simple state machines using State::Machine. State::Machine 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 State::Machine::Simple. This library is a Moose-based implementation of the State::Machine library.

    package CallCenter::Workflow::TelephoneCall;

    use State::Machine::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.