Pod::POM::Node(3pm)

1Pod::POM::Node(3)     User Contributed Perl Documentation    Pod::POM::Node(3)
2
3
4

NAME

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

SYNOPSIS

9           package Pod::POM::Node::Over;
10           use base qw( Pod::POM::Node );
11           use vars qw( %ATTRIBS @ACCEPT $EXPECT $ERROR );
12
13           %ATTRIBS =   ( indent => 4 );
14           @ACCEPT  = qw( over item begin for text verbatim );
15           $EXPECT  =  q( back );
16
17           package main;
18           my $list = Pod::POM::Node::Over->new(8);
19           $list->add('item', 'First Item');
20           $list->add('item', 'Second Item');
21           ...
22

DESCRIPTION

24       This documentation describes the inner workings of the Pod::POM::Node
25       module and gives a brief overview of the relationship between it and
26       its derived classes.  It is intended more as a guide to the internals
27       for interested hackers than as general user documentation.  See
28       Pod::POM for information on using the modules.
29
30       This module implements a base class node which is subclassed to repre‐
31       sent different elements within a Pod Object Model.
32
33           package Pod::POM::Node::Over;
34           use base qw( Pod::POM::Node );
35
36       The base class implements the new() constructor method to instantiate
37       new node objects.
38
39           my $list = Pod::POM::Node::Over->new();
40
41       The characteristics of a node can be specified by defining certain
42       variables in the derived class package.  The %ATTRIBS hash can be used
43       to denote attributes that the node should accept.  In the case of an
44       "=over" node, for example, an "indent" attribute can be specified which
45       otherwise defaults to 4.
46
47           package Pod::POM::Node::Over;
48           use base qw( Pod::POM::Node );
49           use vars qw( %ATTRIBS $ERROR );
50
51           %ATTRIBS = ( indent => 4 );
52
53       The new() method will now expect an argument to set the indent value,
54       or will use 4 as the default if no argument is provided.
55
56           my $list = Pod::POM::Node::Over->new(8);    # indent: 8
57           my $list = Pod::POM::Node::Over->new( );    # indent: 4
58
59       If the default value is undefined then the argument is mandatory.
60
61           package Pod::POM::Node::Head1;
62           use base qw( Pod::POM::Node );
63           use vars qw( %ATTRIBS $ERROR );
64
65           %ATTRIBS = ( title => undef );
66
67           package main;
68           my $head = Pod::POM::Node::Head1->new('My Title');
69
70       If a mandatory argument isn't provided then the constructor will return
71       undef to indicate failure.  The $ERROR variable in the derived class
72       package is set to contain a string of the form "$type expected a
73       $attribute".
74
75           # dies with error: "head1 expected a title"
76           my $head = Pod::POM::Node::Head1->new()
77               ⎪⎪ die $Pod::POM::Node::Head1::ERROR;
78
79       For convenience, the error() subroutine can be called as a class method
80       to retrieve this value.
81
82           my $type = 'Pod::POM::Node::Head1';
83           my $head = $type->new()
84               ⎪⎪ die $type->error();
85
86       The @ACCEPT package variable can be used to indicate the node types
87       that are permitted as children of a node.
88
89           package Pod::POM::Node::Head1;
90           use base qw( Pod::POM::Node );
91           use vars qw( %ATTRIBS @ACCEPT $ERROR );
92
93           %ATTRIBS =   ( title => undef );
94           @ACCEPT  = qw( head2 over begin for text verbatim );
95
96       The add() method can then be called against a node to add a new child
97       node as part of its content.
98
99           $head->add('over', 8);
100
101       The first argument indicates the node type.  The @ACCEPT list is exam‐
102       ined to ensure that the child node type is acceptable for the parent
103       node.  If valid, the constructor for the relevant child node class is
104       called passing any remaining arguments as attributes.  The new node is
105       then returned.
106
107           my $list = $head->add('over', 8);
108
109       The error() method can be called against the parent node to retrieve
110       any constructor error generated by the child node.
111
112           my $list = $head->add('over', 8);
113           die $head->error() unless defined $list;
114
115       If the child node is not acceptable to the parent then the add() method
116       returns one of the constants IGNORE, REDUCE or REJECT, as defined in
117       Pod::POM::Constants.  These return values are used by the Pod::POM
118       parser module to implement a simple shift/reduce parser.
119
120       In the most common case, IGNORE is returned to indicate that the parent
121       node doesn't know anything about the new child node.  The parser uses
122       this as an indication that it should back up through the parse stack
123       until it finds a node which will accept this child node.  Through this
124       mechanism, the parser is able to implicitly terminate certain POD
125       blocks.  For example, a list item initiated by a "=item" tag will not
126       accept another "=item" tag, but will instead return IGNORE.  The parser
127       will back out until it finds the enclosing "=over" node which will
128       accept it.  Thus, a new "=item" implicitly terminates any previous
129       "=item".
130
131       The $EXPECT package variable can be used to indicate a node type which
132       a parent expects to terminate itself.  An "=over" node, for example,
133       should always be terminated by a matching "=back".  When such a match
134       is made, the add() method returns REDUCE to indicate successful termi‐
135       nation.
136
137           package Pod::POM::Node::Over;
138           use base qw( Pod::POM::Node );
139           use vars qw( %ATTRIBS @ACCEPT $EXPECT $ERROR );
140
141           %ATTRIBS =   ( indent => 4 );
142           @ACCEPT  = qw( over item begin for text verbatim );
143           $EXPECT  =  q( back );
144
145           package main;
146           my $list = Pod::POM::Node::Over->new();
147           my $item = $list->add('item');
148           $list->add('back');                 # returns REDUCE
149
150       If a child node isn't specified in the @ACCEPT list or doesn't match
151       any $EXPECT specified then REJECT is returned.  The parent node sets an
152       internal error of the form "$type expected a terminating $expect".  The
153       parser uses this to detect missing POD tags.  In nearly all cases the
154       parser is smart enough to fix the incorrect structure and downgrades
155       any errors to warnings.
156
157           # dies with error 'over expected terminating back'
158           ref $list->add('head1', 'My Title')     # returns REJECT
159               ⎪⎪ die $list->error();
160
161       Each node contains a 'type' field which contains a simple string indi‐
162       cating the node type, e.g. 'head1', 'over', etc.  The $NODES and $NAMES
163       package variables (in the base class) reference hash arrays which map
164       these names to and from package names (e.g. head1 <=>
165       Pod::POM::Node::Head1).
166
167           print $list->{ type };      # 'over'
168
169       An AUTOLOAD method is provided to access to such internal items for
170       those who don't like violating an object's encapsulation.
171
172           print $list->type();
173
174       Nodes also contain a 'content' list, blessed into the
175       Pod::POM::Node::Content class, which contains the content (child ele‐
176       ments) for the node.  The AUTOLOAD method returns this as a list refer‐
177       ence or as a list of items depending on the context in which it is
178       called.
179
180           my $items = $list->content();
181           my @items = $list->content();
182
183       Each node also contains a content list for each individual child node
184       type that it may accept.
185
186           my @items = $list->item();
187           my @text  = $list->text();
188           my @vtext = $list->verbatim();
189
190       The present() method is used to present a node through a particular
191       view.  This simply maps the node type to a method which is then called
192       against the view object.  This is known as 'double dispatch'.
193
194           my $view = 'Pod::POM::View::HTML';
195           print $list->present($view);
196
197       The method name is constructed from the node type prefixed by 'view_'.
198       Thus the following are roughly equivalent.
199
200           $list->present($view);
201
202           $view->view_list($list);
203
204       The benefit of the former over the latter is, of course, that the call‐
205       er doesn't need to know or determine the type of the node.  The node
206       itself is in the best position to determine what type it is.
207

AUTHOR

209       Andy Wardley <abw@kfs.org>
210

COPYRIGHT

212       Copyright (C) 2000, 2001 Andy Wardley.  All Rights Reserved.
213
214       This module is free software; you can redistribute it and/or modify it
215       under the same terms as Perl itself.
216

NAME

SYNOPSIS

DESCRIPTION

AUTHOR

COPYRIGHT

SEE ALSO