NAME

Class::Visitor - Visitor and Iterator extensions to Class::Template

SYNOPSIS

  use Class::Visitor;

  visitor_class 'CLASS', 'SUPER', { TEMPLATE };
  visitor_class 'CLASS', 'SUPER', [ TEMPLATE ];

  $obj = CLASS->new ();
  $iter = $obj->iter;
  $iter = $obj->iter ($parent, $array, $index);

  $obj->accept($visitor, ...);
  $obj->children_accept($visitor, ...);
  $obj->children_accept_ARRAYMEMBER ($visitor, ...);
  $obj->push_ARRAYMEMBER($value[, ...]);
  $value = $obj->pop_ARRAYMEMBER;
  $obj->as_string ([$context[, ...]]);
  $obj->ARRAYMEMBER_as_string ([$context[, ...]]);

  $iter inherits the following from Class::Iter:

  $iter->parent;
  $iter->is_iter;
  $iter->root;
  $iter->rootpath;
  $iter->next;
  $iter->at_end;
  $iter->delegate;
  $iter->is_same ($obj);

DESCRIPTION

Class::Visitor extends the getter/setter functions provided by Class::Template for CLASS by defining methods for using the Visitor and Iterator design patterns. All of the Iterator methods are inherited from Class::Iter except iter.

CLASS is the name of the new class, SUPER the superclass of this class (will define @ISA), and TEMPLATE is as defined in Class::Template.

$obj-iter> returns a new iterator for this object. If parent, array, and index are not defined, then the new iterator is treated as the root object. Except as inherited from Class::Iter or as defined below, methods for $iter and $obj work the same.

The accept methods cause a callback to $visitor with $self as the first argument plus the rest of the arguments passed to accept. This is implemented like:

    sub accept {
        my $self = shift; my $visitor = shift;
        $visitor->visit_MyClass ($self, @_);
    }

children_accept calls accept on each object in the array field named contents. children_accept_ARRAYMEMBER does the same for ARRAYMEMBER.

Calling accept methods on iterators always calls back using iterators. Calling accept on non-iterators calls back using non-iterators. The latter is significantly faster.

push and pop act like their respective array functions.

as_string returns the concatenated scalar values of the array field named contents, possibly modified by $context. ARRAYMEMBER_as_string does the same for ARRAYMEMBER.

Visitor handles scalars specially for children_accept and as_string. In the case of children_accept, Visitor will create an iterator in the class Class::Scalar::Iter with the scalar as the delegate.

In the case of as_string, Visitor will use the string unless $context->{cdata_mapper} is defined, in which case it returns the result of calling the cdata_mapper subroutine with the scalar and the remaining arguments. The actual implementation is:

    &{$context->{cdata_mapper}} ($scalar, @_);

AUTHOR

Ken MacLeod, ken@bitsko.slc.ut.us

SEE ALSO

perl(1), Class::Template(3), Class::Iter(3).

The package SGML::SPGrove uses Class::Visitor extensively.