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.

cpanm Devel::CallerStack

perl -MCPAN -e shell
install Devel::CallerStack