/ 
Pod-Compiler-0.20
River stage zero No dependents
/ Pod::objects

NAME

Pod::objects - package with objects for representing POD documents

SYNOPSIS

require Pod::objects;
my $root = Pod::root->new;

DESCRIPTION

The following section describes the objects returned by Pod::Compiler and their methods. These objects all inherit from Tree::DAG_Node, so all methods described there are valid as well.

The set/retrieve methods all work in the following way: If no argument is specified, the corresponding value is returned. Otherwise the object's value is set to the given argument and returned.

Common methods

The following methods are common for all the classes:

class->new( @parameters )

Create a new object instance of class. See the individual classes for valid parameters.

$obj->line( $num )

Store/retrieve the line number where this object occurred in the source file. Sets and returns the new value if $num is defined and simply returns the value otherwise.

$obj->as_pod()

This method returns the object in POD syntax, including its child objects. Basically this gives you the same code as in the input file.

$obj->contents_as_pod()

Return this object's children in POD format.

$obj->as_text()

This method returns the object as simple text in ISO-8859-1 encoding. All POD markup is discarded.

$obj->contents_as_text()

Return this object's children as simple text in ISO-8859-1 encoding. This strips all POD markup.

Pod::root

This object represents the root of the POD document and thus serves mainly as a storage for the following classes. It inherits from Storable, so that it can easily be stored to and retrived from the file system.

Pod::root->new( %params )

The creation method takes an optional argument -linelength => num. If this is set to a non-zero value, the as_pod method of Pod::paragraph will reformat the POD to use as much of each line up to num characters.

$root->store( $file )
$root->store_fd( $filehandle )

Store the object (and all its contents) to the given file name/handle using Storable for subsequent retrieval.

Pod::root->read( $file )
Pod::root->read_fd( $filehandle )

Read the given file/handle into a Pod::root object. $file must contain a Pod::root object stored by Storable, otherwise a fatal error is raised.

$root->nodes()

Retrieves this POD's node collection, which is maintained as a Pod::node::collection object.

$root->errors()

Returns the number of errors occured during parsing.

$root->warnings()

Returns the number of warnings occured during parsing.

$root->links()

Returns all Pod::link objects within the parsed document.

Pod::perlcode

If the -perlcode option was true for Pod::Compiler, then these objects represent Perl code blocks in the parsed file.

The as_text method returns the empty string, as_pod the contents.

Pod::perlcode->new( $text )

The new constructor takes an optional parameter, which is the string representing the code block. This string may contain newlines.

$perlcode->contents( $string )

This methods sets/retrieves the code block.

$perlcode->append( $code )

This methods appends $code to the contents.

Pod::paragraph

This represents a simple text paragraph. See Pod::root above for an option that forces the reformatting of the POD code of a paragraph to a certain line length. Forced line breaks, i.e. a newline followed by whitespace is not affected.

Pod::verbatim

This represents a verbatim paragraph, i.e. a block that has leading whitespace on its first line.

$verbatim->addline( $line )

Adds one line to this verbatim paragraph. $line should not contain carriage returns nor newlines.

$verbatim->content( @lines )

Set this verbatim paragraph's contents to @lines. If @lines is omitted, this method simply returns the current contents, i.e. an array of strings that reresent the individual lines. The contents can be cleared completely by saying $verbatim->content( undef ).

Pod::head

This class represents =headX directives. The new method accepts a single argument which denotes the heading level, default is 1.

$head->level( $num )

This sets/retrieves the heading level. Officially supported are only 1 and 2, but higher numbers are not rejected here.

$head->node( $node )

This sets/retrieves the heading's node information. $node and the return value are instances of Pod::node or undef.

$head->nodeid()

This retrieves the heading's node id from node above. Just a shortcut for $head->node->id, and safe in case the node is not defined. Returns the id string or undef.

$head->nodetext()

This retrieves the heading's node text from node above. Just a shortcut for $head->node->text, and safe in case the node is not defined. Returns the node text or undef. The node text is derived from what comes after =item, stripping * (bullets) and \d.? (numbers) as well as all POD markup. The result is what POD links can link to from other documents.

Pod::list

This stores everything that is enclosed by =over ... =back. Note that such a brace may not span =heads.

$list->autoopen( $flag )

This sets/retrieves the autoopen property. A list gets this property when the parser encounters an =item without a previous =over. The parser then opens a (implicit) list which has the autoopen property set to true.

$list->indent( $num )

This sets/retrieves the indent level of the list, i.e. the value that follows =over. Default is 4.

$list->type( $string )

This sets/retrieves the list type. The parser tries to guess this type from the =items it encounters. The three possible types are bullet, number, and definition. In case of doubt, definition wins.

$list->has_items()

This retrieves the number of =items in this list.

Pod::item

This stores a list's =item.

$item->prefix( $string )

