File: README

FSM Chat
========

What is it?
~~~~~~~~~~~
A PHP class for creating dialog robots, line-oriented file parsers and command line interpreters using Finite State Machine.

How to use?
~~~~~~~~~~~
First, include the class file.
Then you must define input patterns (as regular expressions), actions
to take when each of them are found, and optional machine states: the default target state (can be changed inside action; can be NULL if no change) and required state (NULL if no state check is needed).

Example: E1loadd - Dialog robot for interacting with Cisco AS53xx access server in order to continuously retrieve active calls information.

It is also possible to load FSM definition from file or another source usingLoadFSM() and LoadFSMFile() methods.

FSM definition syntax.
~~~~~~~~~~~~~~~~~~~~~~
It is just like Makefile syntax:

Line beginning with "#" is a comment.
Empty line is an end of state definiton (it is required even at EOF).
Line starting with an alphanumeric symbol is a state definition:
<Required state or *> <regular expression> [Default state]
Any following line starting with tab character is an action string.


Method description.
~~~~~~~~~~~~~~~~~~~

void FSM( string Expect, string Do [, string Target [, string Require] ] )
 Add a state definition.
  Expect: regex to match input string or packer.
  Do: PHP code to execute on match.
  Target: state to take if "Do" code did not specify it explicitly.
  Require: search for "Expect" only if macine is in this state.

 "Do" code may return:
   string: state to take.
   array("STOP"=> stop ,"NEWSTATE"=> state, "CONTINUE"=> cont, "REPLY"=> reply):
    if "stop" is nonzero, the FSM will stop with FSMSTOP_STOP return code.
    if "state" is nonempty string, the machine will take this state.
    if "cont" is nonzero, the FSM will ignore current match and continues match search.
    reply is passed directly to a stream.

void LoadFSM( string data )
 Load state definitions from string in syntax described above.

void LoadFSMFile( string filename )
 Load state definitions from specified file (wrapper for LoadFSM() ).

int RunString( resource Stream, string StartState )
 Runs a string-oriented FSM on specified stream, assuming StartState.
 Return codes:
  FSMSTOP_OK		Stopped at data end.
  FSMSTOP_STOP		Stopped by action handler.
  FSMSTOP_UNHANDLED	No matches found.

FSM Parser
==========

What is it?
~~~~~~~~~~~
A PHP class for creating parsers and preprocessors using Finite State Machine.

How to use?
~~~~~~~~~~~
First, include the class file.
Then you must define language constructs (as regular expressions), actions
to take when each of them are found, and optional machine states: the default
target state (can be changed inside action; can be NULL if no change) and
required state (NULL if no state check is needed).

Example: xmlparser.php - a very simple XML parser.

It is also possible to load FSM definition from file or another source using
LoadFSM() and LoadFSMFile() methods.

Example: xmlparser_loadfsm.php - the same XML parser loaded from .fsm file.

FSM definition syntax.
~~~~~~~~~~~~~~~~~~~~~~
It is just like Makefile syntax:

Line beginning with "#" is a comment.
Empty line is an end of state definiton (it is required even at EOF).
Line starting with an alphanumeric symbol is a state definition:
<Required state or *> <regular expression> [Default state]
Any following line starting with tab character is an action string.


Method description.
~~~~~~~~~~~~~~~~~~~

void FSM( string Expect, string Do [, string Target [, string Require] ] )
 Add a state definition.
  Expect: regex to match closest to current position.
  Do: PHP code to execute on best match. Inside this code, $STRING is an input string or packet that matches "Expect", $STATE is current state.
  Target: state to take if "Do" code did not specify it explicitly.
  Require: search for "Expect" only if macine is in this state.

 "Do" code may return:
   string: state to take.
   array("STOP"=> stop ,"NEWSTATE"=> state):
    if "stop" is nonzero, the FSM will stop with FSMSTOP_STOP return code.
    if "state" is nonempty string, the machine will take this state.

void LoadFSM( string data )
 Load state definitions from string in syntax described above.

void LoadFSMFile( string filename )
 Load state definitions from specified file (wrapper for LoadFSM() ).

int RunString( resource Stream, string StartState )
 Runs a string-oriented FSM algorithm on specified stream.
 Return codes:
  FSMSTOP_OK		Stopped at data end.
  FSMSTOP_STOP		Stopped by action handler.
  FSMSTOP_UNHANDLED	No matches found.

int RunPacket( resource Stream, string StartState )
 Runs a packet-oriented FSM algorithm on specified stream.
 Return codes:
  FSMSTOP_OK		Stopped at data end.
  FSMSTOP_STOP		Stopped by action handler.
  FSMSTOP_UNHANDLED	No matches found.