1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. | will give a
29 .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
131 .IX Title "Data::Dump::Trace 3"
132 .TH Data::Dump::Trace 3 "2009-03-06" "perl v5.8.7" "User Contributed Perl Documentation"
134 Data::Dump::Trace \- Helpers to trace function and method calls
136 .IX Header "SYNOPSIS"
138 \& use Data::Dump::Trace qw(autowrap mcall);
142 \& autowrap("LWP::UserAgent" => "ua", "HTTP::Response" => "res");
146 \& use LWP::UserAgent;
147 \& $ua = mcall(LWP::UserAgent => "new"); # instead of LWP::UserAgent\->new;
148 \& $ua\->get("http://www.example.com")\->dump;
151 .IX Header "DESCRIPTION"
152 The following functions are provided:
153 .ie n .IP "autowrap( $class )" 4
154 .el .IP "autowrap( \f(CW$class\fR )" 4
155 .IX Item "autowrap( $class )"
157 .ie n .IP "autowrap( $class\fR => \f(CW$prefix )" 4
158 .el .IP "autowrap( \f(CW$class\fR => \f(CW$prefix\fR )" 4
159 .IX Item "autowrap( $class => $prefix )"
160 .ie n .IP "autowrap( $class1\fR => \f(CW$prefix1\fR, \f(CW$class2\fR => \f(CW$prefix2, ... )" 4
161 .el .IP "autowrap( \f(CW$class1\fR => \f(CW$prefix1\fR, \f(CW$class2\fR => \f(CW$prefix2\fR, ... )" 4
162 .IX Item "autowrap( $class1 => $prefix1, $class2 => $prefix2, ... )"
163 .ie n .IP "autowrap( $class1\fR => \e%info1, \f(CW$class2 => \e%info2, ... )" 4
164 .el .IP "autowrap( \f(CW$class1\fR => \e%info1, \f(CW$class2\fR => \e%info2, ... )" 4
165 .IX Item "autowrap( $class1 => %info1, $class2 => %info2, ... )"
167 Register classes whose objects are are automatically wrapped when
168 returned by one of the call functions below. If \f(CW$prefix\fR is provided
169 it will be used as to name the objects.
171 Alternative is to pass an \f(CW%info\fR hash for each class. The recognized keys are:
173 .ie n .IP "prefix => $string" 4
174 .el .IP "prefix => \f(CW$string\fR" 4
175 .IX Item "prefix => $string"
176 The prefix string used to name objects of this type.
177 .IP "proto => \e%hash" 4
178 .IX Item "proto => %hash"
179 A hash of prototypes to use for the methods when an object is wrapped.
183 .ie n .IP "wrap( name => $str\fR, func => \e&func, proto => \f(CW$proto )" 4
184 .el .IP "wrap( name => \f(CW$str\fR, func => \e&func, proto => \f(CW$proto\fR )" 4
185 .IX Item "wrap( name => $str, func => &func, proto => $proto )"
187 .ie n .IP "wrap( name => $str\fR, obj => \f(CW$obj, proto => \e%hash )" 4
188 .el .IP "wrap( name => \f(CW$str\fR, obj => \f(CW$obj\fR, proto => \e%hash )" 4
189 .IX Item "wrap( name => $str, obj => $obj, proto => %hash )"
191 Returns a wrapped function or object. When a wrapped function is
192 invoked then a trace is printed after the underlying function has returned.
193 When a method on a wrapped object is invoked then a trace is printed
194 after the methods on the underlying objects has returned.
196 See \*(L"Prototypes\*(R" for description of the \f(CW\*(C`proto\*(C'\fR argument.
197 .ie n .IP "call( $name\fR, \e&func, \f(CW$proto\fR, \f(CW@ARGS )" 4
198 .el .IP "call( \f(CW$name\fR, \e&func, \f(CW$proto\fR, \f(CW@ARGS\fR )" 4
199 .IX Item "call( $name, &func, $proto, @ARGS )"
200 Calls the given function with the given arguments. The trace will use
201 \&\f(CW$name\fR as the name of the function.
203 See \*(L"Prototypes\*(R" for description of the \f(CW$proto\fR argument.
204 .ie n .IP "mcall( $class\fR, \f(CW$method\fR, \f(CW$proto\fR, \f(CW@ARGS )" 4
205 .el .IP "mcall( \f(CW$class\fR, \f(CW$method\fR, \f(CW$proto\fR, \f(CW@ARGS\fR )" 4
206 .IX Item "mcall( $class, $method, $proto, @ARGS )"
208 .ie n .IP "mcall( $object\fR, \f(CW$method\fR, \f(CW$proto\fR, \f(CW@ARGS )" 4
209 .el .IP "mcall( \f(CW$object\fR, \f(CW$method\fR, \f(CW$proto\fR, \f(CW@ARGS\fR )" 4
210 .IX Item "mcall( $object, $method, $proto, @ARGS )"
212 Calls the given method with the given arguments.
214 See \*(L"Prototypes\*(R" for description of the \f(CW$proto\fR argument.
215 .ie n .IP "trace( $symbol\fR, \f(CW$prototype )" 4
216 .el .IP "trace( \f(CW$symbol\fR, \f(CW$prototype\fR )" 4
217 .IX Item "trace( $symbol, $prototype )"
218 Replaces the function given by \f(CW$symbol\fR with a wrapped function.
220 .IX Subsection "Prototypes"
221 \&\fBNote: The prototype string syntax described here is experimental and
222 likely to change in revisions of this interface\fR.
224 The \f(CW$proto\fR argument to \fIcall()\fR and \fImcall()\fR can optionally provide a
225 prototype for the function call. This give the tracer hints about how
226 to best format the argument lists and if there are \fIin/out\fR or \fIout\fR
227 arguments. The general form for the prototype string is:
230 \& <arguments> = <return_value>
233 The default prototype is \*(L"@ = @\*(R"; list of values as input and list of
236 The value '%' can be used for both arguments and return value to say
237 that key/value pair style lists are used.
239 Alternatively, individual positional arguments can be listed each
240 represented by a letter:
242 .el .IP "\f(CWi\fR" 4
246 .el .IP "\f(CWo\fR" 4
250 .el .IP "\f(CWO\fR" 4
252 both input and output argument
254 If the return value prototype has \f(CW\*(C`!\*(C'\fR appended, then it signals that
255 this function sets errno ($!) when it returns a false value. The
256 trace will display the current value of errno in that case.
258 If the return value prototype looks like a variable name (with \f(CW\*(C`$\*(C'\fR
259 prefix), and the function returns a blessed object, then the variable
260 name will be used as prefix and the returned object automatically
263 .IX Header "SEE ALSO"
267 Copyright 2009 Gisle Aas.
269 This library is free software; you can redistribute it and/or
270 modify it under the same terms as Perl itself.