NAME¶
Pod::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 list 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.