Pod::POM::Node(3) User Contributed Perl Documentation Pod::POM::Node(3)NAMEPod::POM::Node - base class for a POM node
SYNOPSIS
package Pod::POM::Node::Over;
use base qw( Pod::POM::Node );
use vars qw( %ATTRIBS @ACCEPT $EXPECT $ERROR );
%ATTRIBS = ( indent => 4 );
@ACCEPT = qw( over item begin for text verbatim );
$EXPECT = q( back );
package main;
my $list = Pod::POM::Node::Over->new(8);
$list->add('item', 'First Item');
$list->add('item', 'Second Item');
...
DESCRIPTION
This documentation describes the inner workings of the Pod::POM::Node
module and gives a brief overview of the relationship between it and
its derived classes. It is intended more as a guide to the internals
for interested hackers than as general user documentation. See
Pod::POM for information on using the modules.
This module implements a base class node which is subclassed to
represent different elements within a Pod Object Model.
package Pod::POM::Node::Over;
use base qw( Pod::POM::Node );
The base class implements the new() constructor method to instantiate
new node objects.
my $list = Pod::POM::Node::Over->new();
The characteristics of a node can be specified by defining certain
variables in the derived class package. The %ATTRIBS hash can be used
to denote attributes that the node should accept. In the case of an
"=over" node, for example, an "indent" attribute can be specified which
otherwise defaults to 4.
package Pod::POM::Node::Over;
use base qw( Pod::POM::Node );
use vars qw( %ATTRIBS $ERROR );
%ATTRIBS = ( indent => 4 );
The new() method will now expect an argument to set the indent value,
or will use 4 as the default if no argument is provided.
my $list = Pod::POM::Node::Over->new(8); # indent: 8
my $list = Pod::POM::Node::Over->new( ); # indent: 4
If the default value is undefined then the argument is mandatory.
package Pod::POM::Node::Head1;
use base qw( Pod::POM::Node );
use vars qw( %ATTRIBS $ERROR );
%ATTRIBS = ( title => undef );
package main;
my $head = Pod::POM::Node::Head1->new('My Title');
If a mandatory argument isn't provided then the constructor will return
undef to indicate failure. The $ERROR variable in the derived class
package is set to contain a string of the form "$type expected a
$attribute".
# dies with error: "head1 expected a title"
my $head = Pod::POM::Node::Head1->new()
|| die $Pod::POM::Node::Head1::ERROR;
For convenience, the error() subroutine can be called as a class method
to retrieve this value.
my $type = 'Pod::POM::Node::Head1';
my $head = $type->new()
|| die $type->error();
The @ACCEPT package variable can be used to indicate the node types
that are permitted as children of a node.
package Pod::POM::Node::Head1;
use base qw( Pod::POM::Node );
use vars qw( %ATTRIBS @ACCEPT $ERROR );
%ATTRIBS = ( title => undef );
@ACCEPT = qw( head2 over begin for text verbatim );
The add() method can then be called against a node to add a new child
node as part of its content.
$head->add('over', 8);
The first argument indicates the node type. The @ACCEPT list is
examined to ensure that the child node type is acceptable for the
parent node. If valid, the constructor for the relevant child node
class is called passing any remaining arguments as attributes. The new
node is then returned.
my $list = $head->add('over', 8);
The error() method can be called against the parent node to retrieve
any constructor error generated by the child node.
my $list = $head->add('over', 8);
die $head->error() unless defined $list;
If the child node is not acceptable to the parent then the add() method
returns one of the constants IGNORE, REDUCE or REJECT, as defined in
Pod::POM::Constants. These return values are used by the Pod::POM
parser module to implement a simple shift/reduce parser.
In the most common case, IGNORE is returned to indicate that the parent
node doesn't know anything about the new child node. The parser uses
this as an indication that it should back up through the parse stack
until it finds a node which will accept this child node. Through this
mechanism, the parser is able to implicitly terminate certain POD
blocks. For example, a list item initiated by a "=item" tag will not
accept another "=item" tag, but will instead return IGNORE. The parser
will back out until it finds the enclosing "=over" node which will
accept it. Thus, a new "=item" implicitly terminates any previous
"=item".
The $EXPECT package variable can be used to indicate a node type which
a parent expects to terminate itself. An "=over" node, for example,
should always be terminated by a matching "=back". When such a match
is made, the add() method returns REDUCE to indicate successful
termination.
package Pod::POM::Node::Over;
use base qw( Pod::POM::Node );
use vars qw( %ATTRIBS @ACCEPT $EXPECT $ERROR );
%ATTRIBS = ( indent => 4 );
@ACCEPT = qw( over item begin for text verbatim );
$EXPECT = q( back );
package main;
my $list = Pod::POM::Node::Over->new();
my $item = $list->add('item');
$list->add('back'); # returns REDUCE
If a child node isn't specified in the @ACCEPT list or doesn't match
any $EXPECT specified then REJECT is returned. The parent node sets an
internal error of the form "$type expected a terminating $expect". The
parser uses this to detect missing POD tags. In nearly all cases the
parser is smart enough to fix the incorrect structure and downgrades
any errors to warnings.
# dies with error 'over expected terminating back'
ref $list->add('head1', 'My Title') # returns REJECT
|| die $list->error();
Each node contains a 'type' field which contains a simple string
indicating the node type, e.g. 'head1', 'over', etc. The $NODES and
$NAMES package variables (in the base class) reference hash arrays
which map these names to and from package names (e.g. head1 <=>
Pod::POM::Node::Head1).
print $list->{ type }; # 'over'
An AUTOLOAD method is provided to access to such internal items for
those who don't like violating an object's encapsulation.
print $list->type();
Nodes also contain a 'content' list, blessed into the
Pod::POM::Node::Content class, which contains the content (child
elements) for the node. The AUTOLOAD method returns this as a list
reference or as a list of items depending on the context in which it is
called.
my $items = $list->content();
my @items = $list->content();
Each node also contains a content list for each individual child node
type that it may accept.
my @items = $list->item();
my @text = $list->text();
my @vtext = $list->verbatim();
The present() method is used to present a node through a particular
view. This simply maps the node type to a method which is then called
against the view object. This is known as 'double dispatch'.
my $view = 'Pod::POM::View::HTML';
print $list->present($view);
The method name is constructed from the node type prefixed by 'view_'.
Thus the following are roughly equivalent.
$list->present($view);
$view->view_list($list);
The benefit of the former over the latter is, of course, that the
caller doesn't need to know or determine the type of the node. The
node itself is in the best position to determine what type it is.
AUTHOR
Andy Wardley <abw@kfs.org>
COPYRIGHT
Copyright (C) 2000, 2001 Andy Wardley. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
SEE ALSO
Consult Pod::POM for a general overview and examples of use.
perl v5.14.2 2010-04-02 Pod::POM::Node(3)
