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 to visit_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 to visit_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 and visit_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-2008 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.