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

METHODS

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

NODE TYPES, ATTRIBUTES AND ELEMENTS

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

INLINE SEQUENCES

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

BUNDLED MODULES AND TOOLS

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

METADATA

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

AUTHOR

1041       Andy Wardley <abw@kfs.org>
1042
1043       Andrew Ford <A.Ford@ford-mason.co.uk> (co-maintainer as of 03/2009)
1044

COPYRIGHT

1046       Copyright (C) 2000-2009 Andy Wardley.  All Rights Reserved.
1047
1048       This module is free software; you can redistribute it and/or modify it
1049       under the same terms as Perl itself.
1050