NAME

Attribute::QueueStack - designate an array as a queue or a stack

SYNOPSIS

   my @todo :Queue;
   
   push @todo, qw(foo bar baz);
   shift @todo;
   
   # Naughty! Should only remove things from front of queue!
   pop @todo;

DESCRIPTION

This allows you to designate an array as either a queue or a stack.

Under normal circumstances, it acts as a no-op. In other words, your array is unaffected by the presence of the attributes.

However, if Perl is run with the -w flag, or certain environment variables are set (see ENVIRONMENT below), Attribute::QueueStack suddenly goes into deadly mode, and complains if you try to abuse an array or queue.

Why this state of affairs? Well, this module works via tied arrays. Perl's tie mechanism is pretty slow. So the idea is that you'd want the slow but strict behaviour in your development and testing environment, but are happy to have it switched off for speed in your production environment. (Bugs never occur in your production environment because of your thorough testing process, right?!)

A constant Attribute::QueueStack::ARMED can be used to determine the state of Attribute::QueueStack.

Queues

Queues are first-in-first-out (FIFO). The following operations are allowed on them:

my @queue :Queue

Declare a queue.

push @queue, @items

You can add one or more items to the back of the queue.

shift @queue

You can retrieve the first item from the queue.

$queue[0]

You can peek at the first item in the queue.

scalar(@queue)

You can find the length of the queue.

@queue = ()

You can empty the queue entirely.

Stacks

Stacks are last-in-first-out (LIFO). The following operations are allowed on them:

my @stack :Stack

Declare a stack.

push @stack, @items

You can add one or more items to the top of the stack.

pop @stack

You can retrieve the top item from the stack.

$stack[-1]

You can peek at the last item on the stack.

scalar(@stack)

You can find the height of the stack.

@stack = ()

You can empty the stack entirely.

ENVIRONMENT

Setting any of the following environment variables to a true value will arm this module:

• EXTENDED_TESTING

• RELEASE_TESTING

• AUTHOR_TESTING

• AUTOMATED_TESTING

The variables PERL_QUEUESTACK_LOOSE and PERL_QUEUESTACK_STRICT may also be used as overrides.

BUGS

Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=Attribute-QueueStack.

SEE ALSO

The following modules are used as part of the implementation of Attribute::QueueStack, but can alternatively be used on their own: Tie::Array::Queue, Tie::Array::Stack.

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

This software is copyright (c) 2013 by Toby Inkster.

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

DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

cpanm Attribute::QueueStack

perl -MCPAN -e shell
install Attribute::QueueStack