"Fossies" - the Fresh Open Source Software Archive

Member "install-tl-20200916/tlpkg/tlperl/lib/Pod/ParseUtils.pm" (5 Apr 2016, 21174 Bytes) of package /windows/misc/install-tl.zip:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file.

    1 #############################################################################
    2 # Pod/ParseUtils.pm -- helpers for POD parsing and conversion
    3 #
    4 # Copyright (C) 1999-2000 by Marek Rouchal. All rights reserved.
    5 # This file is part of "PodParser". PodParser is free software;
    6 # you can redistribute it and/or modify it under the same terms
    7 # as Perl itself.
    8 #############################################################################
    9 
   10 package Pod::ParseUtils;
   11 use strict;
   12 
   13 use vars qw($VERSION);
   14 $VERSION = '1.63'; ## Current version of this package
   15 require  5.005;    ## requires this Perl version or later
   16 
   17 =head1 NAME
   18 
   19 Pod::ParseUtils - helpers for POD parsing and conversion
   20 
   21 =head1 SYNOPSIS
   22 
   23   use Pod::ParseUtils;
   24 
   25   my $list = new Pod::List;
   26   my $link = Pod::Hyperlink->new('Pod::Parser');
   27 
   28 =head1 DESCRIPTION
   29 
   30 B<NOTE: This module is considered legacy; modern Perl releases (5.18 and
   31 higher) are going to remove Pod-Parser from core and use L<Pod-Simple>
   32 for all things POD.>
   33 
   34 B<Pod::ParseUtils> contains a few object-oriented helper packages for
   35 POD parsing and processing (i.e. in POD formatters and translators).
   36 
   37 =cut
   38 
   39 #-----------------------------------------------------------------------------
   40 # Pod::List
   41 #
   42 # class to hold POD list info (=over, =item, =back)
   43 #-----------------------------------------------------------------------------
   44 
   45 package Pod::List;
   46 
   47 use Carp;
   48 
   49 =head2 Pod::List
   50 
   51 B<Pod::List> can be used to hold information about POD lists
   52 (written as =over ... =item ... =back) for further processing.
   53 The following methods are available:
   54 
   55 =over 4
   56 
   57 =item Pod::List-E<gt>new()
   58 
   59 Create a new list object. Properties may be specified through a hash
   60 reference like this:
   61 
   62   my $list = Pod::List->new({ -start => $., -indent => 4 });
   63 
   64 See the individual methods/properties for details.
   65 
   66 =cut
   67 
   68 sub new {
   69     my $this = shift;
   70     my $class = ref($this) || $this;
   71     my %params = @_;
   72     my $self = {%params};
   73     bless $self, $class;
   74     $self->initialize();
   75     return $self;
   76 }
   77 
   78 sub initialize {
   79     my $self = shift;
   80     $self->{-file} ||= 'unknown';
   81     $self->{-start} ||= 'unknown';
   82     $self->{-indent} ||= 4; # perlpod: "should be the default"
   83     $self->{_items} = [];
   84     $self->{-type} ||= '';
   85 }
   86 
   87 =item $list-E<gt>file()
   88 
   89 Without argument, retrieves the file name the list is in. This must
   90 have been set before by either specifying B<-file> in the B<new()>
   91 method or by calling the B<file()> method with a scalar argument.
   92 
   93 =cut
   94 
   95 # The POD file name the list appears in
   96 sub file {
   97    return (@_ > 1) ? ($_[0]->{-file} = $_[1]) : $_[0]->{-file};
   98 }
   99 
  100 =item $list-E<gt>start()
  101 
  102 Without argument, retrieves the line number where the list started.
  103 This must have been set before by either specifying B<-start> in the
  104 B<new()> method or by calling the B<start()> method with a scalar
  105 argument.
  106 
  107 =cut
  108 
  109 # The line in the file the node appears
  110 sub start {
  111    return (@_ > 1) ? ($_[0]->{-start} = $_[1]) : $_[0]->{-start};
  112 }
  113 
  114 =item $list-E<gt>indent()
  115 
  116 Without argument, retrieves the indent level of the list as specified
  117 in C<=over n>. This must have been set before by either specifying
  118 B<-indent> in the B<new()> method or by calling the B<indent()> method
  119 with a scalar argument.
  120 
  121 =cut
  122 
  123 # indent level
  124 sub indent {
  125    return (@_ > 1) ? ($_[0]->{-indent} = $_[1]) : $_[0]->{-indent};
  126 }
  127 
  128 =item $list-E<gt>type()
  129 
  130 Without argument, retrieves the list type, which can be an arbitrary value,
  131 e.g. C<OL>, C<UL>, ... when thinking the HTML way.
  132 This must have been set before by either specifying
  133 B<-type> in the B<new()> method or by calling the B<type()> method
  134 with a scalar argument.
  135 
  136 =cut
  137 
  138 # The type of the list (UL, OL, ...)
  139 sub type {
  140    return (@_ > 1) ? ($_[0]->{-type} = $_[1]) : $_[0]->{-type};
  141 }
  142 
  143 =item $list-E<gt>rx()
  144 
  145 Without argument, retrieves a regular expression for simplifying the 
  146 individual item strings once the list type has been determined. Usage:
  147 E.g. when converting to HTML, one might strip the leading number in
  148 an ordered list as C<E<lt>OLE<gt>> already prints numbers itself.
  149 This must have been set before by either specifying
  150 B<-rx> in the B<new()> method or by calling the B<rx()> method
  151 with a scalar argument.
  152 
  153 =cut
  154 
  155 # The regular expression to simplify the items
  156 sub rx {
  157    return (@_ > 1) ? ($_[0]->{-rx} = $_[1]) : $_[0]->{-rx};
  158 }
  159 
  160 =item $list-E<gt>item()
  161 
  162 Without argument, retrieves the array of the items in this list.
  163 The items may be represented by any scalar.
  164 If an argument has been given, it is pushed on the list of items.
  165 
  166 =cut
  167 
  168 # The individual =items of this list
  169 sub item {
  170     my ($self,$item) = @_;
  171     if(defined $item) {
  172         push(@{$self->{_items}}, $item);
  173         return $item;
  174     }
  175     else {
  176         return @{$self->{_items}};
  177     }
  178 }
  179 
  180 =item $list-E<gt>parent()
  181 
  182 Without argument, retrieves information about the parent holding this
  183 list, which is represented as an arbitrary scalar.
  184 This must have been set before by either specifying
  185 B<-parent> in the B<new()> method or by calling the B<parent()> method
  186 with a scalar argument.
  187 
  188 =cut
  189 
  190 # possibility for parsers/translators to store information about the
  191 # lists's parent object
  192 sub parent {
  193    return (@_ > 1) ? ($_[0]->{-parent} = $_[1]) : $_[0]->{-parent};
  194 }
  195 
  196 =item $list-E<gt>tag()
  197 
  198 Without argument, retrieves information about the list tag, which can be
  199 any scalar.
  200 This must have been set before by either specifying
  201 B<-tag> in the B<new()> method or by calling the B<tag()> method
  202 with a scalar argument.
  203 
  204 =back
  205 
  206 =cut
  207 
  208 # possibility for parsers/translators to store information about the
  209 # list's object
  210 sub tag {
  211    return (@_ > 1) ? ($_[0]->{-tag} = $_[1]) : $_[0]->{-tag};
  212 }
  213 
  214 #-----------------------------------------------------------------------------
  215 # Pod::Hyperlink
  216 #
  217 # class to manipulate POD hyperlinks (L<>)
  218 #-----------------------------------------------------------------------------
  219 
  220 package Pod::Hyperlink;
  221 
  222 =head2 Pod::Hyperlink
  223 
  224 B<Pod::Hyperlink> is a class for manipulation of POD hyperlinks. Usage:
  225 
  226   my $link = Pod::Hyperlink->new('alternative text|page/"section in page"');
  227 
  228 The B<Pod::Hyperlink> class is mainly designed to parse the contents of the
  229 C<LE<lt>...E<gt>> sequence, providing a simple interface for accessing the
  230 different parts of a POD hyperlink for further processing. It can also be
  231 used to construct hyperlinks.
  232 
  233 =over 4
  234 
  235 =item Pod::Hyperlink-E<gt>new()
  236 
  237 The B<new()> method can either be passed a set of key/value pairs or a single
  238 scalar value, namely the contents of a C<LE<lt>...E<gt>> sequence. An object
  239 of the class C<Pod::Hyperlink> is returned. The value C<undef> indicates a
  240 failure, the error message is stored in C<$@>.
  241 
  242 =cut
  243 
  244 use Carp;
  245 
  246 sub new {
  247     my $this = shift;
  248     my $class = ref($this) || $this;
  249     my $self = +{};
  250     bless $self, $class;
  251     $self->initialize();
  252     if(defined $_[0]) {
  253         if(ref($_[0])) {
  254             # called with a list of parameters
  255             %$self = %{$_[0]};
  256             $self->_construct_text();
  257         }
  258         else {
  259             # called with L<> contents
  260             return unless($self->parse($_[0]));
  261         }
  262     }
  263     return $self;
  264 }
  265 
  266 sub initialize {
  267     my $self = shift;
  268     $self->{-line} ||= 'undef';
  269     $self->{-file} ||= 'undef';
  270     $self->{-page} ||= '';
  271     $self->{-node} ||= '';
  272     $self->{-alttext} ||= '';
  273     $self->{-type} ||= 'undef';
  274     $self->{_warnings} = [];
  275 }
  276 
  277 =item $link-E<gt>parse($string)
  278 
  279 This method can be used to (re)parse a (new) hyperlink, i.e. the contents
  280 of a C<LE<lt>...E<gt>> sequence. The result is stored in the current object.
  281 Warnings are stored in the B<warnings> property.
  282 E.g. sections like C<LE<lt>open(2)E<gt>> are deprecated, as they do not point
  283 to Perl documents. C<LE<lt>DBI::foo(3p)E<gt>> is wrong as well, the manpage
  284 section can simply be dropped.
  285 
  286 =cut
  287 
  288 sub parse {
  289     my $self = shift;
  290     local($_) = $_[0];
  291     # syntax check the link and extract destination
  292     my ($alttext,$page,$node,$type,$quoted) = (undef,'','','',0);
  293 
  294     $self->{_warnings} = [];
  295 
  296     # collapse newlines with whitespace
  297     s/\s*\n+\s*/ /g;
  298 
  299     # strip leading/trailing whitespace
  300     if(s/^[\s\n]+//) {
  301         $self->warning('ignoring leading whitespace in link');
  302     }
  303     if(s/[\s\n]+$//) {
  304         $self->warning('ignoring trailing whitespace in link');
  305     }
  306     unless(length($_)) {
  307         _invalid_link('empty link');
  308         return;
  309     }
  310 
  311     ## Check for different possibilities. This is tedious and error-prone
  312     # we match all possibilities (alttext, page, section/item)
  313     #warn "DEBUG: link=$_\n";
  314 
  315     # only page
  316     # problem: a lot of people use (), or (1) or the like to indicate
  317     # man page sections. But this collides with L<func()> that is supposed
  318     # to point to an internal function...
  319     my $page_rx = '[\w.-]+(?:::[\w.-]+)*(?:[(](?:\d\w*|)[)]|)';
  320     # page name only
  321     if(/^($page_rx)$/o) {
  322         $page = $1;
  323         $type = 'page';
  324     }
  325     # alttext, page and "section"
  326     elsif(m{^(.*?)\s*[|]\s*($page_rx)\s*/\s*"(.+)"$}o) {
  327         ($alttext, $page, $node) = ($1, $2, $3);
  328         $type = 'section';
  329         $quoted = 1; #... therefore | and / are allowed
  330     }
  331     # alttext and page
  332     elsif(/^(.*?)\s*[|]\s*($page_rx)$/o) {
  333         ($alttext, $page) = ($1, $2);
  334         $type = 'page';
  335     }
  336     # alttext and "section"
  337     elsif(m{^(.*?)\s*[|]\s*(?:/\s*|)"(.+)"$}) {
  338         ($alttext, $node) = ($1,$2);
  339         $type = 'section';
  340         $quoted = 1;
  341     }
  342     # page and "section"
  343     elsif(m{^($page_rx)\s*/\s*"(.+)"$}o) {
  344         ($page, $node) = ($1, $2);
  345         $type = 'section';
  346         $quoted = 1;
  347     }
  348     # page and item
  349     elsif(m{^($page_rx)\s*/\s*(.+)$}o) {
  350         ($page, $node) = ($1, $2);
  351         $type = 'item';
  352     }
  353     # only "section"
  354     elsif(m{^/?"(.+)"$}) {
  355         $node = $1;
  356         $type = 'section';
  357         $quoted = 1;
  358     }
  359     # only item
  360     elsif(m{^\s*/(.+)$}) {
  361         $node = $1;
  362         $type = 'item';
  363     }
  364 
  365     # non-standard: Hyperlink with alt-text - doesn't remove protocol prefix, maybe it should?
  366     elsif(/^ \s* (.*?) \s* [|] \s* (\w+:[^:\s] [^\s|]*?) \s* $/ix) {
  367       ($alttext,$node) = ($1,$2);
  368       $type = 'hyperlink';
  369     }
  370 
  371     # non-standard: Hyperlink
  372     elsif(/^(\w+:[^:\s]\S*)$/i) {
  373         $node = $1;
  374         $type = 'hyperlink';
  375     }
  376     # alttext, page and item
  377     elsif(m{^(.*?)\s*[|]\s*($page_rx)\s*/\s*(.+)$}o) {
  378         ($alttext, $page, $node) = ($1, $2, $3);
  379         $type = 'item';
  380     }
  381     # alttext and item
  382     elsif(m{^(.*?)\s*[|]\s*/(.+)$}) {
  383         ($alttext, $node) = ($1,$2);
  384     }
  385     # must be an item or a "malformed" section (without "")
  386     else {
  387         $node = $_;
  388         $type = 'item';
  389     }
  390     # collapse whitespace in nodes
  391     $node =~ s/\s+/ /gs;
  392 
  393     # empty alternative text expands to node name
  394     if(defined $alttext) {
  395         if(!length($alttext)) {
  396           $alttext = $node || $page;
  397         }
  398     }
  399     else {
  400         $alttext = '';
  401     }
  402 
  403     if($page =~ /[(]\w*[)]$/) {
  404         $self->warning("(section) in '$page' deprecated");
  405     }
  406     if(!$quoted && $node =~ m{[|/]} && $type ne 'hyperlink') {
  407         $self->warning("node '$node' contains non-escaped | or /");
  408     }
  409     if($alttext =~ m{[|/]}) {
  410         $self->warning("alternative text '$node' contains non-escaped | or /");
  411     }
  412     $self->{-page} = $page;
  413     $self->{-node} = $node;
  414     $self->{-alttext} = $alttext;
  415     #warn "DEBUG: page=$page section=$section item=$item alttext=$alttext\n";
  416     $self->{-type} = $type;
  417     $self->_construct_text();
  418     1;
  419 }
  420 
  421 sub _construct_text {
  422     my $self = shift;
  423     my $alttext = $self->alttext();
  424     my $type = $self->type();
  425     my $section = $self->node();
  426     my $page = $self->page();
  427     my $page_ext = '';
  428     $page =~ s/([(]\w*[)])$// && ($page_ext = $1);
  429     if($alttext) {
  430         $self->{_text} = $alttext;
  431     }
  432     elsif($type eq 'hyperlink') {
  433         $self->{_text} = $section;
  434     }
  435     else {
  436         $self->{_text} = ($section || '') .
  437             (($page && $section) ? ' in ' : '') .
  438             "$page$page_ext";
  439     }
  440     # for being marked up later
  441     # use the non-standard markers P<> and Q<>, so that the resulting
  442     # text can be parsed by the translators. It's their job to put
  443     # the correct hypertext around the linktext
  444     if($alttext) {
  445         $self->{_markup} = "Q<$alttext>";
  446     }
  447     elsif($type eq 'hyperlink') {
  448         $self->{_markup} = "Q<$section>";
  449     }
  450     else {
  451         $self->{_markup} = (!$section ? '' : "Q<$section>") .
  452             ($page ? ($section ? ' in ':'') . "P<$page>$page_ext" : '');
  453     }
  454 }
  455 
  456 =item $link-E<gt>markup($string)
  457 
  458 Set/retrieve the textual value of the link. This string contains special
  459 markers C<PE<lt>E<gt>> and C<QE<lt>E<gt>> that should be expanded by the
  460 translator's interior sequence expansion engine to the
  461 formatter-specific code to highlight/activate the hyperlink. The details
  462 have to be implemented in the translator.
  463 
  464 =cut
  465 
  466 #' retrieve/set markuped text
  467 sub markup {
  468     return (@_ > 1) ? ($_[0]->{_markup} = $_[1]) : $_[0]->{_markup};
  469 }
  470 
  471 =item $link-E<gt>text()
  472 
  473 This method returns the textual representation of the hyperlink as above,
  474 but without markers (read only). Depending on the link type this is one of
  475 the following alternatives (the + and * denote the portions of the text
  476 that are marked up):
  477 
  478   +perl+                    L<perl>
  479   *$|* in +perlvar+         L<perlvar/$|>
  480   *OPTIONS* in +perldoc+    L<perldoc/"OPTIONS">
  481   *DESCRIPTION*             L<"DESCRIPTION">
  482 
  483 =cut
  484 
  485 # The complete link's text
  486 sub text {
  487     return $_[0]->{_text};
  488 }
  489 
  490 =item $link-E<gt>warning()
  491 
  492 After parsing, this method returns any warnings encountered during the
  493 parsing process.
  494 
  495 =cut
  496 
  497 # Set/retrieve warnings
  498 sub warning {
  499     my $self = shift;
  500     if(@_) {
  501         push(@{$self->{_warnings}}, @_);
  502         return @_;
  503     }
  504     return @{$self->{_warnings}};
  505 }
  506 
  507 =item $link-E<gt>file()
  508 
  509 =item $link-E<gt>line()
  510 
  511 Just simple slots for storing information about the line and the file
  512 the link was encountered in. Has to be filled in manually.
  513 
  514 =cut
  515 
  516 # The line in the file the link appears
  517 sub line {
  518     return (@_ > 1) ? ($_[0]->{-line} = $_[1]) : $_[0]->{-line};
  519 }
  520 
  521 # The POD file name the link appears in
  522 sub file {
  523     return (@_ > 1) ? ($_[0]->{-file} = $_[1]) : $_[0]->{-file};
  524 }
  525 
  526 =item $link-E<gt>page()
  527 
  528 This method sets or returns the POD page this link points to.
  529 
  530 =cut
  531 
  532 # The POD page the link appears on
  533 sub page {
  534     if (@_ > 1) {
  535         $_[0]->{-page} = $_[1];
  536         $_[0]->_construct_text();
  537     }
  538     return $_[0]->{-page};
  539 }
  540 
  541 =item $link-E<gt>node()
  542 
  543 As above, but the destination node text of the link.
  544 
  545 =cut
  546 
  547 # The link destination
  548 sub node {
  549     if (@_ > 1) {
  550         $_[0]->{-node} = $_[1];
  551         $_[0]->_construct_text();
  552     }
  553     return $_[0]->{-node};
  554 }
  555 
  556 =item $link-E<gt>alttext()
  557 
  558 Sets or returns an alternative text specified in the link.
  559 
  560 =cut
  561 
  562 # Potential alternative text
  563 sub alttext {
  564     if (@_ > 1) {
  565         $_[0]->{-alttext} = $_[1];
  566         $_[0]->_construct_text();
  567     }
  568     return $_[0]->{-alttext};
  569 }
  570 
  571 =item $link-E<gt>type()
  572 
  573 The node type, either C<section> or C<item>. As an unofficial type,
  574 there is also C<hyperlink>, derived from e.g. C<LE<lt>http://perl.comE<gt>>
  575 
  576 =cut
  577 
  578 # The type: item or headn
  579 sub type {
  580     return (@_ > 1) ? ($_[0]->{-type} = $_[1]) : $_[0]->{-type};
  581 }
  582 
  583 =item $link-E<gt>link()
  584 
  585 Returns the link as contents of C<LE<lt>E<gt>>. Reciprocal to B<parse()>.
  586 
  587 =back
  588 
  589 =cut
  590 
  591 # The link itself
  592 sub link {
  593     my $self = shift;
  594     my $link = $self->page() || '';
  595     if($self->node()) {
  596         my $node = $self->node();
  597         $node =~ s/\|/E<verbar>/g;
  598         $node =~ s{/}{E<sol>}g;
  599         if($self->type() eq 'section') {
  600             $link .= ($link ? '/' : '') . '"' . $node . '"';
  601         }
  602         elsif($self->type() eq 'hyperlink') {
  603             $link = $self->node();
  604         }
  605         else { # item
  606             $link .= '/' . $node;
  607         }
  608     }
  609     if($self->alttext()) {
  610         my $text = $self->alttext();
  611         $text =~ s/\|/E<verbar>/g;
  612         $text =~ s{/}{E<sol>}g;
  613         $link = "$text|$link";
  614     }
  615     return $link;
  616 }
  617 
  618 sub _invalid_link {
  619     my ($msg) = @_;
  620     # this sets @_
  621     #eval { die "$msg\n" };
  622     #chomp $@;
  623     $@ = $msg; # this seems to work, too!
  624     return;
  625 }
  626 
  627 #-----------------------------------------------------------------------------
  628 # Pod::Cache
  629 #
  630 # class to hold POD page details
  631 #-----------------------------------------------------------------------------
  632 
  633 package Pod::Cache;
  634 
  635 =head2 Pod::Cache
  636 
  637 B<Pod::Cache> holds information about a set of POD documents,
  638 especially the nodes for hyperlinks.
  639 The following methods are available:
  640 
  641 =over 4
  642 
  643 =item Pod::Cache-E<gt>new()
  644 
  645 Create a new cache object. This object can hold an arbitrary number of
  646 POD documents of class Pod::Cache::Item.
  647 
  648 =cut
  649 
  650 sub new {
  651     my $this = shift;
  652     my $class = ref($this) || $this;
  653     my $self = [];
  654     bless $self, $class;
  655     return $self;
  656 }
  657 
  658 =item $cache-E<gt>item()
  659 
  660 Add a new item to the cache. Without arguments, this method returns a
  661 list of all cache elements.
  662 
  663 =cut
  664 
  665 sub item {
  666     my ($self,%param) = @_;
  667     if(%param) {
  668         my $item = Pod::Cache::Item->new(%param);
  669         push(@$self, $item);
  670         return $item;
  671     }
  672     else {
  673         return @{$self};
  674     }
  675 }
  676 
  677 =item $cache-E<gt>find_page($name)
  678 
  679 Look for a POD document named C<$name> in the cache. Returns the
  680 reference to the corresponding Pod::Cache::Item object or undef if
  681 not found.
  682 
  683 =back
  684 
  685 =cut
  686 
  687 sub find_page {
  688     my ($self,$page) = @_;
  689     foreach(@$self) {
  690         if($_->page() eq $page) {
  691             return $_;
  692         }
  693     }
  694     return;
  695 }
  696 
  697 package Pod::Cache::Item;
  698 
  699 =head2 Pod::Cache::Item
  700 
  701 B<Pod::Cache::Item> holds information about individual POD documents,
  702 that can be grouped in a Pod::Cache object.
  703 It is intended to hold information about the hyperlink nodes of POD
  704 documents.
  705 The following methods are available:
  706 
  707 =over 4
  708 
  709 =item Pod::Cache::Item-E<gt>new()
  710 
  711 Create a new object.
  712 
  713 =cut
  714 
  715 sub new {
  716     my $this = shift;
  717     my $class = ref($this) || $this;
  718     my %params = @_;
  719     my $self = {%params};
  720     bless $self, $class;
  721     $self->initialize();
  722     return $self;
  723 }
  724 
  725 sub initialize {
  726     my $self = shift;
  727     $self->{-nodes} = [] unless(defined $self->{-nodes});
  728 }
  729 
  730 =item $cacheitem-E<gt>page()
  731 
  732 Set/retrieve the POD document name (e.g. "Pod::Parser").
  733 
  734 =cut
  735 
  736 # The POD page
  737 sub page {
  738    return (@_ > 1) ? ($_[0]->{-page} = $_[1]) : $_[0]->{-page};
  739 }
  740 
  741 =item $cacheitem-E<gt>description()
  742 
  743 Set/retrieve the POD short description as found in the C<=head1 NAME>
  744 section.
  745 
  746 =cut
  747 
  748 # The POD description, taken out of NAME if present
  749 sub description {
  750    return (@_ > 1) ? ($_[0]->{-description} = $_[1]) : $_[0]->{-description};
  751 }
  752 
  753 =item $cacheitem-E<gt>path()
  754 
  755 Set/retrieve the POD file storage path.
  756 
  757 =cut
  758 
  759 # The file path
  760 sub path {
  761    return (@_ > 1) ? ($_[0]->{-path} = $_[1]) : $_[0]->{-path};
  762 }
  763 
  764 =item $cacheitem-E<gt>file()
  765 
  766 Set/retrieve the POD file name.
  767 
  768 =cut
  769 
  770 # The POD file name
  771 sub file {
  772    return (@_ > 1) ? ($_[0]->{-file} = $_[1]) : $_[0]->{-file};
  773 }
  774 
  775 =item $cacheitem-E<gt>nodes()
  776 
  777 Add a node (or a list of nodes) to the document's node list. Note that
  778 the order is kept, i.e. start with the first node and end with the last.
  779 If no argument is given, the current list of nodes is returned in the
  780 same order the nodes have been added.
  781 A node can be any scalar, but usually is a pair of node string and
  782 unique id for the C<find_node> method to work correctly.
  783 
  784 =cut
  785 
  786 # The POD nodes
  787 sub nodes {
  788     my ($self,@nodes) = @_;
  789     if(@nodes) {
  790         push(@{$self->{-nodes}}, @nodes);
  791         return @nodes;
  792     }
  793     else {
  794         return @{$self->{-nodes}};
  795     }
  796 }
  797 
  798 =item $cacheitem-E<gt>find_node($name)
  799 
  800 Look for a node or index entry named C<$name> in the object.
  801 Returns the unique id of the node (i.e. the second element of the array
  802 stored in the node array) or undef if not found.
  803 
  804 =cut
  805 
  806 sub find_node {
  807     my ($self,$node) = @_;
  808     my @search;
  809     push(@search, @{$self->{-nodes}}) if($self->{-nodes});
  810     push(@search, @{$self->{-idx}}) if($self->{-idx});
  811     foreach(@search) {
  812         if($_->[0] eq $node) {
  813             return $_->[1]; # id
  814         }
  815     }
  816     return;
  817 }
  818 
  819 =item $cacheitem-E<gt>idx()
  820 
  821 Add an index entry (or a list of them) to the document's index list. Note that
  822 the order is kept, i.e. start with the first node and end with the last.
  823 If no argument is given, the current list of index entries is returned in the
  824 same order the entries have been added.
  825 An index entry can be any scalar, but usually is a pair of string and
  826 unique id.
  827 
  828 =back
  829 
  830 =cut
  831 
  832 # The POD index entries
  833 sub idx {
  834     my ($self,@idx) = @_;
  835     if(@idx) {
  836         push(@{$self->{-idx}}, @idx);
  837         return @idx;
  838     }
  839     else {
  840         return @{$self->{-idx}};
  841     }
  842 }
  843 
  844 =head1 AUTHOR
  845 
  846 Please report bugs using L<http://rt.cpan.org>.
  847 
  848 Marek Rouchal E<lt>marekr@cpan.orgE<gt>, borrowing
  849 a lot of things from L<pod2man> and L<pod2roff> as well as other POD
  850 processing tools by Tom Christiansen, Brad Appleton and Russ Allbery.
  851 
  852 B<Pod::ParseUtils> is part of the L<Pod::Parser> distribution.
  853 
  854 =head1 SEE ALSO
  855 
  856 L<pod2man>, L<pod2roff>, L<Pod::Parser>, L<Pod::Checker>,
  857 L<pod2html>
  858 
  859 =cut
  860 
  861 1;