Pod::POM(3pm)

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

NAME

6       Pod::POM - POD Object Model
7

SYNOPSIS

9           use Pod::POM;
10
11           my $parser = Pod::POM->new(\%options);
12
13           # parse from a text string
14           my $pom = $parser->parse_text($text)
15               ⎪⎪ die $parser->error();
16
17           # parse from a file specified by name or filehandle
18           my $pom = $parser->parse_text($file)
19               ⎪⎪ die $parser->error();
20
21           # parse from text or file
22           my $pom = $parser->parse($text_or_file)
23               ⎪⎪ die $parser->error();
24
25           # examine any warnings raised
26           foreach my $warning ($parser->warnings()) {
27               warn $warning, "\n";
28           }
29
30           # print table of contents using each =head1 title
31           foreach my $head1 ($pom->head1()) {
32               print $head1->title(), "\n";
33           }
34
35           # print each section
36           foreach my $head1 ($pom->head1()) {
37               print $head1->title(), "\n";
38               print $head1->content();
39           }
40
41           # print the entire document as HTML
42           use Pod::POM::View::HTML;
43           print Pod::POM::View::HTML->print($pom);
44
45           # create custom view
46           package My::View;
47           use base qw( Pod::POM::View::HTML );
48
49           sub view_head1 {
50               my ($self, $item) = @_;
51               return '<h1>',
52                      $item->title->present($self),
53                      "</h1>\n",
54                      $item->content->present($self);
55           }
56
57           package main;
58           print My::View->print($pom);
59

DESCRIPTION

