NAME
    Devel::CallerStack - Object-Oriented call stack and iterator.

DESCRIPION
    Devel-CallerStack is an object-oriented interface to the call stack.
    When constructed it will build a callstack and provide you access and
    filtration methods. Each element of the stack is an instance of
    Devel::CallerStack::Level.

SYNOPSIS
        use Devel::CallerStack qw/caller_stack/;

        my $stack = Devel::CallerStack->new();
        # or
        my $stack = caller_stack();

        # Get all callers
        my @callers = $stack->all_list();

        # Limit to specific callers:
        $stack->filter( 'line', 100 );
        $stack->filter( 'subroutine', qr/mysub$/ );
        $stack->filter( 'package', 'My::Package' );

        my @specific_callers = $stack->filtered_list()

        # As an iterator

        while ( my $level = $stack->next ) {
            ...
        }

        1;

EXPORTS
    Nothing is exported by default. However caller_stack() can be imported.

    $stack = caller_stack()
        Shortcut for Devel::CallerStack->new();

CONSTRUCTOR
    $stack = Devel::CallerStack->new()
        Builds a new caller stack.

OBJECT METHODS
  COMPLETE CALLER STACK
    The following will always return the complete unfiltered caller stack.

    $arrayref = $stack->all()
        Return a reference to the actual array of caller levels. Each item
        will be an instance of Devel::CallerStack::Level.

    @list = $stack->all_list()
        Return a list of caller levels. Each item will be an instance of
        Devel::CallerStack::Level.

  FILTERING RESULTS
    You can apply filters that will remove any levels from the stack that do
    not match given check against it's attributes. You can apply multiple
    filters, each will filter the remaining results from the previous
    filter.

    $stack->filter( $attribute, $check )
    @list = $stack->filter( $attribute, $check )
        Filter the stack so that only levels where the given attribute
        matches the given check will be listed. $attribute should be the
        name of a caller attribute (See Devel::CallerStack::Level). $check
        may be a string against which to compare, a regex, or a coderef.

        NOTE: When called in list context it will return the filtered
        results, but will not modify the object in any way. In any other
        context the filter will be applied to the object itself.

        filter() returns $self in scalar context making the call chainable.

        Filter out any levels where the package is not an instance of
        'Wanted::Package':

            $stack->filter( 'package', sub {
                my $package = shift;
                $package->isa( 'Wanted::Package' );
            });

    $arrayref = $stack->filtered()
        Get a reference to the actual list of callers remaining after
        filters have been applied. Each element is an instance of
        Devel::CallerStack::Level.

    @list = $stack->filtered_list()
        Get a list of callers remaining after filters have been applied.
        Each element is an instance of Devel::CallerStack::Level.

    $bool = $stack->is_filtered()
        Returns true if filters have been applied

    $stack->unfilter()
        Removes all filters. unfilter() returns $self in scalar context
        making the call chainable.

  ELEMENT ACCESS
    $level = $stack->element( $idx )
    $arrayref = $stack->attribute_stack( $attribute )
        Return an arrayref containing $attribute from each stack element.

  ITERATION
    The caller stack is an array of Devel::CallerStack::Level items
    progressing from the most recent caller to the most distant.

    $level = $stack->recent()
        Return the most recent caller.

    $level = $stack->next()
        Returns the next most recent caller, and increments the index.
        Returns undef at the end of the stack.

    $level = $stack->previous()
        The reverse of next, used to go backwords.

    $level = $stack->distant()
        Return the most distant caller.

    $level = $stack->index()
        Returns the index of the iterator

    $stack->reset()
        Resets the iterator to index 0.

  PACKAGE SHORTCUTS
    $level = $stack->recent_package_caller( $package )
        Return the most recent call from the specified package.

    $level = distant_package_caller( $package )
        Return the most distant call from the specified package.

    @list = package_callers( $package )
        Return all the calls from a given package.

FENNEC PROJECT
    This module is part of the Fennec project. See Fennec for more details.
    Fennec is a project to develop an extendable and powerful testing
    framework. Together the tools that make up the Fennec framework provide
    a potent testing environment.

    The tools provided by Fennec are also useful on their own. Sometimes a
    tool created for Fennec is useful outside the greator framework. Such
    tools are turned into their own projects. This is one such project.

    Fennec - The core framework
      The primary Fennec project that ties them all together.

AUTHORS
    Chad Granum exodist7@gmail.com

COPYRIGHT
    Copyright (C) 2010 Chad Granum

    Devel-CallerStack is free software; Standard perl licence.

    Devel-CallerStack is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license for
    more details.

