Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

RedHat 9 (Linux i386) - man page for pod::parseutils (redhat section 3pm)

Pod::ParseUtils(3pm)		 Perl Programmers Reference Guide	     Pod::ParseUtils(3pm)

NAME
       Pod::ParseUtils - helpers for POD parsing and conversion

SYNOPSIS
	 use Pod::ParseUtils;

	 my $list = new Pod::List;
	 my $link = Pod::Hyperlink->new('Pod::Parser');

DESCRIPTION
       Pod::ParseUtils contains a few object-oriented helper packages for POD parsing and pro-
       cessing (i.e. in POD formatters and translators).

       Pod::List

       Pod::List can be used to hold information about POD lists (written as =over ... =item ...
       =back) for further processing.  The following methods are available:

       Pod::List->new()
	   Create a new list object. Properties may be specified through a hash reference like
	   this:

	     my $list = Pod::List->new({ -start => $., -indent => 4 });

	   See the individual methods/properties for details.

       $list->file()
	   Without argument, retrieves the file name the list is in. This must have been set
	   before by either specifying -file in the new() method or by calling the file() method
	   with a scalar argument.

       $list->start()
	   Without argument, retrieves the line number where the list started.	This must have
	   been set before by either specifying -start in the new() method or by calling the
	   start() method with a scalar argument.

       $list->indent()
	   Without argument, retrieves the indent level of the list as specified in "=over n".
	   This must have been set before by either specifying -indent in the new() method or by
	   calling the indent() method with a scalar argument.

       $list->type()
	   Without argument, retrieves the list type, which can be an arbitrary value, e.g. "OL",
	   "UL", ... when thinking the HTML way.  This must have been set before by either speci-
	   fying -type in the new() method or by calling the type() method with a scalar argu-
	   ment.

       $list->rx()
	   Without argument, retrieves a regular expression for simplifying the individual item
	   strings once the list type has been determined. Usage: E.g. when converting to HTML,
	   one might strip the leading number in an ordered list as "<OL>" already prints numbers
	   itself.  This must have been set before by either specifying -rx in the new() method
	   or by calling the rx() method with a scalar argument.

       $list->item()
	   Without argument, retrieves the array of the items in this list.  The items may be
	   represented by any scalar.  If an argument has been given, it is pushed on the list of
	   items.

       $list->parent()
	   Without argument, retrieves information about the parent holding this list, which is
	   represented as an arbitrary scalar.	This must have been set before by either specify-
	   ing -parent in the new() method or by calling the parent() method with a scalar argu-
	   ment.

       $list->tag()
	   Without argument, retrieves information about the list tag, which can be any scalar.
	   This must have been set before by either specifying -tag in the new() method or by
	   calling the tag() method with a scalar argument.

       Pod::Hyperlink

       Pod::Hyperlink is a class for manipulation of POD hyperlinks. Usage:

	 my $link = Pod::Hyperlink->new('alternative text|page/"section in page"');

       The Pod::Hyperlink class is mainly designed to parse the contents of the "L<...>"
       sequence, providing a simple interface for accessing the different parts of a POD hyper-
       link for further processing. It can also be used to construct hyperlinks.

       Pod::Hyperlink->new()
	   The new() method can either be passed a set of key/value pairs or a single scalar
	   value, namely the contents of a "L<...>" sequence. An object of the class "Pod::Hyper-
	   link" is returned. The value "undef" indicates a failure, the error message is stored
	   in $@.

       $link->parse($string)
	   This method can be used to (re)parse a (new) hyperlink, i.e. the contents of a
	   "L<...>" sequence. The result is stored in the current object.  Warnings are stored in
	   the warnings property.  E.g. sections like "L<open(2)>" are deprecated, as they do not
	   point to Perl documents. "L<DBI::foo(3p)>" is wrong as well, the manpage section can
	   simply be dropped.

       $link->markup($string)
	   Set/retrieve the textual value of the link. This string contains special markers "P<>"
	   and "Q<>" that should be expanded by the translator's interior sequence expansion
	   engine to the formatter-specific code to highlight/activate the hyperlink. The details
	   have to be implemented in the translator.

       $link->text()
	   This method returns the textual representation of the hyperlink as above, but without
	   markers (read only). Depending on the link type this is one of the following alterna-
	   tives (the + and * denote the portions of the text that are marked up):

	     +perl+		       L<perl>
	     *$|* in +perlvar+	       L<perlvar/$|>
	     *OPTIONS* in +perldoc+    L<perldoc/"OPTIONS">
	     *DESCRIPTION*	       L<"DESCRIPTION">

       $link->warning()
	   After parsing, this method returns any warnings encountered during the parsing
	   process.

       $link->file()
       $link->line()
	   Just simple slots for storing information about the line and the file the link was
	   encountered in. Has to be filled in manually.

       $link->page()
	   This method sets or returns the POD page this link points to.

       $link->node()
	   As above, but the destination node text of the link.

       $link->alttext()
	   Sets or returns an alternative text specified in the link.

       $link->type()
	   The node type, either "section" or "item". As an unofficial type, there is also
	   "hyperlink", derived from e.g. "L<http://perl.com>"

       $link->link()
	   Returns the link as contents of "L<>". Reciprocal to parse().

       Pod::Cache

       Pod::Cache holds information about a set of POD documents, especially the nodes for hyper-
       links.  The following methods are available:

       Pod::Cache->new()
	   Create a new cache object. This object can hold an arbitrary number of POD documents
	   of class Pod::Cache::Item.

       $cache->item()
	   Add a new item to the cache. Without arguments, this method returns a list of all
	   cache elements.

       $cache->find_page($name)
	   Look for a POD document named $name in the cache. Returns the reference to the corre-
	   sponding Pod::Cache::Item object or undef if not found.

       Pod::Cache::Item

       Pod::Cache::Item holds information about individual POD documents, that can be grouped in
       a Pod::Cache object.  It is intended to hold information about the hyperlink nodes of POD
       documents.  The following methods are available:

       Pod::Cache::Item->new()
	   Create a new object.

       $cacheitem->page()
	   Set/retrieve the POD document name (e.g. "Pod::Parser").

       $cacheitem->description()
	   Set/retrieve the POD short description as found in the "=head1 NAME" section.

       $cacheitem->path()
	   Set/retrieve the POD file storage path.

       $cacheitem->file()
	   Set/retrieve the POD file name.

       $cacheitem->nodes()
	   Add a node (or a list of nodes) to the document's node list. Note that the order is
	   kept, i.e. start with the first node and end with the last.	If no argument is given,
	   the current list of nodes is returned in the same order the nodes have been added.  A
	   node can be any scalar, but usually is a pair of node string and unique id for the
	   "find_node" method to work correctly.

       $cacheitem->find_node($name)
	   Look for a node or index entry named $name in the object.  Returns the unique id of
	   the node (i.e. the second element of the array stored in the node arry) or undef if
	   not found.

       $cacheitem->idx()
	   Add an index entry (or a list of them) to the document's index list. Note that the
	   order is kept, i.e. start with the first node and end with the last.  If no argument
	   is given, the current list of index entries is returned in the same order the entries
	   have been added.  An index entry can be any scalar, but usually is a pair of string
	   and unique id.

AUTHOR
       Marek Rouchal <marek@saftsack.fs.uni-bayreuth.de>, borrowing a lot of things from pod2man
       and pod2roff as well as other POD processing tools by Tom Christiansen, Brad Appleton and
       Russ Allbery.

SEE ALSO
       pod2man, pod2roff, Pod::Parser, Pod::Checker, pod2html

perl v5.8.0				    2002-06-01			     Pod::ParseUtils(3pm)


All times are GMT -4. The time now is 08:52 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password