Take me over?
NAME
Data::Visitor - Visitor style traversal of Perl data structures
SYNOPSIS
# NOTE
# You probably want to use Data::Visitor::Callback for trivial things
package FooCounter;
use base qw/Data::Visitor/;
BEGIN { __PACKAGE__->mk_accessors( "number_of_foos" ) };
sub visit_value {
my ( $self, $data ) = @_;
if ( defined $data and $data eq "foo" ) {
$self->number_of_foos( ($self->number_of_foos || 0) + 1 );
}
return $data;
}
my $counter = FooCounter->new;
$counter->visit( {
this => "that",
some_foos => [ qw/foo foo bar foo/ ],
the_other => "foo",
});
$counter->number_of_foos; # this is now 4
DESCRIPTION
This module is a simple visitor implementation for Perl values.
It has a main dispatcher method, visit
, which takes a single perl value and then calls the methods appropriate for that value.
METHODS
- visit $data
-
This method takes any Perl value as it's only argument, and dispatches to the various other visiting methods, based on the data's type.
- visit_object $object
-
If the value is a blessed object,
visit
calls this method. The base implementation will just forward tovisit_value
. - visit_ref $value
-
Generic recursive visitor. All non blessed values are given to this.
visit_object
can delegate to this method in order to visit the object anyway.This will check if the visitor can handle
visit_$reftype
(lowercase), and if not delegate tovisit_value
instead. - visit_array $array_ref
- visit_hash $hash_ref
- visit_glob $glob_ref
- visit_scalar $scalar_ref
-
These methods are called for the corresponding container type.
- visit_value $value
-
If the value is anything else, this method is called. The base implementation will return $value.
- visit_hash_entry $key, $value, $hash
-
Delegates to
visit_hash_key
andvisit_hash_value
. The value is passed as$_[2]
so that it is aliased. - visit_hash_key $key, $value, $hash
-
Calls
visit
on the key and returns it. - visit_hash_value $value, $key, $hash
-
The value will be aliased (passed as
$_[1]
). - visit_array_entry $value, $index, $array
-
Delegates to
visit
on value. The value is passed as$_[1]
to retain aliasing.
RETURN VALUE
This object can be used as an fmap
of sorts - providing an ad-hoc functor interface for Perl data structures.
In void context this functionality is ignored, but in any other context the default methods will all try to return a value of similar structure, with it's children also fmapped.
SUBCLASSING
Create instance data using the Class::Accessor interface. Data::Visitor inherits Class::Accessor to get a sane new
.
Then override the callback methods in any way you like. To retain visitor behavior, make sure to retain the functionality of visit_array
and visit_hash
.
TODO
Add support for "natural" visiting of trees.
Expand
retain_magic
to support tying at the very least, or even more with Variable::Magic if possible.Tied values might be redirected to an alternate handler that builds a new empty value, and ties it to a visited clone of the object the original is tied to using a trampoline class. Look into this.
SEE ALSO
Tree::Simple::VisitorFactory, Data::Traverse
http://en.wikipedia.org/wiki/Visitor_pattern, http://www.ninebynine.org/Software/Learning-Haskell-Notes.html#functors, http://en.wikipedia.org/wiki/Functor
AUTHOR
Yuval Kogman <nothingmuch@woobling.org>
COPYRIGHT & LICENSE
Copyright (c) 2006 Yuval Kogman. All rights reserved
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.