--- name: "Bio::Tools::StateMachine::AbstractStateMachine" section: "3pm" platform: "linux" package: "bioperl" version: "1.0-1" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/Bio::Tools::StateMachine::AbstractStateMachine" --- # Bio::Tools::StateMachine::AbstractStateMachine(3pm) Bio::Tools::StateMachine::AbstractStateMachine - Abstract state machine object Here is a portion of an implementation. For the full example, see examples/state-machine/state-machine.pl in the Bioperl distribution. ``` package SimpleStateMachine; ``` ``` use Bio::Root::Root; use Bio::Tools::StateMachine::AbstractStateMachine qw($INITIAL_STATE $FINAL_STATE); use vars qw( @ISA ); ``` ``` @ISA = qw( Bio::Root::Root Bio::Tools::StateMachine::AbstractStateMachine ); ``` ``` my @state_transitions = ( [ $INITIAL_STATE, 'State1'], [ 'State1', 'State2' ], [ 'State2', $FINAL_STATE] ); sub new { my($caller,@args) = @_; my $self = $caller->SUPER::new( @args); $self->_init_state_machine( -transition_table => \@state_transitions ); return $self; } ``` **AbstractStateMachine** provides a generic framework for representing a state machine. This is not an event-based framework where you register handlers to be called when certain events occur. Instead, it provides a set of methods that define the basic logic of an object that has state behavior, that logic being: A **state** is just a string representing the name of the state. A state machine is initialized with a **state transition table** consisting of a set of allowable transitions, where each **transition** is a two-element array in which the first element is the **from** **state**, and the second element is the **to state**. This table permits the AbstractStateMachine to determine if a requested transition is valid. This module is flexible enough to represent both deterministic and non-deterministic finite automata (DFAs and NFAs), but it is fairly new and should be considered experimental. The key methods in AbstractStateMachine that define this logic of operation are: Does whatever checking is necessary to determine if a state transition should occur (for example, read a line of input from STDIN). If a transition should occur, a string is returned containing the name of the new state. Otherwise, it returns `"undef"`. This method **must be implemented** as AbstractStateMachine does not define it (and in fact will throw a NotImplemented exception if you fail to implement it). Causes the machine to change its state to the state specified in the argument. *change\_state()* allows you to mapping a state transition to a particular handler method that does whatever processing is needed to deal with the state transition. This method keeps calling *check\_for\_new\_state()* and if that method returns a defined value (the name of the state to change to), it then calls change\_state( `$state` ), where `$state` is the value returned by *check\_for\_new\_state()*. Before calling *check\_for\_new\_state()*, the *run()* method checks the current state of the machine and exits the loop if the current state ever becomes `$PAUSE_STATE`, `$ERROR_STATE`, or `$FINAL_STATE`. Adds data to a buffer for processing at the next state transition. *check\_for\_new\_state()* should call *append\_input\_cache()* passing it any data it receives while checking for a new state that should be processed later. Retrieves the data stored by calling *append\_input\_cache()*. *change\_state()* should call *get\_input\_cache()* to obtain the data to be processed for the current transition. This object defines an abstract class, meaning that some but not all methods have been implemented. Subclasses must define the methods not implemented here. These include at a minimum: A default simple implementation of *change\_state()* is provided, but subclasses of AbstractStateMachine most likely will want to override this method to do something useful according to the particular state change. If your state machine needs to cache input while processing, you will also need to provide implementations of these methods (which are no-op in AbstractStateMachine): There are some other nuances provided by AbstractStateMachine, such as the ability to *pause()* and *resume()* the running of the machine. To get a feel for how to use this, have look at scripts in the examples/state-machine directory of the Bioperl distribution. Also have a look at Bio::Tools::StateMachine::IOStateMachine which provides a Bio::Root::IO-based implementation of AbstractStateMachine. Bio::SearchIO::psiblast subclasses IOStateMachine.\ **Mailing Lists** User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to one of the Bioperl mailing lists. Your participation is much appreciated. ``` bioperl-l@bioperl.org - General discussion http://bio.perl.org/MailList.html - About the mailing lists ``` **Reporting Bugs** Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their resolution. Bug reports can be submitted via email or the web: ``` bioperl-bugs@bio.perl.org http://bio.perl.org/bioperl-bugs/ ``` Steve Chervitz, \ See the FEEDBACK section for where to send bug reports and comments. I would like to acknowledge my colleagues at Affymetrix for useful feedback. Copyright (c) 2001 Steve Chervitz. All Rights Reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. This software is provided "as is" without warranty of any kind. The rest of the documentation details each of the object methods. Internal methods are usually preceded with a \_\ **running** The machine is either running or not running. Once the machine has stopped running, it cannot be re-started. Use *pause()* to temporarily halt a machine without exiting the run state.\ **transition\_table** ``` Arg : n/a Returns : An array of array references to two-element arrays. Each array ref defines a single transition where the first element is the name of the "from" state and the second element is the name of the "to" state. ``` ``` Example : $sm->transition_table( [ $INITIAL_STATE, 'State1'], [ 'State1', 'State2' ], [ 'State2', 'State3' ], [ 'State3', $FINAL_STATE] ); ``` **add\_transition** ``` Arg : Two string arguments where: First string = name of the "from" state. Second string = name of the "to" state. Throws : A Bio::Root::BadParameter exception if two arguments are not provided. ``` **change\_state** ``` Purpose : To cause the machine to change its state. Argument : A String containing the name of the the new state. Returns : n/a Throws : A Bio::Tools::StateMachine::StateException exception if the state transition cannot be carried out. ``` This is a default implementation that simply validates the state change (by calling validate\_transition) and then calls *finalize\_state\_change()* if the transition is valid. Subclasses of AbstractStateMachine most likely will want to override this method to do something useful according to the particular state change.\ **get\_transitions\_from** ``` Purpose : Returns a list array references that have the indicated state in their 'from' slot. ``` **validate\_transition** ``` Purpose : Determines if the desired state change is defined within the set of registered transitions for this StateMachine. Arg : Two required arguments: [0] string defining the name of the "from" state (case sensitive) [1] string defining the name of the "to" state (case sensitive) Returns : True if the transition is valid. If not valid, throws an exception. Throws : A Bio::Tools::StateMachine::StateException if the desired transition does not exist with the registered transitions for this machine. Throws : A Bio::Root::BadParameter if insufficient arguments are given. ``` **check\_for\_new\_state** ``` Purpose : To do whatever checking is necessary to determine if a state transition should occur. Argument : Any necessary data required to determine if the state machine should change to a new state. Returns : A string containing the name of the new state if the state machine should change to a new state. Otherwise returns undef. ``` This is a virtual method and must be implemented by a subclass to do whatever checking is necessary to determine if a state transition should occur. If not implemented, calling this method will result in a Bio::Root::NotImplemented exception.\ **finalize\_state\_change** ``` Purpose : Performs routine operations to finish changing state. This method should be called at the end of change_state(). Usage : finalize_state_change( $new_state, $clear_input_cache ); Argument : $new_state = the name of the state to change to. $clear_input_cache = boolean whether or not to zap whatever was in the input cache. Depends on the logic of your state machine. ```