view release on metacpan or  search on metacpan

FlipFlop.pm  view on Meta::CPAN

  my $s = qq[
    sub { 
     &{\$Bit::FlipFlop::stash{"$f"}{set}} 
       $op 
     &{\$Bit::FlipFlop::stash{"$f"}{reset}}
    }
  ];

# debug:
#  print $s;
  eval $s;
}
1;
__END__

=head1 NAME

Bit::FlipFlop - Facilitates the maintainance of one bit of state in Perl
programs.  

=head1 SYNOPSIS

  use Bit::FlipFlop;

  my $f = Bit::FlipFlop->new(set   => sub { /start/ },
                             reset => sub { /end/ });

  for (<INPUT>) {
    $f->test;

    print "**leading edge**\n" if $f->lead_edge;
    print "number ", $f->series, ":  $_" if $f->state;
    print "**trailing edge**\n" if $f->trail_edge;
  }

  # -- or --

  #use Bit::FlipFlop

  my $f;
  for (<INPUT>) {
    $f = /start/ .. /end/;  
    
    print "**lead edge**\n" if $f == 1;
    print "number ", +$f, ":  $_" if $f;
    print "**trailing edge**\n" if $f =~ /E/;
  }
   

=head1 DESCRIPTION

Maintaining one bit of state in a program can be a very useful thing. A
Bit::FlipFlop does just that. The flip flop can be false (represented
by the integer 0) or true (1).

=head2 Overview

The initial state of a flip flop is false.  It has an opportunity
to change state during each call to the C<test> method.  

Two callbacks are provided at flip flop construction time, C<set> and
C<reset>. One or both of these callbacks may be evaluated when the
C<test> method is called. The callbacks are evaluated in scalar context,
and their return value is interpreted as a boolean.

While false, the flip flop evaluates the C<set> callback at each call to
the C<test> method. If the C<set> callback returns a true value, the
flip flop flips state to true. While true, the flip flop evaluates the
C<reset> callback when C<test> is called. If C<reset> returns a true
value, then the flip flop flops back into the false state. 

=head2 Edge Conditions and More

The Bit::FlipFlop actually maintains a few bits more state than just one.

When the flip flop changes from false to true, that is called the leading
edge.  Conversely, when its state falls from true to falls, that is known
as the trailing edge.  Bit::FlipFlop provides methods to test for these
"sub states", C<lead_edge> and C<trail_edge>.

Edges are easily seen when the state of a flip flop is plotted over time:

   true        +-------+        +---+      
               |       |        |   |     
   false  -----+       +--------+   +------
               ^       ^ 
   leading edge         trailing edge
               
Which condition will be tested next?

The C<next_test> method is provided to query the flip flop to see which
condition (C<set> or C<reset>) will be queried on the next call to the
C<test> method.

=head2 Bit::FlipFlop methods

The Bit::FlipFlop class provides an object oriented interface to the
flip flop.  

=over 4

=item C<new>

  $f = Bit::FlipFlop->new(set   => sub {$. == 15},
                          reset => sub {$. == 20},
                          simultaneous_edges => 0);

The C<new> method creates a new Bit::FlipFlop object.  A newly created 
flip flop's state is always false.  

The C<set> and C<reset> arguments are required. They are sub refs that
are used for callbacks to test for setting or resetting the flip flop.

C<simultaneous_edges> is an optional argument that defaults to 1
(true) if unspecified. This argument governs whether the flip flop
may look for a leading edge and trailing edge within a single call to
the C<test> method.  

Normally when a flip flop is in the false state, it tests for the
C<set> condition. Should that condition be true, then the flip flop
will change states to true. There are two possible behaviors at this
point. The flip flop could either evaluate the C<reset> condition to
see if it should switch back to the false state *within the same call
to C<test>*, or it could postpone looking at the C<reset> condition
until the next call to C<test>.

The former behaviour is specified by C<simultaneous_edges=E<gt>1>, 
which is the default behaviour if left unspecified.  To obtain a 
flip flop that will *not* check for both edge conditions within
a single call to C<test>, specify C<simultaneous_edges=E<gt>0>.

=item C<test>

  $f->test;

The C<test> method evaluates one or both conditional tests (according to
the flip flop's state) and determines if the flip flop's state should be
inverted. An alias, C<clock> is provided for circuitry heads.

=item C<state>

  print "It's ", $f->state ? 'true' : 'false', ".\n";

To query the current state of a flip flop, call its C<state> method, which
will return a boolean value (1 for true, 0 for false).

For those just desperate to obsfucate some code, even while using a 
nice, clean OO interface, the boolean state of a flip flop is
also available as C<$$f>.  Don't do this.  In fact, just forget that
you read it.

  # don't you wish that you didn't fire me now?
  # muahahahaha ack plbbf..
  print "It's ", $$f? 'true' : 'false', ".\n";


=item C<series>

The C<series> method returns an integer that tells how many times
the C<test> method has been called since its state has been true.

C<series> will return 1 after the first call to C<test> has flip a
flip flop's state to true, and its return value will be incremented
by one each time that C<test> is called and the state remains true.

A call to C<series> while the flip flop is false will return 0.

=item C<lead_edge>

  print "Just passed the leading edge of truth.\n" 
    if $f->lead_edge;