This sets the item's prefix. A prefix can be either '*' or 'o' in case of a bullet list or a number, optionally followed by a dot for numbered lists. This is stored separately because links to such nodes do not contain the prefix.

In case of a numbered list this method returns subsequent numbers for each item independent of what was parsed.

$item->node()
$item->nodeid()
$item->nodetext()

See "Pod::head" for the description of these methods.

Pod::begin

This stores everything between =begin ... =end. It is unclear how POD directives in such a block should be handled. The behaviour is undefined and may change in the future.

as_pod returns the original contents, as_text returns the empty string.

$begin->type( $string )

This set/retrieves the begin/end block type, i.e. the first argument after =begin.

$begin->args( $string )

This set/retrieves the begin/end block arguments, i.e. everything the follows the first argument after =begin.

$begin->addchunk( $string )

This adds a chunk to the begin/end block. A chunk is a paragraph.

$begin->contents()

Return the current contents, i.e. the array of all chunks.

Pod::for

This stores =for paragraphs. The as_pod method return the original contents, as_text returns the empty string.

$for->type( $string )

This sets/retrieves the formatter specification of the =for pargraph.

$for->args( $string )

This sets/retrieves everything following the formatter specification up to the next newline.

$for->content( $string )

This sets/retrieves the =for paragraph's contents, i.e. everything following the first newline after the =for directive.

Textual Objects

The following sections describe objects that represent text. They have some common methods:

$textobj->nested()

Gives a string that contains the interior sequence codes in which this object is nested. A string object XXX inside B<...I<XXX>...> would thus return BI.

$textobj->as_pod()

Gives the POD code of this object, including its children.

$textobj->as_text()

Gives the objects text contents. No POD markup will be returned.

Pod::string

This object contains plain ASCII strings. Note that the contents can well include angle brackets (<>). When converted into POD code, these are automatically escaped where necesary.

The new constructor takes an optional argument: the string.

$string->content( $text )

Set/retrieve the string's contents.

Pod::bold

This class represents the B<...> (bold) interior sequence.

Pod::italic

This class represents the I<...> (italic) interior sequence.

Pod::code

This class represents the C<...> (code/courier) interior sequence.

Pod::file

This class represents the F<...> (file) interior sequence.

Pod::nonbreaking

This class represents the S<...> (nonbreaking space) interior sequence.

Pod::zero

This class represents the Z<> (zero width character) interior sequence. Note that this sequence cannot have children.

Pod::idx

This class represents the X<...> (index) interior sequence. The text therein is not printed in the resulting manpage, but is supposed to appear in an index with a hyperlink to the place where it occurred.

$idx->node()
$idx->nodeid()
$idx->nodetext()

See "Pod::head" for the description of these methods.

Pod::entity

This class represents the E<...> (entity) interior sequence. This object has no children, just a value. Entities encountered in the POD source that map to standard ASCII characters (most notably lt, gt, sol and verbar) are not kept as entities, but converted into or appended to the preceding Pod::string, but only if the nesting of this entity permits.

Entities may be specified as textual entities (auml, szlig, etc.), or a numeric. The usual Perl encodings are valid here: 123 is decimal, 0x3a is hexadecimal, 0177 is octal.

The new constructor takes an optional argument, namely the numeric code of the entity to create.

The as_text method returns the corresponding ISO-8859-1 (Latin-1) character. Sorry, no unicode support yet.

$entity->decode( $string )

This method can be given any type of entity encoding and sets the entity value to the resulting code. This code is undef if the given string was not recognized.

$entity->value( $num )

Sets/retrieves the numeric value of this entity.

$entity->as_pod()

Returns the POD representation of this entity. If a textual encoding like auml is known for the value it is used, otherwise decimal encoding.

This is a class for representation of POD hyperlinks. The code to parse the corresponding POD code is entirely in Pod::Compiler.

The new() method can be passed a set of key/value pairs for one-stop initialization.

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 (links to same or other POD document):

page:    L<perl>              the perl manpage
item:    L<perlvar/$!>        the $! entry in the perlvar manpage
item:    L</DESTROY>          the DESTOY entry elsewhere in this
                              document
head:    L<perldoc/"OPTIONS"> the section on OPTIONS in the perldoc
                              manpage
head:    L<"DESCRIPTION">     the section on DESCRIPTION elsewhere
                              in this document

The following are not offical, but are supported:

man:     L<sed(1)>              the sed(1) manpage
url:     L<http://www.perl.com> http://www.perl.com
         (same for ftp: news: mailto:)

If an alternative text (L<alttext|...>) was specified, this text (without POD markup) is returned.

All POD formatters should use the same text for the different types of links. Clever formatters create two hyperlinks for item or section links to another page: one to the top of the page (the page name) and one to the node within the page (the node name).

This method sets or returns the POD page this link points to. If empty, the link points to the current document itself.

As above, but the destination node text (either head or item) of the link.

Sets or returns an alternative text specified in the link.

The node type, either page, man, head or item. As an unofficial type, there is also url, derived from e.g. L<http://perl.com>

