Provided by: libpod-pom-perl_2.01-1_all bug

NAME

       Pod::POM::Node - base class for a POM node

SYNOPSIS

           package Pod::POM::Node::Over;
           use parent 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 parent 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 parent 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 parent 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 parent 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 parent 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.