The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Util-Underscore-v1.4.2
River stage zero No dependents
2 ++
/ Util::Underscore::CallStackFrame

NAME

Util::Underscore::CallStackFrame - object-oriented wrapper for "caller" builtin

VERSION

version v1.4.2

SYNOPSIS

    (caller(4))[3];
    # is equivalent to
    Util::Underscore::CallStackFrame->of(4)->subroutine;

DESCRIPTION

This is a wrapper class for the caller builtin, to allow access to the fields by name. See the caller documentation for more details.

METHODS

of($level)

This class method is a factory method. It returns an object-oriented view on the caller builtin.

$level: An integer indicating the call stack frame level to return. A level of zero indicates the current level (from the perspective of an immediate user of this class). Negative values are illegal.

returns: A Util::Underscore::CallStackFrame instance for the requested stack frame. If no such level exists, undef is returned.

package

The package from which the function was called.

    package Foo;
    
    Bar::baz() eq __PACKAGE__ or die;
    
    package Bar;
    
    sub baz {
        return Util::Underscore::CallStackFrame->of(0)->package;
    }

returns: This stack frame's package name, as a string.

file

The file name where the function was called.

returns: The file name, as a string.

line

The line where the function was called. Note that this isn't necessarily the exact line, but sometimes the line where the current statement ended.

returns: The line number, as an integer.

subroutine

The fully qualified name of the subroutine that was called in this stack frame. There are a couple of special values:

  • The last part of the fully qualified name is __ANON__ when the sub never had a name, i.e. is an anonymous subroutine.

  • The whole name is (eval) when this frame was generated from the eval builtin, rather than from an ordinary function call. Instead of matching against this name, one can use the is_eval accessor below,

  • The whole name is (unknown) when a subroutine was named, but the typeglob where the subroutine was stored was deleted. I have never encountered this behaviour.

return: The fully qualified name of the called subroutine, as a string.

has_args

Checks whether the function call set up a new instance of @_. It does not check whether any arguments where passed at all.

In which cases is has_args false?

  • The stack frame was generated for an eval, rather than for a function call.

  • The function call re-used the existing @_, which happens when calling a function like &func rather than &func() or func(). This is a fairly obscure feature, but is sometimes encountered when doing an explicit tail call such as goto &func.

If args were passed, an array ref to a copy of @_ is returned. This means that arguments loose their referential identity. This uses the @DB::args mechanism (see the caller docs for more details), which means these values may not be up to date.

returns: A false value if no new @_ instance was created in this stack frame. Otherwise, a true value is returned, which is an arrayref containing the arguments with which the subroutine was called.

wantarray

The context in which that function was called. See the wantarray documentation for more details.

The values are true for list context, false but defined for scalar context, and undefined for void context.

return: an indicator for that stack frame's context.

is_eval

Checks whether this stack frame was generated by an eval construct. If so, this returns another accessor object with two attributes.

returns: a false value if this frame was generated by an ordinary subroutine call. If it was created by an eval, then it returns an accessor object (which is also a true-ish value).

The fields of the accessor object are:

source

If that stack frame was generated by a string-eval and not a block-eval, then this field contains the source code that was eval'd.

returns: undef or the source of the eval, if available.

is_require

Indicates whether this eval is actually a use or require.

returns: a boolean value.

is_require

Indicates whether this eval is actually a use or require.

returns: a boolean value.

hints

The $^H under which the caller was compiled. This value is for perl's internal use only.

returns: The caller's $^H.

bitmask

The %{^WARNING_BITS} under which the caller was compiled. This value is for perl's internal use only.

returns_ The caller's ${^WARNING_BITS}.

The %^H hint hash under which the caller was compiled. This hash offers storage for pragmas during compilation. In the context of stack traces, this should be treated as a read-only value.

returns: The caller's %^H, or undef if it was empty.

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/latk/p5-Util-Underscore/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

Lukas Atkinson (cpan: AMON) <amon@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Lukas Atkinson.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.