1Pod::POM::Node(3) User Contributed Perl Documentation Pod::POM::Node(3)
2
6 Pod::POM::Node - base class for a POM node
7
9 package Pod::POM::Node::Over;
10 use base qw( Pod::POM::Node );
11 use vars qw( %ATTRIBS @ACCEPT $EXPECT $ERROR );
12 %ATTRIBS = ( indent => 4 );
14 @ACCEPT = qw( over item begin for text verbatim );
15 $EXPECT = q( back );
16 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
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 This module implements a base class node which is subclassed to
31 represent different elements within a Pod Object Model.
32 package Pod::POM::Node::Over;
34 use base qw( Pod::POM::Node );
35 The base class implements the new() constructor method to instantiate
37 new node objects.
38 my $list = Pod::POM::Node::Over->new();
40 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 package Pod::POM::Node::Over;
48 use base qw( Pod::POM::Node );
49 use vars qw( %ATTRIBS $ERROR );
50 %ATTRIBS = ( indent => 4 );
52 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 my $list = Pod::POM::Node::Over->new(8); # indent: 8
57 my $list = Pod::POM::Node::Over->new( ); # indent: 4
58 If the default value is undefined then the argument is mandatory.
60 package Pod::POM::Node::Head1;
62 use base qw( Pod::POM::Node );
63 use vars qw( %ATTRIBS $ERROR );
64 %ATTRIBS = ( title => undef );
66 package main;
68 my $head = Pod::POM::Node::Head1->new('My Title');
69 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 # dies with error: "head1 expected a title"
76 my $head = Pod::POM::Node::Head1->new()
77 || die $Pod::POM::Node::Head1::ERROR;
78 For convenience, the error() subroutine can be called as a class method
80 to retrieve this value.
81 my $type = 'Pod::POM::Node::Head1';
83 my $head = $type->new()
84 || die $type->error();
85 The @ACCEPT package variable can be used to indicate the node types
87 that are permitted as children of a node.
88 package Pod::POM::Node::Head1;
90 use base qw( Pod::POM::Node );
91 use vars qw( %ATTRIBS @ACCEPT $ERROR );
92 %ATTRIBS = ( title => undef );
94 @ACCEPT = qw( head2 over begin for text verbatim );
95 The add() method can then be called against a node to add a new child
97 node as part of its content.
98 $head->add('over', 8);
100 The first argument indicates the node type. The @ACCEPT list is
102 examined to ensure that the child node type is acceptable for the
103 parent node. If valid, the constructor for the relevant child node
104 class is called passing any remaining arguments as attributes. The new
105 node is then returned.
106 my $list = $head->add('over', 8);
108 The error() method can be called against the parent node to retrieve
110 any constructor error generated by the child node.
111 my $list = $head->add('over', 8);
113 die $head->error() unless defined $list;
114 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 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 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
135 termination.
136 package Pod::POM::Node::Over;
138 use base qw( Pod::POM::Node );
139 use vars qw( %ATTRIBS @ACCEPT $EXPECT $ERROR );
140 %ATTRIBS = ( indent => 4 );
142 @ACCEPT = qw( over item begin for text verbatim );
143 $EXPECT = q( back );
144 package main;
146 my $list = Pod::POM::Node::Over->new();
147 my $item = $list->add('item');
148 $list->add('back'); # returns REDUCE
149 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 # dies with error 'over expected terminating back'
158 ref $list->add('head1', 'My Title') # returns REJECT
159 || die $list->error();
160 Each node contains a 'type' field which contains a simple string
162 indicating the node type, e.g. 'head1', 'over', etc. The $NODES and
163 $NAMES package variables (in the base class) reference hash arrays
164 which map these names to and from package names (e.g. head1 <=>
165 Pod::POM::Node::Head1).
166 print $list->{ type }; # 'over'
168 An AUTOLOAD method is provided to access to such internal items for
170 those who don't like violating an object's encapsulation.
171 print $list->type();
173 Nodes also contain a 'content' list, blessed into the
175 Pod::POM::Node::Content class, which contains the content (child
176 elements) for the node. The AUTOLOAD method returns this as a list
177 reference or as a list of items depending on the context in which it is
178 called.
179 my $items = $list->content();
181 my @items = $list->content();
182 Each node also contains a content list for each individual child node
184 type that it may accept.
185 my @items = $list->item();
187 my @text = $list->text();
188 my @vtext = $list->verbatim();
189 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 my $view = 'Pod::POM::View::HTML';
195 print $list->present($view);
196 The method name is constructed from the node type prefixed by 'view_'.
198 Thus the following are roughly equivalent.
199 $list->present($view);
201 $view->view_list($list);
203 The benefit of the former over the latter is, of course, that the
205 caller doesn't need to know or determine the type of the node. The
206 node itself is in the best position to determine what type it is.
207
209 Andy Wardley <abw@kfs.org>
210
212 Copyright (C) 2000, 2001 Andy Wardley. All Rights Reserved.
213 This module is free software; you can redistribute it and/or modify it
215 under the same terms as Perl itself.
216
218 Consult Pod::POM for a general overview and examples of use.
219perl v5.12.0 2010-04-02 Pod::POM::Node(3)