Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Pod::ParseUtils(3)    User Contributed Perl Documentation   Pod::ParseUtils(3)

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
       NOTE: This module is considered legacy; modern Perl releases (5.18 and
       higher) are going to remove Pod-Parser from core	and use	Pod-Simple for
       all things POD.

       Pod::ParseUtils contains	a few object-oriented helper packages for POD
       parsing and processing (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 specifying -type in	the
	   new() method	or by calling the type() method	with a scalar
	   argument.

       $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 specifying -parent in	the new()
	   method or by	calling	the parent() method with a scalar argument.

       $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	hyperlink 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::Hyperlink"	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	alternatives (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 hyperlinks.  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 corresponding 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 array) 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
       Please report bugs using	<http://rt.cpan.org>.

       Marek Rouchal <marekr@cpan.org>,	borrowing a lot	of things from pod2man
       and pod2roff as well as other POD processing tools by Tom Christiansen,
       Brad Appleton and Russ Allbery.

       Pod::ParseUtils is part of the Pod::Parser distribution.

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

perl v5.32.1			  2021-08-26		    Pod::ParseUtils(3)

NAME | SYNOPSIS | DESCRIPTION | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Pod::ParseUtils&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help