NAME

List::Rotation - Loop (Cycle, Alternate or Toggle) through a list of values via a singleton object implemented as closure.

SYNOPSIS

    use List::Rotation;

    my @array = qw( A B C );

    my $first_cycle  = List::Rotation::Cycle->new(@array);

    print $first_cycle->next;  ## prints A
    print $first_cycle->next;  ## prints B
    print $first_cycle->next;  ## prints C
    print $first_cycle->next;  ## prints A, looping back to beginning
    print $first_cycle->next;  ## prints B
    print $first_cycle->next;  ## prints C

    print $first_cycle->prev;  ## prints B, going back
    print $first_cycle->prev;  ## prints A, going back
    print $first_cycle->prev;  ## prints C, looping forward to last
    print $first_cycle->curr;  ## prints C, at current position

    my $second_cycle = List::Rotation::Cycle->new(@array);  ##  the same object is returned as above
    $first_cycle->reset;       ## reset position
    print $first_cycle->next;  ## prints A
    print $second_cycle->next; ## prints B
    print $first_cycle->next;  ## prints C
    print $second_cycle->next; ## prints A, looping back to beginning

    my $alternation  = List::Rotation::Alternate->new( qw( odd even ) );

    print $alternation->next;  ## prints odd
    print $alternation->next;  ## prints even
    print $alternation->next;  ## prints odd
    $alternation->reset;       ## reset the alternation to first item
    print $alternation->next;  ## prints odd

    my $switch  = List::Rotation::Toggle->new;

    ##  prints even numbers between 2 and 10
    foreach ( 2..10 ) {
        print "$_\n" if $switch->next;
    }

DESCRIPTION

Use List::Rotation to loop through a list of values. Once you get to the end of the list, you go back to the beginning. Alternatively you can walk backwards through your list of values.

List::Rotation is implemented as a Singleton Pattern. You always just get 1 (the very same) Rotation object if you use the new method several times with the exact same set of parameters. This is done by using Memoize on the new method. It returns the same object for every use of new that comes with the same list of parameters.

The class List::Rotation contains three subclasses:

List::Rotation::Cycle: Loop through a list of arbitrary values. The list must not be empty.
List::Rotation::Alternate: Alternate two values.
List::Rotation::Toggle: Toggle between true and false.

OBJECT METHODS

new: Create a Cycle object for the list of values in the list.
next: Return the next element.
prev: Return the previous element.
curr: Return the element at the current position.
reset: Reset the list to the beginning; the following call of next will return the first item of the list again.

References

There are several similar modules available:

Tie::FlipFlop: by Abigail: Alternate between two values.
List::Cycle: by Andi Lester: Objects for cycling through a list of values
Tie::Cycle: by Brian D. Foy: Cycle through a list of values via a scalar.
Tie::Toggle: by Brian D. Foy: False and true, alternately, ad infinitum.

AUTHOR

Imre Saling, <pelagicatcpandotorg>

COPYRIGHT and LICENSE

This software is available under the same terms as perl.