NAME

Spreadsheet::Edit::Log - log method/function call, args, and return values

SYNOPSIS

  use Spreadsheet::Edit::Log;

  sub public_method {
    my $self = shift;
    $self->_internal_method(@_);
  }
  sub _internal_method {
    my $self = shift;
    my @result = (42, $_[0]*1000);
    log_call \@_, [\"Here you go:", @result] if $self->{verbose};
    @result;
  }
  ...
  $obj->public_method(100);  
  #  file::lineno public_method 100 ==> Here you go:42,100000

DESCRIPTION

(This is generic, no longer specific to Spreadsheet::Edit. Someday it might be published as a stand-alone distribution rather than in Spreadsheet-Edit.)

This provides perhaps-overkill convenience for "verbose logging" and/or debug tracing of subroutein calls.

The resulting message string includes the location of the call to your code, the name of the public function or method called, and a representation of the inputs and outputs.

The "public" function/method name shown is not necessarily the immediate caller of the logging function.

log_call {OPTIONS}, [INPUTS], [RESULTS]

Prints the result of calling fmt_call with the same arguments.

The message is written to STDERR or the file handle given by logdest => FILEHANDLE in OPTIONS.

$msgstring = fmt_call {OPTIONS}, [INPUTS], [RESULTS]

{OPTIONS} and [RESULTS] are optional, i.e. may be omitted.

A message string is composed and returned. The general form is:

  File:linenum funcname input,items,... ==> output,items,...\n
 or
  File:linenum Obj<address>->methname input,items,... ==> output,items,...\n

[INPUTS] and [RESULTS] are each a ref to an array of items or a single non-aref item, which are used to form a comma-separated list.

Each item is formatted like with Data::Dumper, i.e. strings are "quoted" and complex structures serialized; printable Unicode characters are shown as themselves (rather than hex escapes)

... with one exception:

If an item is a reference to a a string then the string is inserted as-is (unquoted), and unless the string is empty, adjacent commas are suppressed.

This allows concatenating arbitrary text to regular values formatted with Data::Dumper.

{OPTIONS}

(See "Default OPTIONS" below to specify statically)

self => objref

If your sub is a method, your can pass self => $self and the called-upon object will be displayed separately before the method name. The object is displayed only for the first call in a series of consecutive calls with the same self value.

fmt_object => CODE

Format a reference to a blessed thing, or the value of the self option, if passed, whether blessed or not.

The sub is called with args ($state, $thing). It should return either $thing or an alternative representation string. By default, the type/classname is shown and an abbreviated address (see addrvis in Data::Dumper::Interp).

$state is a ref to a hash where you can store anything you want; it persists only during the current fmt_call invocation.

is_public_api => CODE

Recognize a public entry-point in the call stack.

The sub is called repeatedly with arguments ($state, [package,file,line,subname,...]).

The second argument contains results from caller(N). Your sub should return True if the frame represents the call to be described in the message.

The default callback is sub{ $_[1][3] =~ /::[a-z][^:]*$/ }, which looks for any sub named with an initial [a-z].

$string = fmt_methcall {OPTIONS}, $self, [INPUTS], [RESULTS]

log_methcall {OPTIONS}, $self, [INPUTS], [RESULTS]

These are short-hands for

   $string = fmt_call {OPTIONS, self => $self}, [INPUTS], [RESULTS]
   log_call {OPTIONS, self => $self}, [INPUTS], [RESULTS]

Usually {OPTIONS} can be omitted, so the short-hand form reduces to log_methcall $self, [INPUTS], [RESULTS].

$frame = nearest_call {OPTIONS};

Locate the call frame for the "public" interface most recently called. This accesses the internal logic used by fmt_call, and uses the same is_public_api callback.

The result is a reference to the items returned by caller(N) which represent the call to be traced.

{OPTIONS} may be omitted.

($filename, $linenum, $subname) = abbrev_call_fn_ln_subname {OPTIONS};

Returns abbreviated information from nearest_call, possibly ambiguous but usually more friendly to humans: $filename is the basename only and $subname omits the Package:: prefix.

Default OPTIONS

You can provide OPTIONS to use by default in

  our %SpreadsheetEdit_Log_Options = (...);

in your package.

AUTHOR / LICENSE

Jim Avera (jim.avera gmail) / Public Domain or CC0

cpanm Spreadsheet::Edit

perl -MCPAN -e shell
install Spreadsheet::Edit