1Data::Visitor(3)      User Contributed Perl Documentation     Data::Visitor(3)
2
3
4

NAME

6       Data::Visitor - Visitor style traversal of Perl data structures
7

SYNOPSIS

9               # NOTE
10               # You probably want to use Data::Visitor::Callback for trivial things
11
12               package FooCounter;
13               use base qw/Data::Visitor/;
14
15               BEGIN { __PACKAGE__->mk_accessors( "number_of_foos" ) };
16
17               sub visit_value {
18                       my ( $self, $data ) = @_;
19
20                       if ( defined $data and $data eq "foo" ) {
21                               $self->number_of_foos( ($self->number_of_foos ⎪⎪ 0) + 1 );
22                       }
23
24                       return $data;
25               }
26
27               my $counter = FooCounter->new;
28
29               $counter->visit( {
30                       this => "that",
31                       some_foos => [ qw/foo foo bar foo/ ],
32                       the_other => "foo",
33               });
34
35               $counter->number_of_foos; # this is now 4
36

DESCRIPTION

38       This module is a simple visitor implementation for Perl values.
39
40       It has a main dispatcher method, "visit", which takes a single perl
41       value and then calls the methods appropriate for that value.
42

METHODS

44       visit $data
45           This method takes any Perl value as it's only argument, and dis‐
46           patches to the various other visiting methods, based on the data's
47           type.
48
49       visit_object $object
50           If the value is a blessed object, "visit" calls this method. The
51           base implementation will just forward to "visit_value".
52
53       visit_ref $value
54           Generic recursive visitor. All non blessed values are given to
55           this.
56
57           "visit_object" can delegate to this method in order to visit the
58           object anyway.
59
60           This will check if the visitor can handle "visit_$reftype" (lower‐
61           case), and if not delegate to "visit_value" instead.
62
63       visit_array $array_ref
64       visit_hash $hash_ref
65       visit_glob $glob_ref
66       visit_scalar $scalar_ref
67           These methods are called for the corresponding container type.
68
69       visit_value $value
70           If the value is anything else, this method is called. The base
71           implementation will return $value.
72
73       visit_hash_entry $key, $value, $hash
74           Delegates to "visit_hash_key" and "visit_hash_value". The value is
75           passed as $_[2] so that it is aliased.
76
77       visit_hash_key $key, $value, $hash
78           Calls "visit" on the key and returns it.
79
80       visit_hash_value $value, $key, $hash
81           The value will be aliased (passed as $_[1]).
82
83       visit_array_entry $value, $index, $array
84           Delegates to "visit" on value. The value is passed as $_[1] to
85           retain aliasing.
86

RETURN VALUE

88       This object can be used as an "fmap" of sorts - providing an ad-hoc
89       functor interface for Perl data structures.
90
91       In void context this functionality is ignored, but in any other context
92       the default methods will all try to return a value of similar struc‐
93       ture, with it's children also fmapped.
94

SUBCLASSING

96       Create instance data using the Class::Accessor interface. Data::Visitor
97       inherits Class::Accessor to get a sane "new".
98
99       Then override the callback methods in any way you like. To retain visi‐
100       tor behavior, make sure to retain the functionality of "visit_array"
101       and "visit_hash".
102

TODO

104       ·   Add support for "natural" visiting of trees.
105
106       ·   Expand "retain_magic" to support tying at the very least, or even
107           more with Variable::Magic if possible.
108
109           Tied values might be redirected to an alternate handler that builds
110           a new empty value, and ties it to a visited clone of the object the
111           original is tied to using a trampoline class. Look into this.
112

SEE ALSO

114       Tree::Simple::VisitorFactory, Data::Traverse
115
116       <http://en.wikipedia.org/wiki/Visitor_pattern>, <http://www.nineby‐
117       nine.org/Software/Learning-Haskell-Notes.html#functors>,
118       <http://en.wikipedia.org/wiki/Functor>
119

AUTHOR

121       Yuval Kogman <nothingmuch@woobling.org>
122

124               Copyright (c) 2006 Yuval Kogman. All rights reserved
125               This program is free software; you can redistribute
126               it and/or modify it under the same terms as Perl itself.
127
128
129
130perl v5.8.8                       2007-10-07                  Data::Visitor(3)
Impressum