61       This module implements a parser to convert Pod documents into a simple
62       object model form known hereafter as the Pod Object Model.  The object
63       model is generated as a hierarchical tree of nodes, each of which rep‐
64       resents a different element of the original document.  The tree can be
65       walked manually and the nodes examined, printed or otherwise manipu‐
66       lated.  In addition, Pod::POM supports and provides view objects which
67       can automatically traverse the tree, or section thereof, and generate
68       an output representation in one form or another.
69
70       Let's look at a typical Pod document by way of example.
71
72           =head1 NAME
73
74           My::Module - just another My::Module
75
76           =head1 DESCRIPTION
77
78           This is My::Module, a deeply funky piece of Perl code.
79
80           =head2 METHODS
81
82           My::Module implements the following methods
83
84           =over 4
85
86           =item new(\%config)
87
88           This is the constructor method.  It accepts the following
89           configuration options:
90
91           =over 4
92
93           =item name
94
95           The name of the thingy.
96
97           =item colour
98
99           The colour of the thingy.
100
101           =back
102
103           =item print()
104
105           This prints the thingy.
106
107           =back
108
109           =head1 AUTHOR
110
111           My::Module was written by me E<lt>me@here.orgE<gt>
112
113       This document contains 3 main sections, NAME, DESCRIPTION and AUTHOR,
114       each of which is delimited by an opening "=head1" tag.  NAME and AUTHOR
115       each contain only a single line of text, but DESCRIPTION is more inter‐
116       esting.  It contains a line of text followed by the "=head2" subsec‐
117       tion, METHODS.  This contains a line of text and a list extending from
118       the "=over 4" to the final "=back" just before the AUTHOR section
119       starts.  The list contains 2 items, "new(\%config)", which itself con‐
120       tains some text and a list of 2 items, and "print()".
121
122       Presented as plain text and using indentation to indicate the element
123       nesting, the model then looks something like this :
124
125           NAME
126               My::Module - just another My::Module
127
128           DESCRIPTION
129               This is My::Module, a deeply funky piece of Perl code.
130
131               METHODS
132                   My::Module implements the following methods
133
134                   * new(\%config)
135                       This is the constructor method.  It accepts the
136                       following configuration options:
137
138                       * name
139                           The name of the thingy.
140
141                       * colour
142                           The colour of the thingy.
143
144                   * item print()
145                       This prints the thingy.
146
147           AUTHOR
148               My::Myodule was written by me <me@here.org>
149
150       Those of you familiar with XML may prefer to think of it in the follow‐
151       ing way:
152
153           <pod>
154             <head1 title="NAME">
155               <p>My::Module - just another My::Module</p>
156             </head1>
157
158             <head1 title="DESCRIPTION">
159               <p>This is My::Module, a deeply funky piece of
160                  Perl code.</p>
161
162               <head2 title="METHODS">
163                 <p>My::Module implements the following methods</p>
164
165                 <over indent=4>
166                   <item title="item new(\%config)">
167                     <p>This is the constructor method.  It accepts
168                        the following configuration options:</p>
169
170                     <over indent=4>
171                       <item title="name">
172                         <p>The name of the thingy.</p>
173                       </item>
174
175                       <item title="colour">
176                         <p>The colour of the thingy.</p>
177                       </item>
178                     </over>
179                   </item>
180
181                   <item title="print()">
182                     <p>This prints the thingy.</p>
183                   </item>
184                 </over>
185               </head2>
186             </head1>
187
188             <head1 title="AUTHOR">
189               <p>My::Myodule was written by me &lt;me@here.org&gt;
190             </head1>
191           </pod>
192
193       Notice how we can make certain assumptions about various elements.  For
194       example, we can assume that any "=head1" section we find begins a new
195       section and implicitly ends any previous section.  Similarly, we can
196       assume an "=item" ends when the next one begins, and so on.  In terms
197       of the XML example shown above, we are saying that we're smart enough
198       to add a "</head1>" element to terminate any previously opened
199       "<head1>" when we find a new "=head1" tag in the input document.
200
201       However you like to visualise the content, it all comes down to the
202       same underlying model.  The job of the Pod::POM module is to read an
203       input Pod document and build an object model to represent it in this
204       structured form.
205
206       Each node in the tree (i.e. element in the document) is represented by
207       a Pod::POM::Node::* object.  These encapsulate the attributes for an
208       element (such as the title for a "=head1" tag) and also act as contain‐
209       ers for further Pod::POM::Node::* objects representing the content of
210       the element.  Right down at the leaf nodes, we have simple object types
211       to represent formatted and verbatim text paragraphs and other basic
212       elements like these.
213
214       Parsing Pod
215
216       The Pod::POM module implements the methods parse_file($file),
217       parse_text($text) and parse($file_or_text) to parse Pod files and input
218       text.  They return a Pod::POM::Node::Pod object to represent the root
219       of the Pod Object Model, effectively the "<pod>" element in the XML
220       tree shown above.
221
222           use Pod::POM;
223
224           my $parser = Pod::POM->new();
225           my $pom = $parser->parse_file($filename)
226               ⎪⎪ die $parser->error();
227
228       The parse(), parse_text() and parse_file() methods return undef on
229       error.  The error() method can be called to retrieve the error message
230       generated.  Parsing a document may also generate non-fatal warnings.
231       These can be retrieved via the warnings() method which returns a refer‐
232       ence to a list when called in scalar context or a list of warnings when
233       called in list context.
234
235           foreach my $warn ($parser->warnings()) {
236               warn $warn, "\n";
237           }
238
239       Alternatively, the 'warn' configuration option can be set to have warn‐
240       ings automatically raised via "warn()" as they are encountered.
241
242           my $parser = Pod::POM->new( warn => 1 );
243
244       Walking the Object Model
245
246       Having parsed a document into an object model, we can then select vari‐
247       ous items from it.  Each node implements methods (via AUTOLOAD) which
248       correspond to the attributes and content elements permitted within in.
249
250       So to fetch the list of '=head1' sections within our parsed document,
251       we would do the following:
252
253           my $sections = $pom->head1();
254
255       Methods like this will return a list of further Pod::POM::Node::*
256       objects when called in list context or a reference to a list when
257       called in scalar context.  In the latter case, the list is blessed into
258       the Pod::POM::Node::Content class which gives it certain magical prop‐
259       erties (more on that later).
260
261       Given the list of Pod::POM::Node::Head1 objects returned by the above,
262       we can print the title attributes of each like this:
263
264           foreach my $s (@$sections) {
265               print $s->title();
266           }
267
268       Let's look at the second section, DESCRIPTION.
269
270           my $desc = $sections->[1];
271
272       We can print the title of each subsection within it:
273
274           foreach my $ss ($desc->head2()) {
275               print $ss->title();
276           }
277
278       Hopefully you're getting the idea by now, so here's a more studly exam‐
279       ple to print the title for each item contained in the first list within
280       the METHODS section:
281
282           foreach my $item ($desc->head2->[0]->over->[0]->item) {
283               print $item->title(), "\n";
284           }
285
286       Element Content
287
288       This is all well and good if you know the precise structure of a docu‐
289       ment in advance.  For those more common cases when you don't, each node
290       that can contain other nodes provides a 'content' method to return a
291       complete list of all the other nodes that it contains.  The 'type'
292       method can be called on any node to return its element type (e.g.
293       'head1', 'head2', 'over', item', etc).
294
295           foreach my $item ($pom->content()) {
296               my $type = $item->type();
297               if ($type eq 'head1') {
298                   ...
299               }
300               elsif ($type eq 'head2') {
301                   ...
302               }
303               ...
304           }
305
306       The content for an element is represented by a reference to a list,
307       blessed into the Pod::POM::Node::Content class.  This provides some
308       magic in the form of an overloaded stringification operator which will
309       automatically print the contents of the list if you print the object
310       itself.  In plain English, or rather, in plain Perl, this means you can
311       do things like the following:
312
313           foreach my $head1 ($pom->head1()) {
314               print '<h1>', $head1->title(), "</h1>\n\n";
315               print $head1->content();
316           }
317
318           # print all the root content
319           foreach my $item ($pom->content()) {
320               print $item;
321           }
322
323           # same as above
324           print $pom->content();
325
326       In fact, all Pod::POM::Node::* objects provide this same magic, and
327       will attempt to Do The Right Thing to present themselves in the appro‐
328       priate manner when printed.  Thus, the following are all valid.
329
330           print $pom;                 # entire document
331           print $pom->content;        # content of document
332           print $pom->head1->[0];     # just first section
333           print $pom->head1;          # print all sections
334           foreach my $h1 ($pom->head1()) {
335               print $h1->head2();     # print all subsections
336           }
337
338       Output Views
339
340       To understand how the different elements go about presenting themselves
341       in "the appropriate manner", we must introduce the concept of a view.
342       A view is quite simply a particular way of looking at the model.  In
343       real terms, we can think of a view as being some kind of output type
344       generated by a pod2whatever converter.  Notionally we can think in
345       terms of reading in an input document, building a Pod Object Model, and
346       then generating an HTML view of the document, and/or a LaTeX view, a
347       plain text view, and so on.
348
349       A view is represented in this case by an object class which contains
350       methods for displaying each of the different element types that could
351       be encountered in any Pod document.  There's a method for displaying
352       "=head1" sections (view_head1()), another method for displaying
353       "=head2" sections (view_head2()), one for "=over" (view_over()),
354       another for "=item" (view_item()) and so on.
355
356       If we happen to have a reference to a $node and we know it's a 'head1'
357       node, then we can directly call the right view method to have it dis‐
358       played properly:
359
360           $view = 'Pod::POM::View::HTML';
361           $view->view_head1($node);
362
363       Thus our earlier example can be modified to be slightly less laborious
364       and marginally more flexible.
365
366           foreach my $node ($pom->content) {
367               my $type = $node->type();
368               if ($type eq 'head1') {
369                   print $view->view_head1($node);
370               }
371               elsif ($type eq 'head2') {
372                   print $view->view_head2($node);
373               }
374               ...
375           }
376
377       However, this is still far from ideal.  To make life easier, each
378       Pod::POM::Node::* class inherits (or possibly redefines) a
379       "present($view)" method from the Pod::POM::Node base class.  This
380       method expects a reference to a view object passed as an argument, and
381       it simply calls the appropriate view_xxx() method on the view object,
382       passing itself back as an argument.  In object parlance, this is known
383       as "double dispatch".  The beauty of it is that you don't need to know
384       what kind of node you have to be able to print it.  You simply pass it
385       a view object and leave it to work out the rest.
386
387           foreach my $node ($pom->content) {
388               print $node->present($view);
389           }
390
391       If $node is a Pod::POM::Node::Head1 object, then the view_head1($node)
392       method gets called against the $view object.  Otherwise, if it's a
393       Pod::POM::Node::Head2 object, then the view_head2($node) method is dis‐
394       patched.  And so on, and so on, with each node knowing what it is and
395       where it's going as if determined by some genetically pre-programmed
396       instinct.  Fullfilling their destinies, so to speak.
397
398       Double dispatch allows us to do away with all the explicit type check‐
399       ing and other nonsense and have the node objects themselves worry about
400       where they should be routed to.  At the cost of an extra method call
401       per node, we get programmer convenience, and that's usually a Good
402       Thing.
403
404       Let's have a look at how the view and node classes might be imple‐
405       mented.
406
407           package Pod::POM::View::HTML;
408
409           sub view_pod {
410               my ($self, $node) = @_;
411               return $node->content->present($self);
412           }
413
414           sub view_head1 {
415               my ($self, $node) = @_;
416               return "<h1>", $node->title->present($self), "</h1>\n\n"
417                    . $node->content->present($self);
418           }
419
420           sub view_head2 {
421               my ($self, $node) = @_;
422               return "<h2>", $node->title->present($self), "</h2>\n\n"
423                    . $node->content->present($self);
424           }
425
426           ...
427
428           package Pod::POM::Node::Pod;
429
430           sub present {
431               my ($self, $view) = @_;
432               $view->view_pod($self);
433           }
434
435           package Pod::POM::Node::Head1;
436
437           sub present {
438               my ($self, $view) = @_;
439               $view->view_head1($self);
440           }
441
442           package Pod::POM::Node::Head2;
443
444           sub present {
445               my ($self, $view) = @_;
446               $view->view_head2($self);
447           }
448
449           ...
450
451       Some of the view_xxx methods make calls back against the node objects
452       to display their attributes and/or content.  This is shown in, for
453       example, the view_head1() method above, where the method prints the
454       section title in "<h1>"..."<h1>" tags, followed by the remaining sec‐
455       tion content.
456
457       Note that the title() attribute is printed by calling its present()
458       method, passing on the reference to the current view.  Similarly, the
459       content present() method is called giving it a chance to Do The Right
460       Thing to present itself correctly via the view object.
461
462       There's a good chance that the title attribute is going to be regular
463       text, so we might be tempted to simply print the title rather than call
464       its present method.
465
466           sub view_head1 {
467               my ($self, $node) = @_;
468               # not recommended, prefer $node->title->present($self)
469               return "<h1>", $node->title(), "</h1>\n\n", ...
470           }
471
472       However, it is entirely valid for titles and other element attributes,
473       as well as regular, formatted text blocks to contain code sequences,
474       such like "B<this>" and "I<this>".  These are used to indicate differ‐
475       ent markup styles, mark external references or index items, and so on.
476       What's more, they can be "B<nested I<indefinately>>".  Pod::POM takes
477       care of all this by parsing such text, along with any embedded
478       sequences, into Yet Another Tree, the root node of which is a
479       Pod::POM::Node::Text object, possibly containing other
480       Pod::POM::Node::Sequence objects.  When the text is presented, the tree
481       is automatically walked and relevant callbacks made against the view
482       for the different sequence types.  The methods called against the view
483       are all prefixed 'view_seq_', e.g.  'view_seq_bold', 'view_seq_italic'.
484
485       Now the real magic comes into effect.  You can define one view to ren‐
486       der bold/italic text in one style:
487
488           package My::View::Text;
489           use base qw( Pod::POM::View::Text );
490
491           sub view_seq_bold {
492               my ($self, $text) = @_;
493               return "*$text*";
494           }
495
496           sub view_seq_italic {
497               my ($self, $text) = @_;
498               return "_$text_";
499           }
500
501       And another view to render it in a different style:
502
503           package My::View::HTML;
504           use base qw( Pod::POM::View::HTML );
505
506           sub view_seq_bold {
507               my ($self, $text) = @_;
508               return "<b>$text</b>";
509           }
510
511           sub view_seq_italic {
512               my ($self, $text) = @_;
513               return "<i>$text</i>";
514           }
515
516       Then, you can easily view a Pod Object Model in either style:
517
518           my $text = 'My::View::Text';
519           my $html = 'My::View::HTML';
520
521           print $pom->present($text);
522           print $pom->present($html);
523
524       And you can apply this technique to any node within the object model.
525
526           print $pom->head1->[0]->present($text);
527           print $pom->head1->[0]->present($html);
528
529       In these examples, the view passed to the present() method has been a
530       class name.  Thus, the view_xxx methods get called as class methods, as
531       if written:
532
533           My::View::Text->view_head1(...);
534
535       If your view needs to maintain state then you can create a view object
536       and pass that to the present() method.
537
538           my $view = My::View->new();
539           $node->present($view);
540
541       In this case the view_xxx methods get called as object methods.
542
543           sub view_head1 {
544               my ($self, $node) = @_;
545               my $title = $node->title();
546               if ($title eq 'NAME' && ref $self) {
547                   $self->{ title } = $title();
548               }
549               $self->SUPER::view_head1($node);
550           }
551
552       Whenever you print a Pod::POM::Node::* object, or do anything to cause
553       Perl to stringify it (such as including it another quoted string "like
554       $this"), then its present() method is automatically called.  When
555       called without a view argument, the present() method uses the default
556       view specified in $Pod::POM::DEFAULT_VIEW, which is, by default,
557       'Pod::POM::View::Pod'.  This view regenerates the original Pod docu‐
558       ment, although it should be noted that the output generated may not be
559       exactly the same as the input.  The parser is smart enough to detect
560       some common errors (e.g. not terminating an "=over" with a "=back") and
561       correct them automatically.  Thus you might find a "=back" correctly
562       placed in the output, even if you forgot to add it to the input.  Such
563       corrections raise non-fatal warnings which can later be examined via
564       the warnings() method.
565
566       You can update the $Pod::POM::DEFAULT_VIEW package variable to set the
567       default view, or call the default_view() method.  The default_view()
568       method will automatically load any package you specify.  If setting the
569       package variable directly, you should ensure that any packages required
570       have been pre-loaded.
571
572           use My::View::HTML;
573           $Pod::POM::DEFAULT_VIEW = 'My::View::HTML';
574
575       or
576
577           Pod::POM->default_view('My::View::HTML');
578
579       Template Toolkit Views
580
581       One of the motivations for writing this module was to make it easier to
582       customise Pod documentation to your own look and feel or local format‐
583       ting conventions.  By clearly separating the content (represented by
584       the Pod Object Model) from the presentation style (represented by one
585       or more views) it becomes much easier to achieve this.
586
587       The latest version of the Template Toolkit (2.06 at the time of writ‐
588       ing) provides a Pod plugin to interface to this module.  It also imple‐
589       ments a new (but experimental) VIEW directive which can be used to
590       build different presentation styles for converting Pod to other for‐
591       mats.  The Template Toolkit is available from CPAN:
592
593           http://www.cpan.org/modules/by-module/Template/
594
595       Template Toolkit views are similar to the Pod::POM::View objects
596       described above, except that they allow the presentation style for each
597       Pod component to be written as a template file or block rather than an
598       object method.  The precise syntax and structure of the VIEW directive
599       is subject to change (given that it's still experimental), but at
600       present it can be used to define a view something like this:
601
602           [% VIEW myview %]
603
604              [% BLOCK view_head1 %]
605                 <h1>[% item.title.present(view) %]</h1>
606                 [% item.content.present(view) %]
607              [% END %]
608
609              [% BLOCK view_head2 %]
610                 <h2>[% item.title.present(view) %]</h2>
611                 [% item.content.present(view) %]
612              [% END %]
613
614              ...
615
616           [% END %]
617
618       A plugin is provided to interface to the Pod::POM module:
619
620           [% USE pod %]
621           [% pom = pod.parse('/path/to/podfile') %]
622
623       The returned Pod Object Model instance can then be navigated and pre‐
624       sented via the view in almost any way imaginable:
625
626           <h1>Table of Contents</h1>
627           <ul>
628           [% FOREACH section = pom.head1 %]
629              <li>[% section.title.present(view) %]
630           [% END %]
631           </ul>
632
633           <hr>
634
635           [% FOREACH section = pom.head1 %]
636              [% section.present(myview) %]
637           [% END %]
638
639       You can either pass a reference to the VIEW (myview) to the present()
640       method of a Pod::POM node:
641
642           [% pom.present(myview) %]       # present entire document
643
644       Or alternately call the print() method on the VIEW, passing the
645       Pod::POM node as an argument:
646
647           [% myview.print(pom) %]
648
649       Internally, the view calls the present() method on the node, passing
650       itself as an argument.  Thus it is equivalent to the previous example.
651
652       The Pod::POM node and the view conspire to "Do The Right Thing" to
653       process the right template block for the node.  A reference to the node
654       is available within the template as the 'item' variable.
655
656          [% BLOCK view_head2 %]
657             <h2>[% item.title.present(view) %]</h2>
658             [% item.content.present(view) %]
659          [% END %]
660
661       The Template Toolkit documentation contains further information on
662       defining and using views.  However, as noted above, this may be subject
663       to change or incomplete pending further development of the VIEW direc‐
664       tive.
665

METHODS

667       new(\%config)
668
669       Constructor method which instantiates and returns a new Pod::POM parser
670       object.
671
672           use Pod::POM;
673
674           my $parser = Pod::POM->new();
675
676       A reference to a hash array of configuration options may be passed as
677       an argument.
678
679           my $parser = Pod::POM->new( { warn => 1 } );
680
681       For convenience, configuration options can also be passed as a list of
682       (key => value) pairs.
683
684           my $parser = Pod::POM->new( warn => 1 );
685
686       The following configuration options are defined:
687
688       code
689           This option can be set to have all non-Pod parts of the input docu‐
690           ment stored within the object model as 'code' elements, represented
691           by objects of the Pod::POM::Node::Code class.  It is disabled by
692           default and code sections are ignored.
693
694               my $parser = Pod::POM->new( code => 1 );
695               my $podpom = $parser->parse(\*DATA);
696
697               foreach my $code ($podpom->code()) {
698                   print "<pre>$code</pre>\n";
699               }
700
701               __DATA__
702               This is some program code.
703
704               =head1 NAME
705
706               ...
707
708           This will generate the output:
709
710               <pre>This is some program code.</pre>
711
712           Note that code elements are stored within the POM element in which
713           they are encountered.  For example, the code element below embedded
714           within between Pod sections is stored in the array which can be
715           retrieved by calling "$podpom->head1->[0]->code()".
716
717               =head1 NAME
718
719               My::Module::Name;
720
721               =cut
722
723               Some program code embedded in Pod.
724
725               =head1 SYNOPSIS
726
727               ...
728
729       warn
730           Non-fatal warnings encountered while parsing a Pod document are
731           stored internally and subsequently available via the warnings()
732           method.
733
734               my $parser = Pod::POM->new();
735               my $podpom = $parser->parse_file($filename);
736
737               foreach my $warning ($parser->warnings()) {
738                   warn $warning, "\n";
739               }
740
741           The 'warn' option can be set to have warnings raised automatically
742           via "warn()" as and when they are encountered.
743
744               my $parser = Pod::POM->new( warn => 1 );
745               my $podpom = $parser->parse_file($filename);
746
747           If the configuration value is specified as a subroutine reference
748           then the code will be called each time a warning is raised, passing
749           the warning message as an argument.
750
751               sub my_warning {
752                   my $msg = shift;
753                   warn $msg, "\n";
754               };
755
756               my $parser = Pod::POM->new( warn => \&my_warning );
757               my $podpom = $parser->parse_file($filename);
758
759       meta
760           The 'meta' option can be set to allow "=meta" tags within the Pod
761           document.
762
763               my $parser = Pod::POM->new( meta => 1 );
764               my $podpom = $parser->parse_file($filename);
765
766           This is an experimental feature which is not part of standard POD.
767           For example:
768
769               =meta author Andy Wardley
770
771           These are made available as metadata items within the root node of
772           the parsed POM.
773
774               my $author = $podpom->metadata('author');
775
776           See the METADATA section below for further information.
777
778       parse_file($file)
779
780       Parses the file specified by name or reference to a file handle.
781       Returns a reference to a Pod::POM::Node::Pod object which represents
782       the root node of the Pod Object Model on success.  On error, undef is
783       returned and the error message generated can be retrieved by calling
784       error().
785
786           my $podpom = $parser->parse_file($filename)
787               ⎪⎪ die $parser->error();
788
789           my $podpom = $parser->parse_file(\*STDIN)
790               ⎪⎪ die $parser->error();
791
792       Any warnings encountered can be examined by calling the warnings()
793       method.
794
795           foreach my $warn ($parser->warnings()) {
796               warn $warn, "\n";
797           }
798
799       parse_text($text)
800
801       Parses the Pod text string passed as an argument into a Pod Object
802       Model, as per parse_file().
803
804       parse($text_or_$file)
805
806       General purpose method which attempts to Do The Right Thing in calling
807       parse_file() or parse_text() according to the argument passed.
808
809       A hash reference can be passed as an argument that contains a 'text' or
810       'file' key and corresponding value.
811
812           my $podpom = $parser->parse({ file => $filename })
813               ⎪⎪ die $parser->error();
814
815       Otherwise, the argument can be a reference to an input handle which is
816       passed off to parse_file().
817
818           my $podpom = $parser->parse(\*DATA)
819               ⎪⎪ die $parser->error();
820
821       If the argument is a text string that looks like Pod text (i.e. it con‐
822       tains '=' at the start of any line) then it is passed to parse_text().
823
824           my $podpom = $parser->parse($podtext)
825               ⎪⎪ die $parser->error();
826
827       Otherwise it is assumed to be a filename and is passed to parse_file().
828
829           my $podpom = $parser->parse($podfile)
830               ⎪⎪ die $parser->error();
831

NODE TYPES, ATTRIBUTES AND ELEMENTS

833       This section lists the different nodes that may be present in a Pod
834       Object Model.  These are implemented as Pod::POM::Node::* object
835       instances (e.g. head1 => Pod::POM::Node::Head1).  To present a node, a
836       view should implement a method which corresponds to the node name pre‐
837       fixed by 'view_' (e.g. head1 => view_head1()).
838
839       pod The "pod" node is used to represent the root node of the Pod Object
840           Model.
841
842           Content elements: head1, head2, head3, head4, over, begin, for,
843           verbatim, text, code.
844
845       head1
846           A "head1" node contains the Pod content from a "=head1" tag up to
847           the next "=head1" tag or the end of the file.
848
849           Attributes: title
850
851           Content elements: head2, head3, head4, over, begin, for, verbatim,
852           text, code.
853
854       head2
855           A "head2" node contains the Pod content from a "=head2" tag up to
856           the next "=head1" or "=head2" tag or the end of the file.
857
858           Attributes: title
859
860           Content elements: head3, head4, over, begin, for, verbatim, text,
861           code.
862
863       head3
864           A "head3" node contains the Pod content from a "=head3" tag up to
865           the next "=head1", "=head2" or "=head3" tag or the end of the file.
866
867           Attributes: title
868
869           Content elements: head4, over, begin, for, verbatim, text, code.
870
871       head4
872           A "head4" node contains the Pod content from a "=head4" tag up to
873           the next "=head1", "=head2", "=head3" or "=head4" tag or the end of
874           the file.
875
876           Attributes: title
877
878           Content elements: over, begin, for, verbatim, text, code.
879
880       over
881           The "over" node encloses the Pod content in a list starting at an
882           "=over" tag and continuing up to the matching "=back" tag.  Lists
883           may be nested indefinately.
884
885           Attributes: indent (default: 4)
886
887           Content elements: over, item, begin, for, verbatim, text, code.
888
889       item
890           The "item" node encloses the Pod content in a list item starting at
891           an "=item" tag and continuing up to the next "=item" tag or a
892           "=back" tag which terminates the list.
893
894           Attributes: title (default: *)
895
896           Content elements: over, begin, for, verbatim, text, code.
897
898       begin
899           A "begin" node encloses the Pod content in a conditional block
900           starting with a "=begin" tag and continuing up to the next "=end"
901           tag.
902
903           Attributes: format
904
905           Content elements: verbatim, text, code.
906
907       for A "for" node contains a single paragraph containing text relevant
908           to a particular format.
909
910           Attributes: format, text
911
912       verbatim
913           A "verbatim" node contains a verbatim text paragraph which is pre‐
914           fixed by whitespace in the source Pod document (i.e. indented).
915
916           Attributes: text
917
918       text
919           A "text" node contains a regular text paragraph.  This may include
920           embedded inline sequences.
921
922           Attributes: text
923
924       code
925           A "code" node contains Perl code which is by default, not consid‐
926           ered to be part of a Pod document.  The "code" configuration option
927           must be set for Pod::POM to generate code blocks, otherwise they
928           are ignored.
929
930           Attributes: text
931

INLINE SEQUENCES

933       Embedded sequences are permitted within regular text blocks (i.e. not
934       verbatim) and title attributes.  To present these sequences, a view
935       should implement methods corresponding to the sequence name, prefixed
936       by 'view_seq_' (e.g. bold => view_seq_bold()).
937
938       code
939           Code extract, e.g. C<my code>
940
941       bold
942           Bold text, e.g. B<bold text>
943
944       italic
945           Italic text, e.g. I<italic text>
946
947       link
948           A link (cross reference), e.g. L<My::Module>
949
950       space
951           Text contains non-breaking space, e.g.S<Buffy The Vampire Slayer>
952
953       file
954           A filename, e.g. F</etc/lilo.conf>
955
956       index
957           An index entry, e.g. X<Angel>
958
959       zero
960           A zero-width character, e.g. Z<>
961
962       entity
963           An entity escape, e.g. E<lt>
964

BUNDLED MODULES AND TOOLS

966       The Pod::POM module distribution includes a number of sample view
967       objects for rendering Pod Object Models into particular formats.  These
968       are incomplete and may require some further work, but serve at present
969       to illustrate the principal and can be used as the basis for your own
970       view objects.
971
972       Pod::POM::View::Pod
973           Regenerates the model as Pod.
974
975       Pod::POM::View::Text
976           Presents the model as plain text.
977
978       Pod::POM::View::HTML
979           Presents the model as HTML.
980
981       A script is provided for converting Pod documents to other format by
982       using the view objects provided.  The "pom2" script should be called
983       with two arguments, the first specifying the output format, the second
984       the input filename.  e.g.
985
986           $ pom2 text My/Module.pm > README
987           $ pom2 html My/Module.pm > ~/public_html/My/Module.html
988
989       You can also create symbolic links to the script if you prefer and
990       leave it to determine the output format from its own name.
991
992           $ ln -s pom2 pom2text
993           $ ln -s pom2 pom2html
994           $ pom2text My/Module.pm > README
995           $ pom2html My/Module.pm > ~/public_html/My/Module.html
996
997       The distribution also contains a trivial script, "podlint" (previously
998       "pomcheck"), which checks a Pod document for well-formedness by simply
999       parsing it into a Pod Object Model with warnings enabled.  Warnings are
1000       printed to STDERR.
1001
1002           $ podlint My/Module.pm
1003
1004       The "-f" option can be set to have the script attempt to fix any prob‐
1005       lems it encounters.  The regenerated Pod output is printed to STDOUT.
1006
1007           $ podlint -f My/Module.pm > newfile
1008

METADATA

1010       This module includes support for an experimental new "=meta" tag.  This
1011       is disabled by default but can be enabled by loading Pod::POM with the
1012       "meta" option.
1013
1014           use Pod::POM qw( meta );
1015
1016       Alternately, you can specify the "meta" option to be any true value
1017       when you instantiate a Pod::POM parser:
1018
1019           my $parser = Pod::POM->new( meta => 1 );
1020           my $pom    = $parser->parse_file($filename);
1021
1022       Any "=meta" tags in the document will be stored as metadata items in
1023       the root node of the Pod model created.
1024
1025       For example:
1026
1027           =meta module Foo::Bar
1028
1029           =meta author Andy Wardley
1030
1031       You can then access these items via the metadata() method.
1032
1033           print "module: ", $pom->metadata('module'), "\n";
1034           print "author: ", $pom->metadata('author'), "\n";
1035
1036       or
1037
1038           my $metadata = $pom->metadata();
1039           print "module: $metadata->{ module }\n";
1040           print "author: $metadata->{ author }\n";
1041
1042       Please note that this is an experimental feature which is not supported
1043       by other POD processors and is therefore likely to be most incompati‐
1044       ble.  Use carefully.
1045

AUTHOR

1047       Andy Wardley <abw@kfs.org>
1048

VERSION

1050       This is version 0.15 of the Pod::POM module.
1051

COPYRIGHT

1053       Copyright (C) 2000-2002 Andy Wardley.  All Rights Reserved.
1054
1055       This module is free software; you can redistribute it and/or modify it
1056       under the same terms as Perl itself.
1057