.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Data::Dump::Trace 3"
.TH Data::Dump::Trace 3 2024-09-01 "perl v5.40.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Data::Dump::Trace \- Helpers to trace function and method calls
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Data::Dump::Trace qw(autowrap mcall);
\&
\&  autowrap("LWP::UserAgent" => "ua", "HTTP::Response" => "res");
\&
\&  use LWP::UserAgent;
\&  $ua = mcall(LWP::UserAgent => "new");      # instead of LWP::UserAgent\->new;
\&  $ua\->get("http://www.example.com")\->dump;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The following functions are provided:
.ie n .IP "autowrap( $class )" 4
.el .IP "autowrap( \f(CW$class\fR )" 4
.IX Item "autowrap( $class )"
.PD 0
.ie n .IP "autowrap( $class => $prefix )" 4
.el .IP "autowrap( \f(CW$class\fR => \f(CW$prefix\fR )" 4
.IX Item "autowrap( $class => $prefix )"
.ie n .IP "autowrap( $class1 => $prefix1,  $class2 => $prefix2, ... )" 4
.el .IP "autowrap( \f(CW$class1\fR => \f(CW$prefix1\fR,  \f(CW$class2\fR => \f(CW$prefix2\fR, ... )" 4
.IX Item "autowrap( $class1 => $prefix1, $class2 => $prefix2, ... )"
.ie n .IP "autowrap( $class1 => \e%info1, $class2 => \e%info2, ... )" 4
.el .IP "autowrap( \f(CW$class1\fR => \e%info1, \f(CW$class2\fR => \e%info2, ... )" 4
.IX Item "autowrap( $class1 => %info1, $class2 => %info2, ... )"
.PD
Register classes whose objects are automatically wrapped when
returned by one of the call functions below.  If \f(CW$prefix\fR is provided
it will be used as to name the objects.
.Sp
Alternative is to pass an \f(CW%info\fR hash for each class.  The recognized keys are:
.RS 4
.ie n .IP "prefix => $string" 4
.el .IP "prefix => \f(CW$string\fR" 4
.IX Item "prefix => $string"
The prefix string used to name objects of this type.
.IP "proto => \e%hash" 4
.IX Item "proto => %hash"
A hash of prototypes to use for the methods when an object is wrapped.
.RE
.RS 4
.RE
.ie n .IP "wrap( name => $str, func => \e&func, proto => $proto )" 4
.el .IP "wrap( name => \f(CW$str\fR, func => \e&func, proto => \f(CW$proto\fR )" 4
.IX Item "wrap( name => $str, func => &func, proto => $proto )"
.PD 0
.ie n .IP "wrap( name => $str, obj => $obj, proto => \e%hash )" 4
.el .IP "wrap( name => \f(CW$str\fR, obj => \f(CW$obj\fR, proto => \e%hash )" 4
.IX Item "wrap( name => $str, obj => $obj, proto => %hash )"
.PD
Returns a wrapped function or object.  When a wrapped function is
invoked then a trace is printed after the underlying function has returned.
When a method on a wrapped object is invoked then a trace is printed
after the methods on the underlying objects has returned.
.Sp
See "Prototypes" for description of the \f(CW\*(C`proto\*(C'\fR argument.
.ie n .IP "call( $name, \e&func, $proto, @ARGS )" 4
.el .IP "call( \f(CW$name\fR, \e&func, \f(CW$proto\fR, \f(CW@ARGS\fR )" 4
.IX Item "call( $name, &func, $proto, @ARGS )"
Calls the given function with the given arguments.  The trace will use
\&\f(CW$name\fR as the name of the function.
.Sp
See "Prototypes" for description of the \f(CW$proto\fR argument.
.ie n .IP "mcall( $class, $method, $proto, @ARGS )" 4
.el .IP "mcall( \f(CW$class\fR, \f(CW$method\fR, \f(CW$proto\fR, \f(CW@ARGS\fR )" 4
.IX Item "mcall( $class, $method, $proto, @ARGS )"
.PD 0
.ie n .IP "mcall( $object, $method, $proto, @ARGS )" 4
.el .IP "mcall( \f(CW$object\fR, \f(CW$method\fR, \f(CW$proto\fR, \f(CW@ARGS\fR )" 4
.IX Item "mcall( $object, $method, $proto, @ARGS )"
.PD
Calls the given method with the given arguments.
.Sp
See "Prototypes" for description of the \f(CW$proto\fR argument.
.ie n .IP "trace( $symbol, $prototype )" 4
.el .IP "trace( \f(CW$symbol\fR, \f(CW$prototype\fR )" 4
.IX Item "trace( $symbol, $prototype )"
Replaces the function given by \f(CW$symbol\fR with a wrapped function.
.SS Prototypes
.IX Subsection "Prototypes"
\&\fBNote: The prototype string syntax described here is experimental and
likely to change in revisions of this interface\fR.
.PP
The \f(CW$proto\fR argument to \fBcall()\fR and \fBmcall()\fR can optionally provide a
prototype for the function call.  This give the tracer hints about how
to best format the argument lists and if there are \fIin/out\fR or \fIout\fR
arguments.  The general form for the prototype string is:
.PP
.Vb 1
\&   <arguments> = <return_value>
.Ve
.PP
The default prototype is "@ = @"; list of values as input and list of
values as output.
.PP
The value '%' can be used for both arguments and return value to say
that key/value pair style lists are used.
.PP
Alternatively, individual positional arguments can be listed each
represented by a letter:
.ie n .IP """i""" 4
.el .IP \f(CWi\fR 4
.IX Item "i"
input argument
.ie n .IP """o""" 4
.el .IP \f(CWo\fR 4
.IX Item "o"
output argument
.ie n .IP """O""" 4
.el .IP \f(CWO\fR 4
.IX Item "O"
both input and output argument
.PP
If the return value prototype has \f(CW\*(C`!\*(C'\fR appended, then it signals that
this function sets errno ($!) when it returns a false value.  The
trace will display the current value of errno in that case.
.PP
If the return value prototype looks like a variable name (with \f(CW\*(C`$\*(C'\fR
prefix), and the function returns a blessed object, then the variable
name will be used as prefix and the returned object automatically
traced.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Data::Dump