C<DFA::Command> - A Discrete Finite Automata command processor.

- NAME
- SYNOPSIS
- DESCRIPTION
- INSTALLATION
- FEATURES
- TEST SCRIPTS
- CONFIGURATION OPTIONS
- WARNING
- FORMAT OF A STATE TRANSITION TABLE
- Q & A
- DEREFERENCING GUIDELINES
- PROCESSING of #if `defined()`
- WARNING re Perl bug
- ACKNOWLEDGEMENTS
- AUTHOR
- LICENCE

# 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.

# 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!

# AUTHOR

`DFA::Command` and `DFA::Generate` were written by Ron Savage <ron@savage.net.au> in 1997.

# LICENCE

Australian copyright (c) 1997-2002 Ron Savage.

            All Programs of mine are 'OSI Certified Open Source Software';
            you can redistribute them and/or modify them under the terms of
            The Artistic License, a copy of which is available at:
            http://www.opensource.org/licenses/index.html