view release on metacpan or  search on metacpan

lib/FSM.pm  view on Meta::CPAN

package Acme::FSM;
use version 0.77; our $VERSION = version->declare( v2.3.6 );

use Carp qw| croak |;

# TODO:202212202012:whynot: L<|/Linter>

=head1 NAME

Acme::FSM - pseudo Finite State Machine.

=cut

=head1 SYNOPSIS

    my $bb = Acme::FSM->connect( { %options }, { %fst } );
    $bb->process;
    exit 0;

=cut

=head1 DESCRIPTION

B<(disclaimer)>
B<Acme::FSM> is currently in proof-of-concept state.
There's a plan to accompany it with B<Acme::FSM::Simple> with all diagnostics
avoided and run time checks in place.
And then with B<Acme::FSM::Tiny> with run time checks stripped.
Also, see L<B<BUGS AND CAVEATS> later in this POD|/BUGS AND CAVEATS>.

=head2 Concerning Inheritance

Through out code only methods are used to access internal state.
Supposedly, that will enable scaling some day later.
The only exception is L<B<connect()>|/connect()> for obvious reasons.

Through out code neither internal state nor FST records are cached ever.
The only one seamingly inconsistent fragment is inside main loop when next
I<$state> is already found but not yet entered.
I<$action> is processed when the next I<$state> is set
(though, in some sense, not yet entered).
(If it doesn't make sense it's fine, refer to
L<B<process()> method|/process()> description later in this POD.)

This notice seems to be useles.
Instead, it might come handy someday.

=cut

=head2 Terminology

There're some weird loaded words in this POD,
most probably, poorly choosen
(but those are going to stay anyway).
So here comes disambiguation list.

=over

=item I<$action>

Special flag associated with next I<{state}> in a I<[turn]>
(covered in details in L<B<process()>|/process()> method description).
B<(note)> It may be applied to a I<[turn]> of I<{fst}> or I<{state}>.

=item blackboard

Shamelesly stolen from B<DMA::FSM>.
Originally, it meant some opaque HASH passed around in B<DMA::FSM::FSM()>
where
user-code could store it's own ideas and such.
Now it's an object blessed into B<Acme::FSM>
(for user-code still, I<{fsm}> has nothing to do with it).

=item entry

Layout of state records (see below) isn't particularly complicated.
However it's far from being uniform.
I<entry> is a placeholder name for any component of (unspecified) state record
when any semantics is irrelevant.
See also I<[turn]> and B<switch()> below.

=item Finite State Machine

B<Acme::FSM>.

=item Finite State Table

=item I<{fst}>

Collection of state records.

=item FSM

Acronym for I<Finite State Machine>.
See above.

=item FST

Acronym for I<Finite State Table>.
See above.

=item internal state

=item I<{fsm}>

Some open-ended set of parameters dictating FSM's behaviour.

=item item

=item I<$item>

Something that makes sense for user-code.
B<Acme::FSM> treats it as scalar with no internals
(mostly;
one exception is covered in L<B<diag()> method|/diag()> description).

=item I<$namespace>

B<A::F> uses elaborate schema to reach various callbacks
(three of them, at the time of writing).
This optional parameter is in use by this schema.