NAME
Parse::RecDescent::Topiary - tree surgery for Parse::RecDescent
autotrees
SYNOPSIS
use Parse::RecDescent::Topiary;
my $parser = Parse::RecDescent->new($grammar);
...
my $tree = topiary(
tree => $parser->mainrule,
namespace => 'MyModule::Foo',
ucfirst => 1
);
DESCRIPTION
Parse::RecDescent has a mechanism for automatically generating parse
trees. What this does is to bless each resulting node into a package
namespace corresponding to the rule. This might not be desirable, for a
couple of reasons:
* You probably don't want to pollute the top-level namespace with
packages, and you probably don't want your grammar rules to be named
according to CPAN naming conventions. Also, the namespaces could
collide if an application has two different RecDescent grammars,
that share some rule names.
* Parse::RecDescent merely blesses the data structures. It does not
call a constructor. Parse::RecDescent::Topiary calls "new" for each
class. A base class, Parse::RecDescent::Topiary::Base is provided in
the distribution, to construct hashref style objects. The user can
always supply their own - inside out or whatever.
"topiary"
This is a function which recursively rebuilds an autotree returned by
Parse::RecDescent, using constructors for each node.
This exported function takes a list of option / value pairs:
"tree"
Pass in the resulting autotree returned by a Parse::RecDescent
object.
"namespace"
If not specified, topiary will not use objects in the new parse
tree. This can be specified either as a single prefix value, or a
list of namespaces as an arrayref.
As the tree is walked, each blessed node is used to form a candidate
class name, and if such a candidate class has a constructor, i.e. if
"Foo::Bar::Token->can('new')" returns true, this will be used to
construct the new node object (see delegation_class).
If a list of namespaces are given, each one is tried in turn, until
a "new" method is found. If no constructor is found, the node is
built as a data structure, i.e. it is not blessed or constructed.
"ucfirst"
Optional flag to upper case the first character of the rule when
forming the class name.
"consolidate"
Optional flag that causes topiary to reduce the nesting,
unambiguously, of optionally quantified productions. The production
foo(?) causes generation of the hash entry 'foo(?)' containing an
arrayref of either 0 or 1 elements depending whether foo was present
or not in the input string.
If consolidate is a true value, topiary processes this entry, and
either generates a hash entry foo => foo_object if foo was present,
or does not generate a hash entry if it was absent.
"args"
Optional user arguments passed in. These are available to the
constructors, and the default constructor will put them into the new
objects as $self->{__ARGS__}.
"delegation_class"
@class_list = qw(Foo::Bar Foo::Baz);
my $class = delegation_class( 'Dongle', \@class_list, 'wiggle' );
This subroutine is not exported by default, and is used internally by
topiary. $class is set to "Foo::Bar::Dongle" if
"Foo::Bar::Dongle->can('wiggle')" or set to "Foo::Baz::Dongle" if
"Foo::Baz::Dongle->can('wiggle')" or return undef if no match is found.
BUGS
Please report bugs to
http://rt.cpan.org
AUTHOR
Ivor Williams
CPAN ID: IVORW
[email protected]
COPYRIGHT
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included
with this module.
SEE ALSO
Parse::RecDescent.
