NAME

SYNOPSIS

  use POE::Kernel;
  use POE::NFA;
  use POE::Wheel::ReadLine;

  # Spawn an NFA and enter its initial state.
  POE::NFA->spawn(
    inline_states => {
      initial => {
        setup => \&setup_stuff,
      },
      state_login => {
        on_entry => \&login_prompt,
        on_input => \&save_login,
      },
      state_password => {
        on_entry => \&password_prompt,
        on_input => \&check_password,
      },
      state_cmd => {
        on_entry => \&command_prompt,
        on_input => \&handle_command,
      },
    },
  )->goto_state(initial => "setup");

  POE::Kernel->run();
  exit;

  sub setup_stuff {
    $_[RUNSTATE]{io} = POE::Wheel::ReadLine->new(
      InputEvent => 'on_input',
    );
    $_[MACHINE]->goto_state(state_login => "on_entry");
  }

  sub login_prompt { $_[RUNSTATE]{io}->get('Login: '); }

  sub save_login {
    $_[RUNSTATE]{login} = $_[ARG0];
    $_[MACHINE]->goto_state(state_password => "on_entry");
  }

  sub password_prompt { $_[RUNSTATE]{io}->get('Password: '); }

  sub check_password {
    if ($_[RUNSTATE]{login} eq $_[ARG0]) {
      $_[MACHINE]->goto_state(state_cmd => "on_entry");
    }
    else {
      $_[MACHINE]->goto_state(state_login => "on_entry");
    }
  }

  sub command_prompt { $_[RUNSTATE]{io}->get('Cmd: '); }

  sub handle_command {
    $_[RUNSTATE]{io}->put("  <<$_[ARG0]>>");
    if ($_[ARG0] =~ /^(?:quit|stop|exit|halt|bye)$/i) {
      $_[RUNSTATE]{io}->put('Bye!');
      $_[MACHINE]->stop();
    }
    else {
      $_[MACHINE]->goto_state(state_cmd => "on_entry");
    }
  }

DESCRIPTION

A finite automaton is a state machine with a bounded number of states and transitions. Technically, POE::NFA objects may modify themselves at run time, so they aren't really "finite". Run-time modification isn't currently supported by the API, so plausible deniability is maintained!

Deterministic state machines are ones where all possible transitions are known at compile time. POE::NFA is "non-deterministic" because transitions may change based on run-time conditions.

But more simply, POE::NFA is like POE::Session but with banks of event handlers that may be swapped according to the session's run-time state. Consider the SYNOPSIS example, which has "on_entry" and "on_input" handlers that do different things depending on the run-time state. POE::Wheel::ReadLine throws "on_input", but different things happen depending whether the session is in its "login", "password" or "command" state.

POE::NFA borrows heavily from POE::Session, so this document will only discuss the differences. Please see POE::Session for things which are similar.

PUBLIC METHODS

  my %states = (
    state_1 => {
      event_1 => \&handler_1,
      event_2 => \&handler_2,
    },
    state_2 => {
      event_1 => \&handler_3,
      event_2 => \&handler_4,
    },
  );

  $machine{state_2}{event_1} = \&handler_3;

  object_states => {
    state_1 => [
      $object_1 => [qw(event_1 event_2)],
    ],
    state_2 => [
      $object_2 => {
        event_1 => method_1,
        event_2 => method_2,
      }
    ]
  }

  # Switch to the next state.
  $_[MACHINE]->goto_state( 'next_state' );

  # Switch to the next state, and call a specific entry point.
  $_[MACHINE]->goto_state( 'next_state', 'entry_event' );

  # Switch to the next state; call an entry point with some values.
  $_[MACHINE]->goto_state( 'next_state', 'entry_event', @parameters );

  $_[MACHINE]->stop();

  $machine->call_state( 'return_here', 'new_state', 'entry_event' );

  $_[MACHINE]->return_state( 'success', @success_values );

PREDEFINED EVENT FIELDS

  $_[MACHINE]->goto_state( $next_state, $next_state_entry_event );

PREDEFINED EVENT NAMES

See POE::Session's "PREDEFINED EVENT NAMES" section for more information about other predefined events.

The events are: "poe_nfa_goto_state", "poe_nfa_push_state", "poe_nfa_pop_state", "poe_nfa_stop".

Yes, all the internal events begin with "poe_nfa_". More may be forthcoming, but they will always begin the same way. Therefore please do not define events beginning with "poe_nfa_".

SEE ALSO

The SEE ALSO section in POE contains a table of contents covering the entire POE distribution.

BUGS

POE::NFA is not as feature-complete as POE::Session. Your feedback is appreciated.

AUTHORS & COPYRIGHTS