<?php
/**
 * Finite state machine skeleton
 * embodying a Moore FSM
 * (c) 2006 Ouest Systèmes Informatiques (OSI)
 * Licensed under the CeCILL 2.0 license
 *
 * $Id: u_fsm.php,v 1.1 2006-12-03 23:20:08 marand Exp $
 */
require_once('misc.php'); // for func_name()

abstract class fsm
  {
  /**
   * the current state of the object
   * @var string
   */
  protected $f_state;

  /**
   * Transitions holds the transitions table
   * state1
   *   event1
   *     result1
   *     action1
   *   event2
   *     ...
   *   ..
   * ..
   * @var array
   */
  protected $f_transitions = null;

  /**
   * constructor initializes the FSM to the first
   * state in the transitions table
   * @return void
   */
  public function __construct()
    {
    $this->_check_transitions();

    reset($this->f_transitions);
    $x = each($this->f_transitions);
    $x = $x[0];
    $this->f_state = $x;
    }

  /**
   * make sure a transitions graph has been defined
   * @return void
   */
  private function _check_transitions()
    {
    if (!isset($this->f_transitions))
      throw new Exception('No FSM processing is allowed without a transitions table');
    }

  /**
   * getter for f_state
   */
  public function get_state()
    {
    return $this->f_state;
    }

  /**
   * return the list of events accepted in the current state
   * @return array
   */
  public function get_accepted_events()
    {
    $this->_check_transitions();

    $events = array_keys($this->f_transitions[$this->f_state]);
    // echo func_name() . ": " . print_r($events, true). "\n";
    return $events;
    }

  /**
   * return the list of outcome accepted in the current state for the give event
   * @param string $event_name
   * @param mixed $outcome
   * @return array
   */
  public function get_accepted_outcomes($event_name)
    {
    // echo func_name() . "\n";
    $this->_check_transitions();

    if (!$this->is_event_allowed($event_name))
      throw new Exception(func_name() . ": event \"$event_name\" not allowed in state \"$this->f_state\"\n");

    $outcomes = array_keys($this->f_transitions[$this->f_state][$event_name]);
    //echo "outcomes for event $event_name: " . print_r($outcomes, true) . "\n";
    return $outcomes;
    }

  /**
   * is this event accepted in the current state
   * the FSM is in ?
   *
   * @param string $event_name
   * @return boolean
   */
  public function is_event_allowed($event_name)
    {
    // echo func_name() . "($event_name)";
    $this->_check_transitions();

    $ret = in_array($event_name, $this->get_accepted_events());
    // echo ", result = <$ret>\n";
    return $ret;
    }

  /**
   * is a given outcome available for a given event,
   * considering the current context ?
   *
   * @param string $event_name
   * @param mixed $outcome
   * @return boolean
   */
  public function is_outcome_allowed($event_name, $outcome)
    {
    $this->_check_transitions();

    if (!$this->is_event_allowed($event_name))
      return false;

    $ret = array_key_exists($outcome, $this->get_accepted_outcomes($event_name));
    return $ret;
    }

  /**
   * apply an event
   *
   * @param string $event_name
   * @param array $params the
   * @return string resulting state
   */
  public function apply_event($event_name)
    {
    //echo func_name() . "\n";

    if (! $this->is_event_allowed($event_name))
      throw new Exception(func_name()
        . ":  Event \"$event_name\" not accepted in current state \"$this->f_state\"");

    $method_name = "f_$event_name";
    $outcomes = $this->get_accepted_outcomes($event_name);

    $result = $this->$method_name();

    if (!in_array($result, $outcomes))
      throw new Exception(func_name()
        . ": event guard. Transition on \"$event_name\" return invalid result: "
        . var_dump($result)
        . "\n");

    $this->f_state = $this->f_transitions[$this->f_state][$event_name][$result];
    // echo "new state: $this->f_state\n";

    return $result;
    }

  }