#
#   Implement a simple stack in terms of a list.
# 

=pod

=head1 Stack 

An object oriented implementation of a Stack data structure.
Stacks are first in last out data structures.

=head1 Member functions:

=cut

package Stack;

=pod

=head2 new  

    Creates a new instance of a stack. 
  
    my $stack = Stack->new();

=cut

sub new {
    my $class = shift;		# Class name.
    my $self  = [];		# Create an empty list to represent the stack.
    bless($self, $class);	# Turn this into an object and..
    return $self;		# Return it.
}

=pod

=head2 push

    takes an item and pushes it onto the back end of the stack.

    my $stack = Stack->new();
    $stack->push(something);

=cut

sub push {
    my $self = shift;		# Gets the list...
    my $item = shift;		# The item to push.
    push(@$self,$item);
}

=pod

=head2 pop

    Returns the item at the top of the stack: does a pop.

    my object = Stack->new();
    my $item = object->pop();

=cut

sub pop {
    my $self = shift;
    return pop(@$self);
}


1;

=pod

=head1 Internal implementation details

Stacks are implemented as lists.  Thus a stack is a thinly disguised
list with push and pop wrappers.  Since PERL is a dynamically typed
language, stacks can contain any data type ... including a
heterogenous collection of types.

=cut