NAME

Scalar::Cycle::Manual - Cycle through a list of values (with optional automatic incrementation)

SYNOPSIS

    use Scalar::Cycle::Manual ;
        
        my $cyclic_variable = new 'Scalar::Cycle::Manual',  qw( first second third ) ;
        
        print $cyclic_variable; # 'first'
        print $cyclic_variable; # still 'first'
        
        print $cyclic_variable->next ; # 'second'
        print $cyclic_variable; # still 'first'
        
        print $cyclic_variable->previous; #  'third'
        print $cyclic_variable; # still 'first'
        
        print $cyclic_variable->increment;
        print $cyclic_variable; # 'second'
        
        print $cyclic_variable->increment;
        print $cyclic_variable; # 'third'
        
        $cyclic_variable->reset;
        print $cyclic_variable; # first
        
        print $cyclic_variable->decrement;
        print $cyclic_variable; # 'third'
        
        $cyclic_variable++;
        print $cyclic_variable; # 'first'
        
        $cyclic_variable--;
        print $cyclic_variable; # 'third'
        
        $cyclic_variable->auto_increment(1) ;
        print $cyclic_variable; # 'third'
        print $cyclic_variable; # 'first'

DESCRIPTION

There's a bunch of modules implementing a scalar which cycles in a list of values. Take your time to compare them.

If you want more control over when the variable cycles, this module may suit your needs.

DOCUMENTATION

Use Scalar::Cycle::Manual to go through a list over and over again. Once you get to the end of the list, you go back to the beginning.

Overloaded operator

++ and --

These operator act as the increment and decrement subroutines.

0+ and ""

These operators implement the fetching of the current value in scalar and string context.

<>

The '<>' operator returns the current value and increments the current position even if auto_increment is set to 0.

SUBROUTINES/METHODS

new(@value_list)

Creates a Scalar::Cycle::Manual object that you can use to cycle through values.

        use Scalar::Cycle::Manual ;
        
        my $cyclic_variable = new 'Scalar::Cycle::Manual'( qw( first second third )) ;

Arguments

• @value_list - list of values to be cycled through

Return

• a Scalar::Cycle::Manual object

copy_constructor

This is needed by the ++ operator.

auto_increment([$boolean])

When set, the current position in the value list is automatically incremented after the value is accessed.

When a Scalar::Cycle::Manual object is created, auto_increment is set to false.

        my $cyclic_variable = new 'Scalar::Cycle::Manual'( qw( first second third )) ;
        
        print $cyclic_variable; # 'first'
        print $cyclic_variable; # 'first'
        
        $cyclic_variable->auto_increment(1) ;
        
        print $cyclic_variable; # 'second'
        print $cyclic_variable; # 'third'
        
        my $is_auto_increment_on = $cyclic_variable->auto_increment() ;

Arguments

• $boolean- an optional value to set the auto_increment state

Return

• If $bolean is not defined, the current state is returned

as_scalar

Transform the object to the current cycle values. This is automatically called by Perl.

        use Scalar::Cycle::Manual ;
        
        my $cyclic_variable = new 'Scalar::Cycle::Manual'( qw( first second third )) ;
        
        my $value = $cyclic_variable ;
        print $cyclic_variable ;

Return

• the current value extracted from the cycle values.

increment()

Forces the Scalar::Cycle::Manual to change to the next value in the cycle value list.

        use Scalar::Cycle::Manual ;
        
        my $cyclic_variable = new 'Scalar::Cycle::Manual'( qw( first second third )) ;
        
        print $cyclic_variable->increment;
        print $cyclic_variable ;
        
        # or 
        
        print $cyclic_variable->increment;

Return

• the next value, extracted from the cycle values.

decrement()

Forces the Scalar::Cycle::Manual to change to the previous value in the value list.

        print $cyclic_variable->previous;
        print $cyclic_variable ;
        
        # or 
        
        print $cyclic_variable->previous;

Return

• the previous value, extracted from the cycle values.

reset()

Makes the current value the first value in the value list.

        use Scalar::Cycle::Manual ;
        
        my $cyclic_variable = new 'Scalar::Cycle::Manual'( qw( first second third )) ;
        
        $cyclic_variable->auto_increment(1) ;
        print $cyclic_variable; # 'first'
        
        $cyclic_variable->reset ;
        print $cyclic_variable; # 'first'

previous()

Returns the value prior to the value at the current position. This does not affect the current position in the cycle value list.

        use Scalar::Cycle::Manual ;
        
        my $cyclic_variable = new 'Scalar::Cycle::Manual'( qw( first second third )) ;

Return

• the value prior to the value at the current position

next()

Returns the value next to the value at the current position. This does not affect the current position in the value list.

        use Scalar::Cycle::Manual ;
        
        my $cyclic_variable = new 'Scalar::Cycle::Manual'( qw( first second third )) ;

Return

• the value next to the value at the current position

BUGS AND LIMITATIONS

None so far.

AUTHOR

        Khemir Nadim ibn Hamouda
        CPAN ID: NKH
        mailto:nadim@khemir.net

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Scalar::Cycle::Manual

You can also look for information at:

• AnnoCPAN: Annotated CPAN documentation

  http://annocpan.org/dist/Scalar-Cycle-Manual

• RT: CPAN's request tracker

  Please report any bugs or feature requests to L <bug-Scalar-cycle-manual@rt.cpan.org>.

  We will be notified, and then you'll automatically be notified of progress on your bug as we make changes.

• Search CPAN

  http://search.cpan.org/dist/Scalar-Cycle-Manual

SEE ALSO

Scalar-MultiValue

        by Graciliano Monteiro Passos: Create a SCALAR with multiple values.

List-Rotation

        by Imre Saling: Loop (Cycle, Alternate or Toggle) through a list of values via a singleton object implemented as closure.

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.