POM.pm
Go to the documentation of this file.
00001 #============================================================= -*-Perl-*- 00002 # 00003 # Pod::POM 00004 # 00005 # DESCRIPTION 00006 # Parses POD from a file or text string and builds a tree structure, 00007 # hereafter known as the POD Object Model (POM). 00008 # 00009 # AUTHOR 00010 # Andy Wardley <abw@wardley.org> 00011 # 00012 # Andrew Ford <A.Ford@ford-mason.co.uk> (co-maintainer as of 03/2009) 00013 # 00014 # COPYRIGHT 00015 # Copyright (C) 2000-2009 Andy Wardley. All Rights Reserved. 00016 # Copyright (C) 2009 Andrew Ford. All Rights Reserved. 00017 # 00018 # This module is free software; you can redistribute it and/or 00019 # modify it under the same terms as Perl itself. 00020 # 00021 # REVISION 00022 # $Id: POM.pm 88 2010-04-02 13:37:41Z ford $ 00023 # 00024 #======================================================================== 00025 00026 package BASIS::Pod::POM; 00027 00028 require 5.004; 00029 00030 use strict; 00031 use BASIS::Pod::POM::Constants qw( :all ); 00032 use BASIS::Pod::POM::Nodes; 00033 use BASIS::Pod::POM::View::Pod; 00034 00035 use vars qw( $VERSION $DEBUG $ERROR $ROOT $TEXTSEQ $DEFAULT_VIEW ); 00036 use base qw( Exporter ); 00037 00038 $VERSION = '0.27'; 00039 $DEBUG = 0 unless defined $DEBUG; 00040 $ROOT = 'BASIS::Pod::POM::Node::Pod'; # root node class 00041 $TEXTSEQ = 'BASIS::Pod::POM::Node::Sequence'; # text sequence class 00042 $DEFAULT_VIEW = 'BASIS::Pod::POM::View::Pod'; # default view class 00043 00044 00045 #------------------------------------------------------------------------ 00046 # allow 'meta' to be specified as a load option to activate =meta tags 00047 #------------------------------------------------------------------------ 00048 00049 use vars qw( @EXPORT_FAIL @EXPORT_OK $ALLOW_META ); 00050 @EXPORT_OK = qw( meta ); 00051 @EXPORT_FAIL = qw( meta ); 00052 $ALLOW_META = 0; 00053 00054 sub export_fail { 00055 my $class = shift; 00056 my $meta = shift; 00057 return ($meta, @_) unless $meta eq 'meta'; 00058 $ALLOW_META++; 00059 return @_; 00060 } 00061 00062 00063 00064 #------------------------------------------------------------------------ 00065 # new(\%options) 00066 #------------------------------------------------------------------------ 00067 00068 sub new { 00069 my $class = shift; 00070 my $config = ref $_[0] eq 'HASH' ? shift : { @_ }; 00071 00072 bless { 00073 CODE => $config->{ code } || 0, 00074 WARN => $config->{ warn } || 0, 00075 META => $config->{ meta } || $ALLOW_META, 00076 WARNINGS => [ ], 00077 FILENAME => '', 00078 ERROR => '', 00079 }, $class; 00080 } 00081 00082 00083 #------------------------------------------------------------------------ 00084 # parse($text_or_file) 00085 # 00086 # General purpose parse method which attempts to Do The Right Thing in 00087 # calling parse_file() or parse_text() according to the argument 00088 # passed. A hash reference can be specified that contains a 'text' 00089 # or 'file' key and corresponding value. Otherwise, the argument can 00090 # be a reference to an input handle which is passed off to parse_file(). 00091 # If the argument is a text string that contains '=' at the start of 00092 # any line then it is treated as Pod text and passed to parse_text(), 00093 # otherwise it is assumed to be a filename and passed to parse_file(). 00094 #------------------------------------------------------------------------ 00095 00096 sub parse { 00097 my ($self, $input) = @_; 00098 my $result; 00099 00100 if (ref $input eq 'HASH') { 00101 if ($input = $input->{ text }) { 00102 $result = $self->parse_text($input, $input->{ name }); 00103 } 00104 elsif ($input = $input->{ file }) { 00105 $result = $self->parse_file($input); 00106 } 00107 else { 00108 $result = $self->error("no 'text' or 'file' specified"); 00109 } 00110 } 00111 elsif (ref $input || $input !~ /^=/m) { # doesn't look like POD text 00112 $result = $self->parse_file($input); 00113 } 00114 else { # looks like POD text 00115 $result = $self->parse_text($input); 00116 } 00117 00118 return $result; 00119 } 00120 00121 00122 #------------------------------------------------------------------------ 00123 # parse_file($filename_or_handle) 00124 # 00125 # Reads the content of a Pod file specified by name or file handle, and 00126 # passes it to parse_text() for parsing. 00127 #------------------------------------------------------------------------ 00128 00129 sub parse_file { 00130 my ($self, $file) = @_; 00131 my ($text, $name); 00132 00133 if (ref $file) { # assume open filehandle 00134 local $/ = undef; 00135 $name = '<filehandle>'; 00136 $text = <$file>; 00137 } 00138 else { # a file which must be opened 00139 local *FP; 00140 local $/ = undef; 00141 $name = ( $file eq '-' ? '<standard input>' : $file ); 00142 open(FP, $file) || return $self->error("$file: $!"); 00143 $text = <FP>; 00144 close(FP); 00145 } 00146 00147 $self->parse_text($text, $name); 00148 } 00149 00150 00151 #------------------------------------------------------------------------ 00152 # parse_text($text, $name) 00153 # 00154 # Main parser method. Scans the input text for Pod sections and splits 00155 # them into paragraphs. Builds a tree of Pod::POM::Node::* objects 00156 # to represent the Pod document in object model form. 00157 #------------------------------------------------------------------------ 00158 00159 sub parse_text { 00160 my ($self, $text, $name) = @_; 00161 my ($para, $paralen, $gap, $type, $line, $inpod, $code, $result, $verbatim); 00162 my $warn = $self->{ WARNINGS } = [ ]; 00163 00164 my @stack = ( ); 00165 my $item = $ROOT->new($self); 00166 return $self->error($ROOT->error()) 00167 unless defined $item; 00168 push(@stack, $item); 00169 00170 $name = '<input text>' unless defined $name; 00171 $self->{ FILENAME } = $name; 00172 00173 $code = $self->{ CODE }; 00174 $line = \$self->{ LINE }; 00175 $$line = 1; 00176 $inpod = 0; 00177 00178 my @encchunks = split /^(=encoding.*)/m, $text; 00179 $text = shift @encchunks; 00180 while (@encchunks) { 00181 my($encline,$chunk) = splice @encchunks, 0, 2; 00182 require Encode; 00183 my($encoding) = $encline =~ /^=encoding\s+(\S+)/; 00184 Encode::from_to($chunk, $encoding, "utf8"); 00185 Encode::_utf8_on($chunk); 00186 # $text .= "xxx$encline"; 00187 $text .= $chunk; 00188 } 00189 00190 # patch from JJ 00191 # while ($text =~ /(?:(.*?)(\n{2,}))|(.+$)/sg) { 00192 while ($text =~ /(?:(.*?)((?:\s*\n){2,}))|(.+$)/sg) { 00193 ($para, $gap) = defined $1 ? ($1, $2) : ($3, ''); 00194 00195 if ($para =~ s/^==?(\w+)\s*//) { 00196 $type = $1; 00197 # switch on for =pod or any other =cmd, switch off for =cut 00198 if ($type eq 'pod') { $inpod = 1; next } 00199 elsif ($type eq 'cut') { $inpod = 0; next } 00200 else { $inpod = 1 }; 00201 00202 if ($type eq 'meta') { 00203 $self->{ META } 00204 ? $stack[0]->metadata(split(/\s+/, $para, 2)) 00205 : $self->warning("metadata not allowed", $name, $$line); 00206 next; 00207 } 00208 } 00209 elsif (! $inpod) { 00210 next unless $code; 00211 $type = 'code'; 00212 $para .= $gap; 00213 $gap = ''; 00214 } 00215 elsif ($para =~ /^\s+/) { 00216 $verbatim .= $para; 00217 $verbatim .= $gap; 00218 next; 00219 } 00220 else { 00221 $type = 'text'; 00222 chomp($para); # catches last line in file 00223 } 00224 00225 if ($verbatim) { 00226 while(@stack) { 00227 $verbatim =~ s/\s+$//s; 00228 $result = $stack[-1]->add($self, 'verbatim', $verbatim); 00229 00230 if (! defined $result) { 00231 $self->warning($stack[-1]->error(), $name, $$line); 00232 undef $verbatim; 00233 last; 00234 } 00235 elsif (ref $result) { 00236 push(@stack, $result); 00237 undef $verbatim; 00238 last; 00239 } 00240 elsif ($result == REDUCE) { 00241 pop @stack; 00242 undef $verbatim; 00243 last; 00244 } 00245 elsif ($result == REJECT) { 00246 $self->warning($stack[-1]->error(), $name, $$line); 00247 pop @stack; 00248 } 00249 elsif (@stack == 1) { 00250 $self->warning("unexpected $type", $name, $$line); 00251 undef $verbatim; 00252 last; 00253 } 00254 else { 00255 pop @stack; 00256 } 00257 } 00258 } 00259 00260 while(@stack) { 00261 $result = $stack[-1]->add($self, $type, $para); 00262 00263 if (! defined $result) { 00264 $self->warning($stack[-1]->error(), $name, $$line); 00265 last; 00266 } 00267 elsif (ref $result) { 00268 push(@stack, $result); 00269 last; 00270 } 00271 elsif ($result == REDUCE) { 00272 pop @stack; 00273 last; 00274 } 00275 elsif ($result == REJECT) { 00276 $self->warning($stack[-1]->error(), $name, $$line); 00277 pop @stack; 00278 } 00279 elsif (@stack == 1) { 00280 $self->warning("unexpected $type", $name, $$line); 00281 last; 00282 } 00283 else { 00284 pop @stack; 00285 } 00286 } 00287 } 00288 continue { 00289 $$line += ($para =~ tr/\n//); 00290 $$line += ($gap =~ tr/\n//); 00291 } 00292 00293 if ($verbatim) { 00294 while(@stack) { 00295 $verbatim =~ s/\s+$//s; 00296 $result = $stack[-1]->add($self, 'verbatim', $verbatim); 00297 00298 if (! defined $result) { 00299 $self->warning($stack[-1]->error(), $name, $$line); 00300 undef $verbatim; 00301 last; 00302 } 00303 elsif (ref $result) { 00304 push(@stack, $result); 00305 undef $verbatim; 00306 last; 00307 } 00308 elsif ($result == REDUCE) { 00309 pop @stack; 00310 undef $verbatim; 00311 last; 00312 } 00313 elsif ($result == REJECT) { 00314 $self->warning($stack[-1]->error(), $name, $$line); 00315 pop @stack; 00316 } 00317 elsif (@stack == 1) { 00318 $self->warning("unexpected $type", $name, $$line); 00319 undef $verbatim; 00320 last; 00321 } 00322 else { 00323 pop @stack; 00324 } 00325 } 00326 } 00327 00328 return $stack[0]; 00329 } 00330 00331 00332 #------------------------------------------------------------------------ 00333 # parse_sequence($text) 00334 # 00335 # Parse a text paragraph to identify internal sequences (e.g. B<foo>) 00336 # which may be nested within each other. Returns a simple scalar (no 00337 # embedded sequences) or a reference to a Pod::POM::Text object. 00338 #------------------------------------------------------------------------ 00339 00340 sub parse_sequence { 00341 my ($self, $text) = @_; 00342 my ($cmd, $lparen, $rparen, $plain); 00343 my ($name, $line, $warn) = @$self{ qw( FILENAME LINE WARNINGS ) }; 00344 my @stack; 00345 00346 push(@stack, [ '', '', 'EOF', $name, $line, [ ] ] ); 00347 00348 while ($text =~ / 00349 (?: ([A-Z]) (< (?:<+\s)?) ) # open 00350 | ( (?:\s>+)? > ) # or close 00351 | (?: (.+?) # or text... 00352 (?= # ...up to 00353 (?: [A-Z]< ) # open 00354 | (?: (?: \s>+)? > ) # or close 00355 | $ # or EOF 00356 ) 00357 ) 00358 /gxs) { 00359 if (defined $1) { 00360 ($cmd, $lparen) = ($1, $2); 00361 $lparen =~ s/\s$//; 00362 ($rparen = $lparen) =~ tr/</>/; 00363 push(@stack, [ $cmd, $lparen, $rparen, $name, $line, [ ] ]); 00364 } 00365 elsif (defined $3) { 00366 $rparen = $3; 00367 $rparen =~ s/^\s+//; 00368 if ($rparen eq $stack[-1]->[RPAREN]) { 00369 $cmd = $TEXTSEQ->new(pop(@stack)) 00370 || return $self->error($TEXTSEQ->error()); 00371 push(@{ $stack[-1]->[CONTENT] }, $cmd); 00372 } 00373 else { 00374 $self->warning((scalar @stack > 1 00375 ? "expected '$stack[-1]->[RPAREN]' not '$rparen'" 00376 : "spurious '$rparen'"), $name, $line); 00377 push(@{ $stack[-1]->[CONTENT] }, $rparen); 00378 } 00379 } 00380 elsif (defined $4) { 00381 $plain = $4; 00382 push(@{ $stack[-1]->[CONTENT] }, $plain); 00383 $line += ($plain =~ tr/\n//); 00384 } 00385 else { 00386 $self->warning("unexpected end of input", $name, $line); 00387 last; 00388 } 00389 } 00390 00391 while (@stack > 1) { 00392 $cmd = pop @stack; 00393 $self->warning("unterminated '$cmd->[CMD]$cmd->[LPAREN]' starting", 00394 $name, $cmd->[LINE]); 00395 $cmd = $TEXTSEQ->new($cmd) 00396 || $self->error($TEXTSEQ->error()); 00397 push(@{ $stack[-1]->[CONTENT] }, $cmd); 00398 } 00399 00400 return $TEXTSEQ->new(pop(@stack)) 00401 || $self->error($TEXTSEQ->error()); 00402 } 00403 00404 00405 #------------------------------------------------------------------------ 00406 # default_view($viewer) 00407 # 00408 # Accessor method to return or update the $DEFVIEW package variable, 00409 # loading the module for any package name specified. 00410 #------------------------------------------------------------------------ 00411 00412 sub default_view { 00413 my ($self, $viewer) = @_; 00414 return $DEFAULT_VIEW unless $viewer; 00415 unless (ref $viewer) { 00416 my $file = $viewer; 00417 $file =~ s[::][/]g; 00418 $file .= '.pm'; 00419 eval { require $file }; 00420 return $self->error($@) if $@; 00421 } 00422 00423 return ($DEFAULT_VIEW = $viewer); 00424 } 00425 00426 00427 #------------------------------------------------------------------------ 00428 # warning($msg, $file, $line) 00429 # 00430 # Appends a string of the form " at $file line $line" to $msg if 00431 # $file is specified and then stores $msg in the internals 00432 # WARNINGS list. If the WARN option is set then the warning is 00433 # raised, either via warn(), or by dispatching to a subroutine 00434 # when WARN is defined as such. 00435 #------------------------------------------------------------------------ 00436 00437 sub warning { 00438 my ($self, $msg, $file, $line) = @_; 00439 my $warn = $self->{ WARN }; 00440 $line = 'unknown' unless defined $line && length $line; 00441 $msg .= " at $file line $line" if $file; 00442 00443 push(@{ $self->{ WARNINGS } }, $msg); 00444 00445 if (ref $warn eq 'CODE') { 00446 &$warn($msg); 00447 } 00448 elsif ($warn) { 00449 warn($msg, "\n"); 00450 } 00451 } 00452 00453 00454 #------------------------------------------------------------------------ 00455 # warnings() 00456 # 00457 # Returns a reference to the (possibly empty) list of warnings raised by 00458 # the most recent call to any of the parse_XXX() methods 00459 #------------------------------------------------------------------------ 00460 00461 sub warnings { 00462 my $self = shift; 00463 return wantarray ? @{ $self->{ WARNINGS } } : $self->{ WARNINGS }; 00464 } 00465 00466 00467 #------------------------------------------------------------------------ 00468 # error($msg) 00469 # 00470 # Sets the internal ERROR member and returns undef when called with an 00471 # argument(s), returns the current value when called without. 00472 #------------------------------------------------------------------------ 00473 00474 sub error { 00475 my $self = shift; 00476 my $errvar; 00477 00478 { 00479 no strict qw( refs ); 00480 if (ref $self) { 00481 $errvar = \$self->{ ERROR }; 00482 } 00483 else { 00484 $errvar = \${"$self\::ERROR"}; 00485 } 00486 } 00487 if (@_) { 00488 $$errvar = ref($_[0]) ? shift : join('', @_); 00489 return undef; 00490 } 00491 else { 00492 return $$errvar; 00493 } 00494 } 00495 00496 00497 00498 sub DEBUG { 00499 print STDERR "DEBUG: ", @_ if $DEBUG; 00500 } 00501 00502 1; 00503 00504 __END__ 00505 00506 =head1 NAME 00507 00508 Pod::POM - POD Object Model 00509 00510 =head1 SYNOPSIS 00511 00512 use Pod::POM; 00513 00514 my $parser = Pod::POM->new(\%options); 00515 00516 # parse from a text string 00517 my $pom = $parser->parse_text($text) 00518 || die $parser->error(); 00519 00520 # parse from a file specified by name or filehandle 00521 my $pom = $parser->parse_file($file) 00522 || die $parser->error(); 00523 00524 # parse from text or file 00525 my $pom = $parser->parse($text_or_file) 00526 || die $parser->error(); 00527 00528 # examine any warnings raised 00529 foreach my $warning ($parser->warnings()) { 00530 warn $warning, "\n"; 00531 } 00532 00533 # print table of contents using each =head1 title 00534 foreach my $head1 ($pom->head1()) { 00535 print $head1->title(), "\n"; 00536 } 00537 00538 # print each section 00539 foreach my $head1 ($pom->head1()) { 00540 print $head1->title(), "\n"; 00541 print $head1->content(); 00542 } 00543 00544 # print the entire document as HTML 00545 use Pod::POM::View::HTML; 00546 print Pod::POM::View::HTML->print($pom); 00547 00548 # create custom view 00549 package My::View; 00550 use base qw( Pod::POM::View::HTML ); 00551 00552 sub view_head1 { 00553 my ($self, $item) = @_; 00554 return '<h1>', 00555 $item->title->present($self), 00556 "</h1>\n", 00557 $item->content->present($self); 00558 } 00559 00560 package main; 00561 print My::View->print($pom); 00562 00563 =head1 DESCRIPTION 00564 00565 This module implements a parser to convert Pod documents into a simple 00566 object model form known hereafter as the Pod Object Model. The object 00567 model is generated as a hierarchical tree of nodes, each of which 00568 represents a different element of the original document. The tree can 00569 be walked manually and the nodes examined, printed or otherwise 00570 manipulated. In addition, Pod::POM supports and provides view objects 00571 which can automatically traverse the tree, or section thereof, and 00572 generate an output representation in one form or another. 00573 00574 Let's look at a typical Pod document by way of example. 00575 00576 =head1 NAME 00577 00578 My::Module - just another My::Module 00579 00580 =head1 DESCRIPTION 00581 00582 This is My::Module, a deeply funky piece of Perl code. 00583 00584 =head2 METHODS 00585 00586 My::Module implements the following methods 00587 00588 =over 4 00589 00590 =item new(\%config) 00591 00592 This is the constructor method. It accepts the following 00593 configuration options: 00594 00595 =over 4 00596 00597 =item name 00598 00599 The name of the thingy. 00600 00601 =item colour 00602 00603 The colour of the thingy. 00604 00605 =back 00606 00607 =item print() 00608 00609 This prints the thingy. 00610 00611 =back 00612 00613 =head1 AUTHOR 00614 00615 My::Module was written by me E<lt>me@here.orgE<gt> 00616 00617 This document contains 3 main sections, NAME, DESCRIPTION and 00618 AUTHOR, each of which is delimited by an opening C<=head1> tag. 00619 NAME and AUTHOR each contain only a single line of text, but 00620 DESCRIPTION is more interesting. It contains a line of text 00621 followed by the C<=head2> subsection, METHODS. This contains 00622 a line of text and a list extending from the C<=over 4> to the 00623 final C<=back> just before the AUTHOR section starts. The list 00624 contains 2 items, C<new(\%config)>, which itself contains some 00625 text and a list of 2 items, and C<print()>. 00626 00627 Presented as plain text and using indentation to indicate the element 00628 nesting, the model then looks something like this : 00629 00630 NAME 00631 My::Module - just another My::Module 00632 00633 DESCRIPTION 00634 This is My::Module, a deeply funky piece of Perl code. 00635 00636 METHODS 00637 My::Module implements the following methods 00638 00639 * new(\%config) 00640 This is the constructor method. It accepts the 00641 following configuration options: 00642 00643 * name 00644 The name of the thingy. 00645 00646 * colour 00647 The colour of the thingy. 00648 00649 * item print() 00650 This prints the thingy. 00651 00652 AUTHOR 00653 My::Myodule was written by me <me@here.org> 00654 00655 Those of you familiar with XML may prefer to think of it in the 00656 following way: 00657 00658 <pod> 00659 <head1 title="NAME"> 00660 <p>My::Module - just another My::Module</p> 00661 </head1> 00662 00663 <head1 title="DESCRIPTION"> 00664 <p>This is My::Module, a deeply funky piece of 00665 Perl code.</p> 00666 00667 <head2 title="METHODS"> 00668 <p>My::Module implements the following methods</p> 00669 00670 <over indent=4> 00671 <item title="item new(\%config)"> 00672 <p>This is the constructor method. It accepts 00673 the following configuration options:</p> 00674 00675 <over indent=4> 00676 <item title="name"> 00677 <p>The name of the thingy.</p> 00678 </item> 00679 00680 <item title="colour"> 00681 <p>The colour of the thingy.</p> 00682 </item> 00683 </over> 00684 </item> 00685 00686 <item title="print()"> 00687 <p>This prints the thingy.</p> 00688 </item> 00689 </over> 00690 </head2> 00691 </head1> 00692 00693 <head1 title="AUTHOR"> 00694 <p>My::Myodule was written by me <me@here.org> 00695 </head1> 00696 </pod> 00697 00698 Notice how we can make certain assumptions about various elements. 00699 For example, we can assume that any C<=head1> section we find begins a 00700 new section and implicitly ends any previous section. Similarly, we 00701 can assume an C<=item> ends when the next one begins, and so on. In 00702 terms of the XML example shown above, we are saying that we're smart 00703 enough to add a C<E<lt>/head1E<gt>> element to terminate any 00704 previously opened C<E<lt>head1E<gt>> when we find a new C<=head1> tag 00705 in the input document. 00706 00707 However you like to visualise the content, it all comes down to the 00708 same underlying model. The job of the Pod::POM module is to read an 00709 input Pod document and build an object model to represent it in this 00710 structured form. 00711 00712 Each node in the tree (i.e. element in the document) is represented 00713 by a Pod::POM::Node::* object. These encapsulate the attributes for 00714 an element (such as the title for a C<=head1> tag) and also act as 00715 containers for further Pod::POM::Node::* objects representing the 00716 content of the element. Right down at the leaf nodes, we have simple 00717 object types to represent formatted and verbatim text paragraphs and 00718 other basic elements like these. 00719 00720 =head2 Parsing Pod 00721 00722 The Pod::POM module implements the methods parse_file($file), 00723 parse_text($text) and parse($file_or_text) to parse Pod files and 00724 input text. They return a Pod::POM::Node::Pod object to represent the 00725 root of the Pod Object Model, effectively the C<E<lt>podE<gt>> element 00726 in the XML tree shown above. 00727 00728 use Pod::POM; 00729 00730 my $parser = Pod::POM->new(); 00731 my $pom = $parser->parse_file($filename) 00732 || die $parser->error(); 00733 00734 The parse(), parse_text() and parse_file() methods return 00735 undef on error. The error() method can be called to retrieve the 00736 error message generated. Parsing a document may also generate 00737 non-fatal warnings. These can be retrieved via the warnings() method 00738 which returns a reference to a list when called in scalar context or a 00739 list of warnings when called in list context. 00740 00741 foreach my $warn ($parser->warnings()) { 00742 warn $warn, "\n"; 00743 } 00744 00745 Alternatively, the 'warn' configuration option can be set to have 00746 warnings automatically raised via C<warn()> as they are encountered. 00747 00748 my $parser = Pod::POM->new( warn => 1 ); 00749 00750 =head2 Walking the Object Model 00751 00752 Having parsed a document into an object model, we can then select 00753 various items from it. Each node implements methods (via AUTOLOAD) 00754 which correspond to the attributes and content elements permitted 00755 within in. 00756 00757 So to fetch the list of '=head1' sections within our parsed document, 00758 we would do the following: 00759 00760 my $sections = $pom->head1(); 00761 00762 Methods like this will return a list of further Pod::POM::Node::* 00763 objects when called in list context or a reference to a list when 00764 called in scalar context. In the latter case, the list is blessed 00765 into the Pod::POM::Node::Content class which gives it certain 00766 magical properties (more on that later). 00767 00768 Given the list of Pod::POM::Node::Head1 objects returned by the above, 00769 we can print the title attributes of each like this: 00770 00771 foreach my $s (@$sections) { 00772 print $s->title(); 00773 } 00774 00775 Let's look at the second section, DESCRIPTION. 00776 00777 my $desc = $sections->[1]; 00778 00779 We can print the title of each subsection within it: 00780 00781 foreach my $ss ($desc->head2()) { 00782 print $ss->title(); 00783 } 00784 00785 Hopefully you're getting the idea by now, so here's a more studly 00786 example to print the title for each item contained in the first list 00787 within the METHODS section: 00788 00789 foreach my $item ($desc->head2->[0]->over->[0]->item) { 00790 print $item->title(), "\n"; 00791 } 00792 00793 =head2 Element Content 00794 00795 This is all well and good if you know the precise structure of a 00796 document in advance. For those more common cases when you don't, 00797 each node that can contain other nodes provides a 'content' method 00798 to return a complete list of all the other nodes that it contains. 00799 The 'type' method can be called on any node to return its element 00800 type (e.g. 'head1', 'head2', 'over', item', etc). 00801 00802 foreach my $item ($pom->content()) { 00803 my $type = $item->type(); 00804 if ($type eq 'head1') { 00805 ... 00806 } 00807 elsif ($type eq 'head2') { 00808 ... 00809 } 00810 ... 00811 } 00812 00813 The content for an element is represented by a reference to a list, 00814 blessed into the Pod::POM::Node::Content class. This provides some 00815 magic in the form of an overloaded stringification operator which 00816 will automatically print the contents of the list if you print 00817 the object itself. In plain English, or rather, in plain Perl, 00818 this means you can do things like the following: 00819 00820 foreach my $head1 ($pom->head1()) { 00821 print '<h1>', $head1->title(), "</h1>\n\n"; 00822 print $head1->content(); 00823 } 00824 00825 # print all the root content 00826 foreach my $item ($pom->content()) { 00827 print $item; 00828 } 00829 00830 # same as above 00831 print $pom->content(); 00832 00833 In fact, all Pod::POM::Node::* objects provide this same magic, and 00834 will attempt to Do The Right Thing to present themselves in the 00835 appropriate manner when printed. Thus, the following are all valid. 00836 00837 print $pom; # entire document 00838 print $pom->content; # content of document 00839 print $pom->head1->[0]; # just first section 00840 print $pom->head1; # print all sections 00841 foreach my $h1 ($pom->head1()) { 00842 print $h1->head2(); # print all subsections 00843 } 00844 00845 =head2 Output Views 00846 00847 To understand how the different elements go about presenting 00848 themselves in "the appropriate manner", we must introduce the concept 00849 of a view. A view is quite simply a particular way of looking at the 00850 model. In real terms, we can think of a view as being some kind of 00851 output type generated by a pod2whatever converter. Notionally we can 00852 think in terms of reading in an input document, building a Pod Object 00853 Model, and then generating an HTML view of the document, and/or a 00854 LaTeX view, a plain text view, and so on. 00855 00856 A view is represented in this case by an object class which contains 00857 methods for displaying each of the different element types that could 00858 be encountered in any Pod document. There's a method for displaying 00859 C<=head1> sections (view_head1()), another method for displaying 00860 C<=head2> sections (view_head2()), one for C<=over> (view_over()), 00861 another for C<=item> (view_item()) and so on. 00862 00863 If we happen to have a reference to a $node and we know it's a 'head1' 00864 node, then we can directly call the right view method to have it 00865 displayed properly: 00866 00867 $view = 'Pod::POM::View::HTML'; 00868 $view->view_head1($node); 00869 00870 Thus our earlier example can be modified to be I<slightly> less laborious 00871 and I<marginally> more flexible. 00872 00873 foreach my $node ($pom->content) { 00874 my $type = $node->type(); 00875 if ($type eq 'head1') { 00876 print $view->view_head1($node); 00877 } 00878 elsif ($type eq 'head2') { 00879 print $view->view_head2($node); 00880 } 00881 ... 00882 } 00883 00884 However, this is still far from ideal. To make life easier, each 00885 Pod::POM::Node::* class inherits (or possibly redefines) a 00886 C<present($view)> method from the Pod::POM::Node base class. This method 00887 expects a reference to a view object passed as an argument, and it 00888 simply calls the appropriate view_xxx() method on the view object, 00889 passing itself back as an argument. In object parlance, this is known 00890 as "double dispatch". The beauty of it is that you don't need to know 00891 what kind of node you have to be able to print it. You simply pass 00892 it a view object and leave it to work out the rest. 00893 00894 foreach my $node ($pom->content) { 00895 print $node->present($view); 00896 } 00897 00898 If $node is a Pod::POM::Node::Head1 object, then the view_head1($node) 00899 method gets called against the $view object. Otherwise, if it's a 00900 Pod::POM::Node::Head2 object, then the view_head2($node) method is 00901 dispatched. And so on, and so on, with each node knowing what it is 00902 and where it's going as if determined by some genetically pre-programmed 00903 instinct. Fullfilling their destinies, so to speak. 00904 00905 Double dispatch allows us to do away with all the explicit type 00906 checking and other nonsense and have the node objects themselves worry 00907 about where they should be routed to. At the cost of an extra method 00908 call per node, we get programmer convenience, and that's usually 00909 a Good Thing. 00910 00911 Let's have a look at how the view and node classes might be 00912 implemented. 00913 00914 package Pod::POM::View::HTML; 00915 00916 sub view_pod { 00917 my ($self, $node) = @_; 00918 return $node->content->present($self); 00919 } 00920 00921 sub view_head1 { 00922 my ($self, $node) = @_; 00923 return "<h1>", $node->title->present($self), "</h1>\n\n" 00924 . $node->content->present($self); 00925 } 00926 00927 sub view_head2 { 00928 my ($self, $node) = @_; 00929 return "<h2>", $node->title->present($self), "</h2>\n\n" 00930 . $node->content->present($self); 00931 } 00932 00933 ... 00934 00935 package Pod::POM::Node::Pod; 00936 00937 sub present { 00938 my ($self, $view) = @_; 00939 $view->view_pod($self); 00940 } 00941 00942 package Pod::POM::Node::Head1; 00943 00944 sub present { 00945 my ($self, $view) = @_; 00946 $view->view_head1($self); 00947 } 00948 00949 package Pod::POM::Node::Head2; 00950 00951 sub present { 00952 my ($self, $view) = @_; 00953 $view->view_head2($self); 00954 } 00955 00956 ... 00957 00958 Some of the view_xxx methods make calls back against the node objects 00959 to display their attributes and/or content. This is shown in, for 00960 example, the view_head1() method above, where the method prints the 00961 section title in C<E<lt>h1E<gt>>...C<E<lt>h1E<gt>> tags, followed by 00962 the remaining section content. 00963 00964 Note that the title() attribute is printed by calling its present() 00965 method, passing on the reference to the current view. Similarly, 00966 the content present() method is called giving it a chance to Do 00967 The Right Thing to present itself correctly via the view object. 00968 00969 There's a good chance that the title attribute is going to be regular 00970 text, so we might be tempted to simply print the title rather than 00971 call its present method. 00972 00973 sub view_head1 { 00974 my ($self, $node) = @_; 00975 # not recommended, prefer $node->title->present($self) 00976 return "<h1>", $node->title(), "</h1>\n\n", ... 00977 } 00978 00979 However, it is entirely valid for titles and other element attributes, 00980 as well as regular, formatted text blocks to contain code sequences, 00981 such like C<BE<lt>thisE<gt>> and C<IE<lt>thisE<gt>>. These are used 00982 to indicate different markup styles, mark external references or index 00983 items, and so on. What's more, they can be C<BE<lt>nested 00984 IE<lt>indefinatelyE<gt>E<gt>>. Pod::POM takes care of all this by 00985 parsing such text, along with any embedded sequences, into Yet Another 00986 Tree, the root node of which is a Pod::POM::Node::Text object, 00987 possibly containing other Pod::POM::Node::Sequence objects. When the 00988 text is presented, the tree is automatically walked and relevant 00989 callbacks made against the view for the different sequence types. The 00990 methods called against the view are all prefixed 'view_seq_', e.g. 00991 'view_seq_bold', 'view_seq_italic'. 00992 00993 Now the real magic comes into effect. You can define one view to 00994 render bold/italic text in one style: 00995 00996 package My::View::Text; 00997 use base qw( Pod::POM::View::Text ); 00998 00999 sub view_seq_bold { 01000 my ($self, $text) = @_; 01001 return "*$text*"; 01002 } 01003 01004 sub view_seq_italic { 01005 my ($self, $text) = @_; 01006 return "_$text_"; 01007 } 01008 01009 And another view to render it in a different style: 01010 01011 package My::View::HTML; 01012 use base qw( Pod::POM::View::HTML ); 01013 01014 sub view_seq_bold { 01015 my ($self, $text) = @_; 01016 return "<b>$text</b>"; 01017 } 01018 01019 sub view_seq_italic { 01020 my ($self, $text) = @_; 01021 return "<i>$text</i>"; 01022 } 01023 01024 Then, you can easily view a Pod Object Model in either style: 01025 01026 my $text = 'My::View::Text'; 01027 my $html = 'My::View::HTML'; 01028 01029 print $pom->present($text); 01030 print $pom->present($html); 01031 01032 And you can apply this technique to any node within the object 01033 model. 01034 01035 print $pom->head1->[0]->present($text); 01036 print $pom->head1->[0]->present($html); 01037 01038 In these examples, the view passed to the present() method has 01039 been a class name. Thus, the view_xxx methods get called as 01040 class methods, as if written: 01041 01042 My::View::Text->view_head1(...); 01043 01044 If your view needs to maintain state then you can create a view object 01045 and pass that to the present() method. 01046 01047 my $view = My::View->new(); 01048 $node->present($view); 01049 01050 In this case the view_xxx methods get called as object methods. 01051 01052 sub view_head1 { 01053 my ($self, $node) = @_; 01054 my $title = $node->title(); 01055 if ($title eq 'NAME' && ref $self) { 01056 $self->{ title } = $title(); 01057 } 01058 $self->SUPER::view_head1($node); 01059 } 01060 01061 Whenever you print a Pod::POM::Node::* object, or do anything to cause 01062 Perl to stringify it (such as including it another quoted string "like 01063 $this"), then its present() method is automatically called. When 01064 called without a view argument, the present() method uses the default 01065 view specified in $Pod::POM::DEFAULT_VIEW, which is, by default, 01066 'Pod::POM::View::Pod'. This view regenerates the original Pod 01067 document, although it should be noted that the output generated may 01068 not be exactly the same as the input. The parser is smart enough to 01069 detect some common errors (e.g. not terminating an C<=over> with a C<=back>) 01070 and correct them automatically. Thus you might find a C<=back> 01071 correctly placed in the output, even if you forgot to add it to the 01072 input. Such corrections raise non-fatal warnings which can later 01073 be examined via the warnings() method. 01074 01075 You can update the $Pod::POM::DEFAULT_VIEW package variable to set the 01076 default view, or call the default_view() method. The default_view() 01077 method will automatically load any package you specify. If setting 01078 the package variable directly, you should ensure that any packages 01079 required have been pre-loaded. 01080 01081 use My::View::HTML; 01082 $Pod::POM::DEFAULT_VIEW = 'My::View::HTML'; 01083 01084 or 01085 01086 Pod::POM->default_view('My::View::HTML'); 01087 01088 =head2 Template Toolkit Views 01089 01090 One of the motivations for writing this module was to make it easier 01091 to customise Pod documentation to your own look and feel or local 01092 formatting conventions. By clearly separating the content 01093 (represented by the Pod Object Model) from the presentation style 01094 (represented by one or more views) it becomes much easier to achieve 01095 this. 01096 01097 The latest version of the Template Toolkit (2.06 at the time of 01098 writing) provides a Pod plugin to interface to this module. It also 01099 implements a new (but experimental) VIEW directive which can be used 01100 to build different presentation styles for converting Pod to other 01101 formats. The Template Toolkit is available from CPAN: 01102 01103 http://www.cpan.org/modules/by-module/Template/ 01104 01105 Template Toolkit views are similar to the Pod::POM::View objects 01106 described above, except that they allow the presentation style for 01107 each Pod component to be written as a template file or block rather 01108 than an object method. The precise syntax and structure of the VIEW 01109 directive is subject to change (given that it's still experimental), 01110 but at present it can be used to define a view something like this: 01111 01112 [% VIEW myview %] 01113 01114 [% BLOCK view_head1 %] 01115 <h1>[% item.title.present(view) %]</h1> 01116 [% item.content.present(view) %] 01117 [% END %] 01118 01119 [% BLOCK view_head2 %] 01120 <h2>[% item.title.present(view) %]</h2> 01121 [% item.content.present(view) %] 01122 [% END %] 01123 01124 ... 01125 01126 [% END %] 01127 01128 A plugin is provided to interface to the Pod::POM module: 01129 01130 [% USE pod %] 01131 [% pom = pod.parse('/path/to/podfile') %] 01132 01133 The returned Pod Object Model instance can then be navigated and 01134 presented via the view in almost any way imaginable: 01135 01136 <h1>Table of Contents</h1> 01137 <ul> 01138 [% FOREACH section = pom.head1 %] 01139 <li>[% section.title.present(view) %] 01140 [% END %] 01141 </ul> 01142 01143 <hr> 01144 01145 [% FOREACH section = pom.head1 %] 01146 [% section.present(myview) %] 01147 [% END %] 01148 01149 You can either pass a reference to the VIEW (myview) to the 01150 present() method of a Pod::POM node: 01151 01152 [% pom.present(myview) %] # present entire document 01153 01154 Or alternately call the print() method on the VIEW, passing the 01155 Pod::POM node as an argument: 01156 01157 [% myview.print(pom) %] 01158 01159 Internally, the view calls the present() method on the node, 01160 passing itself as an argument. Thus it is equivalent to the 01161 previous example. 01162 01163 The Pod::POM node and the view conspire to "Do The Right Thing" to 01164 process the right template block for the node. A reference to the 01165 node is available within the template as the 'item' variable. 01166 01167 [% BLOCK view_head2 %] 01168 <h2>[% item.title.present(view) %]</h2> 01169 [% item.content.present(view) %] 01170 [% END %] 01171 01172 The Template Toolkit documentation contains further information on 01173 defining and using views. However, as noted above, this may be 01174 subject to change or incomplete pending further development of the 01175 VIEW directive. 01176 01177 =head1 METHODS 01178 01179 =head2 new(\%config) 01180 01181 Constructor method which instantiates and returns a new Pod::POM 01182 parser object. 01183 01184 use Pod::POM; 01185 01186 my $parser = Pod::POM->new(); 01187 01188 A reference to a hash array of configuration options may be passed as 01189 an argument. 01190 01191 my $parser = Pod::POM->new( { warn => 1 } ); 01192 01193 For convenience, configuration options can also be passed as a list of 01194 (key =E<gt> value) pairs. 01195 01196 my $parser = Pod::POM->new( warn => 1 ); 01197 01198 The following configuration options are defined: 01199 01200 =over 4 01201 01202 =item code 01203 01204 This option can be set to have all non-Pod parts of the input document 01205 stored within the object model as 'code' elements, represented by 01206 objects of the Pod::POM::Node::Code class. It is disabled by default 01207 and code sections are ignored. 01208 01209 my $parser = Pod::POM->new( code => 1 ); 01210 my $podpom = $parser->parse(\*DATA); 01211 01212 foreach my $code ($podpom->code()) { 01213 print "<pre>$code</pre>\n"; 01214 } 01215 01216 __DATA__ 01217 This is some program code. 01218 01219 =head1 NAME 01220 01221 ... 01222 01223 This will generate the output: 01224 01225 <pre>This is some program code.</pre> 01226 01227 Note that code elements are stored within the POM element in which 01228 they are encountered. For example, the code element below embedded 01229 within between Pod sections is stored in the array which can be 01230 retrieved by calling C<$podpom-E<gt>head1-E<gt>[0]-E<gt>code()>. 01231 01232 =head1 NAME 01233 01234 My::Module::Name; 01235 01236 =cut 01237 01238 Some program code embedded in Pod. 01239 01240 =head1 SYNOPSIS 01241 01242 ... 01243 01244 =item warn 01245 01246 Non-fatal warnings encountered while parsing a Pod document are stored 01247 internally and subsequently available via the warnings() method. 01248 01249 my $parser = Pod::POM->new(); 01250 my $podpom = $parser->parse_file($filename); 01251 01252 foreach my $warning ($parser->warnings()) { 01253 warn $warning, "\n"; 01254 } 01255 01256 The 'warn' option can be set to have warnings raised automatically 01257 via C<warn()> as and when they are encountered. 01258 01259 my $parser = Pod::POM->new( warn => 1 ); 01260 my $podpom = $parser->parse_file($filename); 01261 01262 If the configuration value is specified as a subroutine reference then 01263 the code will be called each time a warning is raised, passing the 01264 warning message as an argument. 01265 01266 sub my_warning { 01267 my $msg = shift; 01268 warn $msg, "\n"; 01269 }; 01270 01271 my $parser = Pod::POM->new( warn => \&my_warning ); 01272 my $podpom = $parser->parse_file($filename); 01273 01274 =item meta 01275 01276 The 'meta' option can be set to allow C<=meta> tags within the Pod 01277 document. 01278 01279 my $parser = Pod::POM->new( meta => 1 ); 01280 my $podpom = $parser->parse_file($filename); 01281 01282 This is an experimental feature which is not part of standard 01283 POD. For example: 01284 01285 =meta author Andy Wardley 01286 01287 These are made available as metadata items within the root 01288 node of the parsed POM. 01289 01290 my $author = $podpom->metadata('author'); 01291 01292 See the L<METADATA|METADATA> section below for further information. 01293 01294 =back 01295 01296 =head2 parse_file($file) 01297 01298 Parses the file specified by name or reference to a file handle. 01299 Returns a reference to a Pod::POM::Node::Pod object which represents 01300 the root node of the Pod Object Model on success. On error, undef 01301 is returned and the error message generated can be retrieved by calling 01302 error(). 01303 01304 my $podpom = $parser->parse_file($filename) 01305 || die $parser->error(); 01306 01307 my $podpom = $parser->parse_file(\*STDIN) 01308 || die $parser->error(); 01309 01310 Any warnings encountered can be examined by calling the 01311 warnings() method. 01312 01313 foreach my $warn ($parser->warnings()) { 01314 warn $warn, "\n"; 01315 } 01316 01317 =head2 parse_text($text) 01318 01319 Parses the Pod text string passed as an argument into a Pod Object 01320 Model, as per parse_file(). 01321 01322 =head2 parse($text_or_$file) 01323 01324 General purpose method which attempts to Do The Right Thing in calling 01325 parse_file() or parse_text() according to the argument passed. 01326 01327 A hash reference can be passed as an argument that contains a 'text' 01328 or 'file' key and corresponding value. 01329 01330 my $podpom = $parser->parse({ file => $filename }) 01331 || die $parser->error(); 01332 01333 Otherwise, the argument can be a reference to an input handle which is 01334 passed off to parse_file(). 01335 01336 my $podpom = $parser->parse(\*DATA) 01337 || die $parser->error(); 01338 01339 If the argument is a text string that looks like Pod text (i.e. it 01340 contains '=' at the start of any line) then it is passed to parse_text(). 01341 01342 my $podpom = $parser->parse($podtext) 01343 || die $parser->error(); 01344 01345 Otherwise it is assumed to be a filename and is passed to parse_file(). 01346 01347 my $podpom = $parser->parse($podfile) 01348 || die $parser->error(); 01349 01350 =head1 NODE TYPES, ATTRIBUTES AND ELEMENTS 01351 01352 This section lists the different nodes that may be present in a Pod Object 01353 Model. These are implemented as Pod::POM::Node::* object instances 01354 (e.g. head1 =E<gt> Pod::POM::Node::Head1). To present a node, a view should 01355 implement a method which corresponds to the node name prefixed by 'view_' 01356 (e.g. head1 =E<gt> view_head1()). 01357 01358 =over 4 01359 01360 =item pod 01361 01362 The C<pod> node is used to represent the root node of the Pod Object Model. 01363 01364 Content elements: head1, head2, head3, head4, over, begin, for, 01365 verbatim, text, code. 01366 01367 =item head1 01368 01369 A C<head1> node contains the Pod content from a C<=head1> tag up to the 01370 next C<=head1> tag or the end of the file. 01371 01372 Attributes: title 01373 01374 Content elements: head2, head3, head4, over, begin, for, verbatim, text, code. 01375 01376 =item head2 01377 01378 A C<head2> node contains the Pod content from a C<=head2> tag up to the 01379 next C<=head1> or C<=head2> tag or the end of the file. 01380 01381 Attributes: title 01382 01383 Content elements: head3, head4, over, begin, for, verbatim, text, code. 01384 01385 =item head3 01386 01387 A C<head3> node contains the Pod content from a C<=head3> tag up to the 01388 next C<=head1>, C<=head2> or C<=head3> tag or the end of the file. 01389 01390 Attributes: title 01391 01392 Content elements: head4, over, begin, for, verbatim, text, code. 01393 01394 =item head4 01395 01396 A C<head4> node contains the Pod content from a C<=head4> tag up to the 01397 next C<=head1>, C<=head2>, C<=head3> or C<=head4> tag or the end of the file. 01398 01399 Attributes: title 01400 01401 Content elements: over, begin, for, verbatim, text, code. 01402 01403 =item over 01404 01405 The C<over> node encloses the Pod content in a list starting at an C<=over> 01406 tag and continuing up to the matching C<=back> tag. Lists may be nested 01407 indefinately. 01408 01409 Attributes: indent (default: 4) 01410 01411 Content elements: over, item, begin, for, verbatim, text, code. 01412 01413 =item item 01414 01415 The C<item> node encloses the Pod content in a list item starting at an 01416 C<=item> tag and continuing up to the next C<=item> tag or a C<=back> tag 01417 which terminates the list. 01418 01419 Attributes: title (default: *) 01420 01421 Content elements: over, begin, for, verbatim, text, code. 01422 01423 =item begin 01424 01425 A C<begin> node encloses the Pod content in a conditional block starting 01426 with a C<=begin> tag and continuing up to the next C<=end> tag. 01427 01428 Attributes: format 01429 01430 Content elements: verbatim, text, code. 01431 01432 =item for 01433 01434 A C<for> node contains a single paragraph containing text relevant to a 01435 particular format. 01436 01437 Attributes: format, text 01438 01439 =item verbatim 01440 01441 A C<verbatim> node contains a verbatim text paragraph which is prefixed by 01442 whitespace in the source Pod document (i.e. indented). 01443 01444 Attributes: text 01445 01446 =item text 01447 01448 A C<text> node contains a regular text paragraph. This may include 01449 embedded inline sequences. 01450 01451 Attributes: text 01452 01453 =item code 01454 01455 A C<code> node contains Perl code which is by default, not considered to be 01456 part of a Pod document. The C<code> configuration option must be set for 01457 Pod::POM to generate code blocks, otherwise they are ignored. 01458 01459 Attributes: text 01460 01461 =back 01462 01463 =head1 INLINE SEQUENCES 01464 01465 Embedded sequences are permitted within regular text blocks (i.e. not 01466 verbatim) and title attributes. To present these sequences, a view 01467 should implement methods corresponding to the sequence name, prefixed 01468 by 'view_seq_' (e.g. bold =E<gt> view_seq_bold()). 01469 01470 =over 4 01471 01472 =item code 01473 01474 Code extract, e.g. CE<lt>my codeE<gt> 01475 01476 =item bold 01477 01478 Bold text, e.g. BE<lt>bold textE<gt> 01479 01480 =item italic 01481 01482 Italic text, e.g. IE<lt>italic textE<gt> 01483 01484 =item link 01485 01486 A link (cross reference), e.g. LE<lt>My::ModuleE<gt> 01487 01488 =item space 01489 01490 Text contains non-breaking space, e.g.SE<lt>Buffy The Vampire SlayerE<gt> 01491 01492 =item file 01493 01494 A filename, e.g. FE<lt>/etc/lilo.confE<gt> 01495 01496 =item index 01497 01498 An index entry, e.g. XE<lt>AngelE<gt> 01499 01500 =item zero 01501 01502 A zero-width character, e.g. ZE<lt>E<gt> 01503 01504 =item entity 01505 01506 An entity escape, e.g. EE<lt>ltE<gt> 01507 01508 =back 01509 01510 =head1 BUNDLED MODULES AND TOOLS 01511 01512 The Pod::POM module distribution includes a number of sample view 01513 objects for rendering Pod Object Models into particular formats. These 01514 are incomplete and may require some further work, but serve at present to 01515 illustrate the principal and can be used as the basis for your own view 01516 objects. 01517 01518 =over 4 01519 01520 =item Pod::POM::View::Pod 01521 01522 Regenerates the model as Pod. 01523 01524 =item Pod::POM::View::Text 01525 01526 Presents the model as plain text. 01527 01528 =item Pod::POM::View::HTML 01529 01530 Presents the model as HTML. 01531 01532 =back 01533 01534 A script is provided for converting Pod documents to other format by 01535 using the view objects provided. The C<pom2> script should be called 01536 with two arguments, the first specifying the output format, the second 01537 the input filename. e.g. 01538 01539 $ pom2 text My/Module.pm > README 01540 $ pom2 html My/Module.pm > ~/public_html/My/Module.html 01541 01542 You can also create symbolic links to the script if you prefer and 01543 leave it to determine the output format from its own name. 01544 01545 $ ln -s pom2 pom2text 01546 $ ln -s pom2 pom2html 01547 $ pom2text My/Module.pm > README 01548 $ pom2html My/Module.pm > ~/public_html/My/Module.html 01549 01550 The distribution also contains a trivial script, C<podlint> 01551 (previously C<pomcheck>), which checks a Pod document for 01552 well-formedness by simply parsing it into a Pod Object Model with 01553 warnings enabled. Warnings are printed to STDERR. 01554 01555 $ podlint My/Module.pm 01556 01557 The C<-f> option can be set to have the script attempt to fix any problems 01558 it encounters. The regenerated Pod output is printed to STDOUT. 01559 01560 $ podlint -f My/Module.pm > newfile 01561 01562 =head1 METADATA 01563 01564 This module includes support for an experimental new C<=meta> tag. This 01565 is disabled by default but can be enabled by loading Pod::POM with the 01566 C<meta> option. 01567 01568 use Pod::POM qw( meta ); 01569 01570 Alternately, you can specify the C<meta> option to be any true value when 01571 you instantiate a Pod::POM parser: 01572 01573 my $parser = Pod::POM->new( meta => 1 ); 01574 my $pom = $parser->parse_file($filename); 01575 01576 Any C<=meta> tags in the document will be stored as metadata items in the 01577 root node of the Pod model created. 01578 01579 For example: 01580 01581 =meta module Foo::Bar 01582 01583 =meta author Andy Wardley 01584 01585 You can then access these items via the metadata() method. 01586 01587 print "module: ", $pom->metadata('module'), "\n"; 01588 print "author: ", $pom->metadata('author'), "\n"; 01589 01590 or 01591 01592 my $metadata = $pom->metadata(); 01593 print "module: $metadata->{ module }\n"; 01594 print "author: $metadata->{ author }\n"; 01595 01596 Please note that this is an experimental feature which is not supported by 01597 other POD processors and is therefore likely to be most incompatible. Use 01598 carefully. 01599 01600 =head1 AUTHOR 01601 01602 Andy Wardley E<lt>abw@kfs.orgE<gt> 01603 01604 Andrew Ford E<lt>A.Ford@ford-mason.co.ukE<gt> (co-maintainer as of 03/2009) 01605 01606 =head1 VERSION 01607 01608 This is version 0.25 of the Pod::POM module. 01609 01610 =head1 COPYRIGHT 01611 01612 Copyright (C) 2000-2009 Andy Wardley. All Rights Reserved. 01613 01614 This module is free software; you can redistribute it and/or 01615 modify it under the same terms as Perl itself. 01616 01617 =head1 SEE ALSO 01618 01619 For the definitive reference on Pod, see L<perlpod>. 01620 01621 For an overview of Pod::POM internals and details relating to subclassing 01622 of POM nodes, see L<Pod::POM::Node>. 01623 01624 There are numerous other fine Pod modules available from CPAN which 01625 perform conversion from Pod to other formats. In many cases these are 01626 likely to be faster and quite possibly more reliable and/or complete 01627 than this module. But as far as I know, there aren't any that offer 01628 the same kind of flexibility in being able to customise the generated 01629 output. But don't take my word for it - see your local CPAN site for 01630 further details: 01631 01632 http://www.cpan.org/modules/by-module/Pod/ 01633