Pod::Abstract::BuildNoUser)Contributed Perl DocumenPod::Abstract::BuildNode(3)NAMEPod::Abstract::BuildNode - Build new nodes for use in Pod::Abstract.
SYNOPSIS
use Pod::Abstract::BuildNode qw(node nodes); # shorthand
my $root_doc = node->root;
for(my $i = 1; $i < 10; $i ++) {
$root_doc->push(node->head1("Heading number $i"));
}
print $root_doc->pod;
DESCRIPTION
For building a new Pod::Abstract document, or adding nodes to an
existing one. This provides easy methods to generate correctly set
nodes for most common Pod::Abstract elements.
NOTESPod::Abstract::BuildNode can export two functions, "node" and "nodes".
These are constant functions to provide a shorthand so instead of
writing:
use Pod::Abstract::BuildNode;
# ...
my @nodes = Pod::Abstract::BuildNode->from_pod( $pod );
You can instead write:
use Pod::Abstract::BuildNode qw(node nodes);
# ...
my @nodes = nodes->from_pod($pod);
Which is more readable, and less typing. "node" and "nodes" are both
synonyms of "Pod::Abstract::BuildNode".
This shorthand form is shown in all the method examples below. All
methods operate on the class.
METHODS
from_pod
my @nodes = nodes->from_pod($pod_text);
Given some literal Pod text, generate a full subtree of nodes. The
returned array is all of the top level nodes. The full document tree
will be populated under the returned nodes.
root
my $root = node->root;
Generate a root node. A root node generates no output, and is used to
hold a document tree. Use this to make a new document.
begin
my $begin_block = node->begin($command);
Generates a begin/end block. Nodes nested inside the begin node will
appear between the begin/end.
Note that there is no corresponding "end" method - the end command
belongs to it's corresponding begin.
for
my $for = node->for('overlay from <class>');
Create a =for node. The argument is the literal body of the for node,
no parsing will be performed.
paragraph
my $para = node->paragraph('Pod text');
Generates a Pod paragraph, possibly containing interior sequences. The
argument will be parsed as Pod, and will generate text and sequence
nodes inside the paragraph.
verbatim
my $v = node->verbatim($text);
Add the given text as a verbatim node to the document. All lines in the
fiven $text will be indented by one space to ensure they are treated as
verbatim.
heading
my $head2 = node->heading(2, $heading);
Generate a heading node at the given level. Nodes that "belong" in the
heading's section should be nested in the heading node. The $heading
text will be parsed for interior sequences.
head1
node->head1($heading);
head2
node->head2($heading);
head3
node->head3($heading);
head4
node->head4($heading);
over
my $list = node->over([$num]);
Generates an over/back block, to contain list items. The optional
parameter $num specifies the number of spaces to indent by. Note that
the back node is part of the over, there is no separate back method.
item
my $item = node->item('*');
Generates an item with the specified label. To fill in the text of the
item, nest paragraphs into the item. Items should be contained in over
nodes.
text
my $text = node->text('Literal text');
Generates a literal text node. You generally do not want this, you
probably want a paragraph. Use this if you want to, for example, append
a word at the end of a paragraph.
pod
my $n = node->pod;
Generates an "=pod" command. Can be useful to force pod mode at the end
of cut nodes.
Do not confuse with "from_pod"!
my $cut = node->cut;
Generates an explicit "=cut" command.
AUTHOR
Ben Lilburne <bnej@mac.com>
COPYRIGHT AND LICENSE
Copyright (C) 2009 Ben Lilburne
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
perl v5.14.1 2010-01-03 Pod::Abstract::BuildNode(3)
