NAME

       Pod::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.

NOTES

       Pod::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.