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.