The node type, either page, man, head or item. As an unofficial type, there is also url, derived from e.g. L<http://perl.com>

Returns the link as L<...>.

ADDITIONAL CLASSES

The following classes to not inherit from any other package and serve as a convenience storage for POD-related data.

Pod::node

This class stores information about a POD node, i.e. a potential hyperlink destination. This is derived from =headX, =item and X<...> entries. See also "Pod::node::collection".

Pod::node->new( %params )

Creates a new instance of Pod::node. Optional parameters are text, id, type. See below.

$node->text( $string )

Sets/retrieves the node's text. The text is a plain string without any POD markup in ISO-8859-1 encoding.

$node->id( $string )

Sets/retrieves the node's unique id. The id is a string that is unique in the POD document and can be used as a hyperlink anchor.

$node->type( $string )

Sets/retrieves the node's type, which is either headX (X being a number), item or X, depending on from which POD construct this node was derived.

$node->was_hit()

Increments the number of hits to this node. Should be called whenever a link was resolved to this node.

$node->hits()

Retrieves the number of hits on this node.

Pod::node::collection

This class is merely an array that holds Pod::nodes. It provides some methods to search in this set of nodes.

$ncollection->all()

Return an array of all nodes. Nodes are instances of Pod::node.

$ncollection->add( @nodes )

Add the given nodes to the collection. A fatal error occurs when trying to add non-Pod::nodes to the collection. Returns true.

$ncollection->get_by_text( $string )

Returns an array of nodes or the first matching node (depending on context) that exactly matches the node text. The return value should normally be either the empty array or undef for no match and exactly one element that matches, unless several nodes with the same text are in the collection, which should never occur.

$ncollection->get_by_rx( $regexp )

Same as above, but get the node by matching the given $regexp on the node text. A fatal error occurs if the regexp has syntax errors.

$ncollection->get_by_id( $string )

Same as above, but get the node by its unique id.

$ncollection->get_by_type( $string )

Same as above, but get the node by its type. The string is treated as a regexp, so you can get all =head nodes by specifying "head" or all =head1 nodes by giving "head1".

$ncollection->ids()

Return an array of all node ids.

$ncollection->texts()

Return an array of all node texts.

Pod::doc

A convenience class for storing POD document information, especially by converters. See also "Pod::doc::collection".

Pod::doc->new( %params )

Create a new instance of Pod::doc, assigning the given optional parameters. See below for the parameter names, they are identical with the accessor methods.

$doc->name( $string )

Set/retrieve the canonical name of the POD document, e.g. perldoc or Pod::Compiler.

$doc->source( $file )

Set/retrieve the source file name of the POD document, e.g. /usr/local/bin/perldoc or /usr/local/lib/perl5/site_perl/Pod/Compiler.pm.

$doc->temp( $file )

Set/retrieve the temporary file name of the POD document (to be created by (Pod::root object)->store), e.g. /tmp/perldoc.tmp or /tmp/Pod__Compiler.tmp. You have to "invent" a method for generating temp filenames yourself, see also File::Temp.

$doc->destination( $file )

Set/retrieve the destination file name of the POD document, e.g. /usr/local/share/perl/html/perldoc.html or /usr/local/share/perl/Pod/Compiler.html.

$doc->nodes( $nodecollection )

Set/retrieve the this POD document's node collection. When setting, the given argument must be a Pod::node::collection object, otherwise a fatal error occurs.

Pod::doc::collection

This class serves as a container for a set of Pod::doc objects and defines some methods for such a collection. This object is simply a hash with the canonical POD name as key and the corresponding Pod::doc object as value.

Pod::doc::collection->new()

Create a new collection instance.

$dcollection->all_names()

Return an array of all sorted documents names in the collection.

$dcollection->all_objs()

Return an array of all Pod::docs in the collection. There is no specific sort order.

$dcollection->get( $name )

Return the Pod::doc object associated with the name $name or undef if no such name is in the collection.

$dcollection->add( $name , $object )
$dcollection->add( $object )

Add the given Pod::doc object to the collection. The two-argument form explicitely sets the name to $name, otherwise the objects name is used. Exceptions occur if arguments are missing or have the wrong type or the name is empty.

This method tries to resolve the given link (object of class Pod::link) in the document named $name within the document collection. Returns the Pod::doc and the Pod::node in case of success. If the node was found in the current POD (defined by $name) then the first return value will be the empty string. If a node was found, its hit count is automatically incremented. Example:

my ($page,$node) = $dcollection->resolve_link( $link, $myname );
unless(defined $page) {
  warn "Error: Cannot resolve link.\n";
}
elsif(!$page) {
  # node is in the current POD $myname
}
else {
  # link to another POD
}

SEE ALSO

Pod::Compiler, Pod::Parser, Pod::Find, Pod::Checker

AUTHOR

Marek Rouchal <marekr@cpan.org>