view release on metacpan or  search on metacpan

lib/Carp/Capture.pm  view on Meta::CPAN

Invoking L<revert()|/revert> restores capture status to
whatever it was before the last push.  Capturing starts out as 'Enabled'.

=head2 disable

 Usage:
    <void> $cc->disable;

B<Carp::Capture> objects maintain an internal stack that controls
whether capturing is performed.  B<disable()> pushes a new 'Disabled'
value on top of the stack.

Invoking L<revert()|/revert> restores capture status to whatever it
was before the last push.  Capturing starts out as 'Enabled'.

=head2 revert

 Usage:
    <void> $cc->revert;

B<Carp::Capture> objects maintain an internal stack that controls
whether capturing is performed.  B<revert()> pops and discards the
current capture status.  The previous status is restored.

=head2 retrieve_annotation

 Usage:
    <Scalar> = $cc->retrieve_annotation( $id );

If an annotation value was provided in the call to
L<capture()|/capture> then it can be retrieved with the
same identifier used to generate stacktraces.

An exception is thrown if I<$id> originated from a capture that was disabled,
or from one in which no annotation was provided.

=head2 uncaptured

 Usage:
    <Integer> = $cc->uncaptured;

The magic value used to indicate that no callstack was captured, is returned
by B<uncaptured()>.  Testing an identifier for equality with the Uncaptured
value is a way to query the identifier's status.

    my $cc = Carp::Capture->new;
    my $uncaptured = $cc->uncaptured;

    # Prints "On"
    say $uncaptured == $cc->capture ? 'Off' : 'On';

    $cc->disable;

    # Prints "Off"
    say $uncaptured == $cc->capture ? 'Off' : 'On';

The Uncaptured value might also be useful as a default in a data structure.
Capturing can be gated with a conditional that overwrites the default when
active.

=head1 BUGS AND LIMITATIONS

Please report any bugs or feature requests to C<bug-carp-capture at
rt.cpan.org>, or through the web interface at

L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Carp-Capture>.

I will be notified, and then you'll automatically be notified of
progress on your bug as I make changes.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Carp::Capture

You can also look for information at:

=over 4

=item * RT: CPAN's request tracker (report bugs here)

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Carp-Capture>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Carp-Capture>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Carp-Capture>

=item * Search CPAN

L<http://search.cpan.org/dist/Carp-Capture/>

=back

=head1 DEPENDENCIES

All of these are available from CPAN:

 Moose
 Carp::Proxy

=head1 SEE ALSO

=over 4

=item *

See 'perldoc -f caller' for information on accessing the current callstack
from Perl.

=item *

See 'perldoc Carp' for documentation on B<confess()>

=back

=head1 LICENSE AND COPYRIGHT