Devel::CallerItem - An object representing a function call from the stack of function calls.
Usage:
require Devel::CallerItem; $call = Devel::CallerItem->from_depth($depth) || return; $passed_arguments_ref = $call->argument_list_ref(); $callpack = $call->pack(); $callfile = $call->file(); $callline = $call->line(); $callsub = $call->subroutine(); $bool = $call->has_args(); $bool = $call->wants_array(); ($arg_ref,@caller) = $call->as_array(); $call_string = $call->as_string($print_level); $passed_arguments_string = $call->arguments_as_string(); $printable_arg = Devel::CallerItem->printable_arg($arg,$print_level);
Devel::CallerItem objects hold all the information about a specific function call on the stack. The information is basically that obtained from caller and @DB::args, packaged into an object. This comes with some useful methods to print the object in a nice way.
This method is the constructor for the class. DEPTH is a number, corresponding to the stack level as used by caller. The following two calls are equivalent in terms of what gets put into '@caller'
@caller = caller($DEPTH); ($arg_ref,@caller) = Devel::CallerItem->from_depth($DEPTH)->as_array();
Returns a reference to an array holding the elements actually passed to the function on the stack that makes up the function call.
If the function was called as '&func;', then this array is not empty, it holds the array that was passed down to the function 'func'.
The package from which the function was called.
The file from which the function was called.
The line from which the function was called.
The fully qualified package name of the function that was called.
Boolean indicating whether the function was called with arguments.
Boolean indicating the context in which the function was called.
Equivalent to the following:
($call->argument_list_ref(),$call->pack(),$call->file(), $call->line(),$call->subroutine(),$call->has_args(), $call->wants_array());
Returns the object in string format suitable for printing a fully informative message about the function call. Looks like one of the following:
$ = func(args) called from FILE line LINE; $ = &func called from FILE line LINE; @ = func(args) called from FILE line LINE; @ = &func called from FILE line LINE;
giving the context (scalar - $, array - @) and whether it was called with arguments or without (&). PRINT_LEVEL determines the level of detail printed about the arguments to the function - see 'printable_arg' below.
Returns a string representing the arguments held in the argument_list_ref. Equivalent to calling 'printable_arg' for each argument and joining them with commas.
Renders ARG printable. PRINT_LEVEL affects the detail of what is printed. There are three levels, 0 or 1 or 2. (Currently anything other than these values is treated as a '2', but this is an unsupported feature an is likely to change if any further levels are added - so use 0/1/2 to be safe.)
Level 0 makes strings printable, but scalars which return refs are just stringified - i.e. an argument which is like [33,{'g' => 55}] would just appear as something like 'ARRAY(0x9882c)'. This is the default.
At level 1, an argument which is like [33,{'g' => 55}] would be fully expanded to '[33,{'g' => 55}]', but any scalar which is repeated in the arguments is just stringified to something like 'ARRAY(0x9882c)'. i.e. if you had '$a = bless [],A;$b =[$a];$a->[0]=$b;', which is a recursive object, then '$a' would be printed as '[[A=ARRAY(0x83038)]]'.
Finally, at the highest level, arguments are printed with an associated variable and bless statement if needed - so with '$a' above you would get $a printed as: '($v1 = bless [($v2 = [$v1])], A)'. NOTE that this does not actually rebuild '$a' in perl code - perl parses this as having $v1 empty in internal array - it is only assigned to after the outer anonymous array is built. This nomenclature is used purely to make explicit any recursive or multiply passed arguments - this sort of level of detail is needed on occasion, but there is a clear cost in clarity.
NOTE that the format of the printed out items that depends on the PRINT_LEVEL is likely to change in future versions when a standardized module for printing variables comes out.
The following is a simple example, illustrating the three levels of detail available using the print_level settings, and can be executed using perl -x Devel/CallerItem.pm
perl -x Devel/CallerItem.pm
#!perl
require Devel::CallerItem; $a="pp"; $c = bless [], A; $d = [$c]; $c->[0] = $d; sub level0 { print Devel::CallerItem->from_depth(0)->as_string(0),"\n" } sub level1 { print Devel::CallerItem->from_depth(0)->as_string(1),"\n" } sub level2 { print Devel::CallerItem->from_depth(0)->as_string(2),"\n" } level0('hi',21,[44,[66,{"q","hi"},\$a],$c]); level1('hi',21,[44,[66,{"q","hi"},\$a],$c]); level2('hi',21,[44,[66,{"q","hi"},\$a],$c]);
__END__
Jack Shirazi (though the difficult bits were taken from sigtrap)
Copyright (c) 1995 Jack Shirazi. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Version 1.0, 31st July - JS
To install Devel::CallerItem, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Devel::CallerItem
CPAN shell
perl -MCPAN -e shell install Devel::CallerItem
For more information on module installation, please visit the detailed CPAN module installation guide.