NAME
    `DFA::Command' - A Discrete Finite Automata command processor.

    `DFA::Generate' - A DFA program generator.

SYNOPSIS
            use DFA::Command;

            $stateMachine = new DFA::Command('Name of first event');
            # Or:
            #$stateMachine = DFA::Command -> new('Name of first event');

            $stateMachine -> load('Name of STT file');
            $stateMachine -> dump() if ($YouAreDebugging);

            $stateMachine -> process('Name of a event file');

DESCRIPTION
    `DFA::Command'

    This module reads a state transition table and then reads a data
    file looking for patterns as defined by regular expressions in
    the state transition table. When a transition is detected, a sub
    is called.

    `DFA::Generate'

    This module reads a state transition table and generates a Perl
    script which uses the module `DFA::Command' to process data
    according to the said table.

    These 2 modules are installed together.

    The name `DFA::Command' was chosen because:

    *   Somebody beat me to it. I wanted to use FSM (Finite State
        Machine)

    *   It creates an appropriate and convenient naming structure for
        related packages

    *   It installs easily in Unix, DOS and NT file systems

    *   It was developed in an environment where the input file
        contained commands and non-commands

INSTALLATION
    You install `DFA::Command', as you would install any perl module
    library, by running these commands:

            perl Makefile.PL
            make
            make test
            make install

    If you want to install a private copy of `DFA::Command' in your
    home directory, then you should try to produce the initial
    Makefile with something like this command:

            perl Makefile.PL LIB=~/perl
                    or
            perl Makefile.PL LIB=C:/Perl/Site/Lib

    If, like me, you don't have permission to write man pages into
    unix system directories, use:

            make pure_install

    instead of make install. This option is secreted in the middle
    of p 414 of the second edition of the dromedary book.

FEATURES
    When input is recognised, and an action function is about to be
    called, `popEvent()' checks that the event just detected was one
    of those expected in the current state.

    Just after an action function is called, the names of those
    events expected next are saved by `pushEvent()', in preparation
    for the next call to popEvent(). This feature and the previous
    one add overhead to the code, but form a marvellous debugging
    aid.

TEST SCRIPTS
    This package contains 3 sets of test files:

    *   Chinese

    *   Citizen

    *   X500

    Each set of test files contains:

    *   A state transition table. These files are called: Chinese.STT,
        Citizen.STT and X500DN.STT.

    *   A data file comtaining commands to be recognized by the DFA.
        These files are called: Chinese.dat, Citizen.dat and
        X500DN.dat.

    *   A script (1) demonstrating DFA::Generate, which when run
        generates a script (2) demonstrating DFA::Command. These
        scripts (1) are called: Chinese_Gen.pl, Citizen_Gen.pl and
        X500DN_Gen.pl.

    *   A script (2) which is the output of the previous script (1).
        These scripts (2) are called: ChineseTest.pl, CitizenTest.pl
        and X500DNTest.pl.

    *   A script (3) which is a version of (2), ie which I have
        generated and then modified to demonstrate some
        possibilities. These scripts (3) are called: Chinese.pl,
        Citizen.pl and X500DN.pl.

    *   2 log files output by these 2 scripts (2, 3). These logs are
        called: ChineseTest.log, Chinese.log, CitizenTest.log,
        Citizen.log, X500DNTest.log, X500DN.log.

    These scripts are all in a subdirectory called test. They are
    not in a subdirectory called t because the test harness does not
    provide for scripts to be run which generate scripts to be run.

CONFIGURATION OPTIONS
    chomp. Chomp each input line before processing it. Default: True

    commentPrefix. Ignore any input lines which start with this
    character. If trimLeading is false, and a line starts with
    whitespace followed by this character, that line will still be
    ignored. Default: '#'

    ignoreBlankLines. If true, ignore input lines which are blank
    after any chomping. Default: True

    trimLeading. If true, trim leading whitespace from each input
    line before processing it. Default: True

    trimTrailing. If true, trim trailing whitespace from each input
    line before processing it. This takes place after any chomping.
    Default: True

WARNING
    Go to any lengths whatsoever to avoid '%' characters in your
    input, since some C compilers butcher such input. Eg: The
    thrice-cursed Pyramid C++ compiler.

FORMAT OF A STATE TRANSITION TABLE
    Typically, there will be several lines for each state. These
    lines will differ by their event names, and the corresponding
    regexp which recognises the given event.

    Each line consists of these fields:

    *   The name of the state. Use \w as your guideline for forming
        names - ie no whitespace

    *   The regexp to be used to search for an event in the input line.
        In colloquial terms, this means the regexp to be used to
        search for the presence of a command in the input line. The
        arrival of this command is the event in question. Don't use
        whitespace within the regexp, since these lines are split on
        whitespace. (No package is perfect...)

    *   The name of the event detected if the regexp fires. Use \w - ie
        no whitespace

    *   The name of the action function to call if the regexp fires

    *   The names of the events which are allowed to follow the current
        event. Separate event names with '|', without surrounding
        whitespace. Alternately, as syntactic sugar, use the special
        token commandList to refer to all events where the name of
        the state is 'commandState'

Q & A
    How do I skip input text? Use a regexp of '.*' in your state
    transition table.

    If my input is 'abcd' and I have 2 regexps, 'abc.*' and
    'abcd.*', which regexp fires? Hmmm. Grammatically speaking, that
    is a question. Seriously tho, the order of evaluation will be
    the order in which keys are stored in hashes, which is not under
    user control. In short, you bungled it by using ambiguous
    regexps.

DEREFERENCING GUIDELINES
            $self -> {$state} -> {$event} -> {'sub'}          Name of subroutine
            $self -> {$state} -> {$event} -> {'nextState'}    Name of state
            $self -> {$state} -> {$event} -> {'validEvents'}  Event|Event
            $self -> {$state} -> {'RE'}                       [REs]
            $self -> {$state} -> {'event'}                    [Events]
            $self -> {'nextEvent'}                            [Expected events]
            $self -> {'state'}                                Current state
            $self -> {'event'}                                Current event
            $self -> {'command'}                              Current command
            $self -> {'RE'}                                   Current RE
            $self -> {'original'}                             Current input line, original
            $self -> {'clean'}                                Current input line, cleaned up
            $self -> {'$1'}                                   Current text matching () IN RE
            $self -> {'$2'}                                   Current text matching () IN RE
            $self -> {'$3'}                                   Current text matching () IN RE

PROCESSING of #if defined()
    Reference: PC Techniques, Aug/Sep 1993, p 102, Hax 166.
    Unimplemented.

WARNING re Perl bug
    As always, be aware that these 2 lines mean the same thing,
    sometimes:

    *   $self -> {'thing'}

    *   $self->{'thing'}

    The problem is the spaces around the ->. Inside double quotes,
    "...", the first space stops the dereference taking place.
    Outside double quotes the scanner correctly associates the $self
    token with the {'thing'} token.

    I regard this as a bug.

AUTHOR
    `DFA::Command' and `DFA::Generate' were written by Ron Savage
    *<rpsavage@ozemail.com.au>* in 1997.

ACKNOWLEDGEMENTS
    The processing loop at the heart of this module is something I
    downloaded from comp.land.perl.misc circa 1994. I encourage the
    author to contact me.

    You'll know who you are: There were 2 bugs - both harmless - in
    1 line of code, in the routine I call load(). Anybody who
    accepts responsibility for this code will be deemed to be the
    author. Well done!

LICENCE
    This program is free software; you can redistribute it and/or
    modify it under the same terms as Perl itself.

