local-lib5/man/man3/Data::Visitor::Callback.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  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<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  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
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  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.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  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
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  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'
 101 .\}
 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 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Data::Visitor::Callback 3"
 132 .TH Data::Visitor::Callback 3 "2009-08-14" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Data::Visitor::Callback \- A Data::Visitor with callbacks.
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&        use Data::Visitor::Callback;
 139 .Ve
 140 .PP
 141 .Vb 5
 142 \&        my $v = Data::Visitor::Callback\->new(
 143 \&                value => sub { ... },
 144 \&                array => sub { ... },
 145 \&                object => "visit_ref", # can also use method names
 146 \&        );
 147 .Ve
 148 .PP
 149 .Vb 1
 150 \&        $v\->visit( $some_perl_value );
 151 .Ve
 152 .SH "DESCRIPTION"
 153 .IX Header "DESCRIPTION"
 154 This is a Data::Visitor subclass that lets you invoke callbacks instead of
 155 needing to subclass yourself.
 156 .SH "METHODS"
 157 .IX Header "METHODS"
 158 .ie n .IP "new %opts\fR, \f(CW%callbacks" 4
 159 .el .IP "new \f(CW%opts\fR, \f(CW%callbacks\fR" 4
 160 .IX Item "new %opts, %callbacks"
 161 Construct a new visitor.
 162 .Sp
 163 The options supported are:
 164 .RS 4
 165 .IP "ignore_return_values" 4
 166 .IX Item "ignore_return_values"
 167 When this is true (off by default) the return values from the callbacks are
 168 ignored, thus disabling the fmapping behavior as documented in
 169 Data::Visitor.
 170 .Sp
 171 This is useful when you want to modify \f(CW$_\fR directly
 172 .IP "tied_as_objects" 4
 173 .IX Item "tied_as_objects"
 174 Whether ot not to visit the \*(L"tied\*(R" in perlfunc of a tied structure instead of
 175 pretending the structure is just a normal one.
 176 .Sp
 177 See \*(L"visit_tied\*(R" in Data::Visitor.
 178 .RE
 179 .RS 4
 180 .RE
 181 .SH "CALLBACKS"
 182 .IX Header "CALLBACKS"
 183 Use these keys for the corresponding callbacks.
 184 .PP
 185 The callback is in the form:
 186 .PP
 187 .Vb 2
 188 \&        sub {
 189 \&                my ( $visitor, $data ) = @_;
 190 .Ve
 191 .PP
 192 .Vb 1
 193 \&                # or you can use $_, it's aliased
 194 .Ve
 195 .PP
 196 .Vb 2
 197 \&                return $data; # or modified data
 198 \&        }
 199 .Ve
 200 .PP
 201 Within the callback \f(CW$_\fR is aliased to the data, and this is also passed in the
 202 parameter list.
 203 .PP
 204 Any method can also be used as a callback:
 205 .PP
 206 .Vb 1
 207 \&        object => "visit_ref", # visit objects anyway
 208 .Ve
 209 .IP "visit" 4
 210 .IX Item "visit"
 211 Called for all values
 212 .IP "value" 4
 213 .IX Item "value"
 214 Called for non objects, non container (hash, array, glob or scalar ref) values.
 215 .IP "ref_value" 4
 216 .IX Item "ref_value"
 217 Called after \f(CW\*(C`value\*(C'\fR, for references to regexes, globs and code.
 218 .IP "plain_value" 4
 219 .IX Item "plain_value"
 220 Called after \f(CW\*(C`value\*(C'\fR for non references.
 221 .IP "object" 4
 222 .IX Item "object"
 223 Called for blessed objects.
 224 .Sp
 225 Since \*(L"visit_object\*(R" in Data::Visitor will not recurse downwards unless you
 226 delegate to \f(CW\*(C`visit_ref\*(C'\fR, you can specify \f(CW\*(C`visit_ref\*(C'\fR as the callback for
 227 \&\f(CW\*(C`object\*(C'\fR in order to enter objects.
 228 .Sp
 229 It is reccomended that you specify the classes (or base classes) you want
 230 though, instead of just visiting any object forcefully.
 231 .IP "Some::Class" 4
 232 .IX Item "Some::Class"
 233 You can use any class name as a callback. This is colled only after the
 234 \&\f(CW\*(C`object\*(C'\fR callback.
 235 .Sp
 236 If the object \f(CW\*(C`isa\*(C'\fR the class then the callback will fire.
 237 .Sp
 238 These callbacks are called from least derived to most derived by comparing the
 239 classes' \f(CW\*(C`isa\*(C'\fR at construction time.
 240 .IP "object_no_class" 4
 241 .IX Item "object_no_class"
 242 Called for every object that did not have a class callback.
 243 .IP "object_final" 4
 244 .IX Item "object_final"
 245 The last callback called for objects, useful if you want to post process the
 246 output of any class callbacks.
 247 .IP "array" 4
 248 .IX Item "array"
 249 Called for array references.
 250 .IP "hash" 4
 251 .IX Item "hash"
 252 Called for hash references.
 253 .IP "glob" 4
 254 .IX Item "glob"
 255 Called for glob references.
 256 .IP "scalar" 4
 257 .IX Item "scalar"
 258 Called for scalar references.
 259 .IP "tied" 4
 260 .IX Item "tied"
 261 Called on the return value of \f(CW\*(C`tied\*(C'\fR for all tied containers. Also passes in
 262 the variable as the second argument.
 263 .IP "seen" 4
 264 .IX Item "seen"
 265 Called for a reference value encountered a second time.
 266 .Sp
 267 Passes in the result mapping as the second argument.
 268 .SH "AUTHOR"
 269 .IX Header "AUTHOR"
 270 Yuval Kogman <nothingmuch@woobling.org>
 271 .SH "COPYRIGHT & LICENSE"
 272 .IX Header "COPYRIGHT & LICENSE"
 273 .Vb 3
 274 \&        Copyright (c) 2006 Yuval Kogman. All rights reserved
 275 \&        This program is free software; you can redistribute
 276 \&        it and/or modify it under the same terms as Perl itself.
 277 .Ve