.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Pod::Abstract::Node 3pm"
.TH Pod::Abstract::Node 3pm "2010-01-03" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Pod::Abstract::Node \- Pod Document Node.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 9
\& $node\->nest( @list );          # Nests list as children of $node. If they
\&                                # exist in a tree they will be detached.
\& $node\->clear;                  # Remove (detach) all children of $node
\& $node\->hoist;                  # Append all children of $node after $node.
\& $node\->detach;                 # Detaches intact subtree from parent
\& $node\->select( $path_exp );    # Selects the path expression under $node
\& $node\->select_into( $target, $path_exp );
\&                                # Selects into the children of the
\&                                # target node.  (copies)
\&
\& $node\->insert_before($target); # Inserts $node in $target\*(Aqs tree
\&                                # before $target
\& $node\->insert_after($target);
\&
\& $node\->push($target);          # Appends $target at the end of this node
\& $node\->unshift($target);       # Prepends $target at the start of this node
\&
\& $node\->path();                 # List of nodes leading to this one
\& $node\->children();             # All direct child nodes of this one
\& $node\->next();                 # Following sibling if present
\& $node\->previous();             # Preceding sibling if present
\&
\& $node\->duplicate();            # Duplicate node and children in a new tree.
\&
\& $node\->pod;                    # Convert node back into literal POD
\& $node\->ptree;                  # Show visual (abbreviated) parse tree
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 3
\& my $node = Pod::Abstract::Node\->new(
\&    type => \*(Aq:text\*(Aq, body => \*(AqSome text\*(Aq,
\& );
.Ve
.PP
Creates a new, unattached Node object. This is \s-1NOT\s0 the recommended way
to make nodes to add to a document, use Pod::Abstract::BuildNode for
that. There are specific rules about how data must be set up for these
nodes, and \f(CW\*(C`new\*(C'\fR lets you ignore them.
.PP
Apart from type and body, all other hash arguments will be converted
into \*(L"params\*(R", which may be internal data or node attributes.
.PP
Type may be:
.IP "\(bu" 4
A plain word, which is taken to be a command name.
.IP "\(bu" 4
\&\f(CW\*(C`:paragraph\*(C'\fR, \f(CW\*(C`:text\*(C'\fR, \f(CW\*(C`:verbatim\*(C'\fR or <:X> (where X is an inline
format letter). These will be treated as you would expect.
.IP "\(bu" 4
\&\f(CW\*(C`#cut\*(C'\fR, meaning this is literal, non-pod text.
.PP
Note that these do not guarantee the resulting document structure will
match your types \- types are derived from the document, not the other
way around. If your types do not match your document they will mutate
when it is reloaded.
.PP
See Pod::Abstract::BuildNode if you want to make nodes easily for
creating/modifying a document tree.
.SS "ptree"
.IX Subsection "ptree"
.Vb 1
\& print $n\->ptree;
.Ve
.PP
Produces a formatted, readable, parse tree. Shows node types, nesting
structure, abbreviated text. Does \s-1NOT\s0 show all information, but shows
enough to help debug parsing/traversal problems.
.SS "text"
.IX Subsection "text"
.Vb 1
\& print $n\->text;
.Ve
.PP
Returns the text subnodes only of the given node, concatenated
together \- i,e, the text only with no formatting at all.
.SS "pod"
.IX Subsection "pod"
.Vb 1
\& print $n\->pod;
.Ve
.PP
Returns the node (and all subnodes) formatted as \s-1POD\s0. A newly loaded
node should produce the original \s-1POD\s0 text when pod is requested.
.SS "select"
.IX Subsection "select"
.Vb 1
\& my @nodes = $n\->select(\*(Aq/:paragraph[//:text =~ {TODO}]\*(Aq);
.Ve
.PP
Select a pPath expression against this node. The above example will
select all paragraphs in the document containing '\s-1TODO\s0' in any of
their text nodes.
.PP
The returned values are the real nodes from the document tree, and
manipulating them will transform the document.
.SS "select_into"
.IX Subsection "select_into"
.Vb 1
\& $node\->select_into($target_node, $path)
.Ve
.PP
As with select, this will match a pPath expression against \f(CW$node\fR \- but
the resulting nodes will be copied and added as children to
\&\f(CW$target_node\fR. The nodes that were added will be returned as a list.
.SS "type"
.IX Subsection "type"
.Vb 1
\& $node\->type( [ $new_type ] );
.Ve
.PP
Get or set the type of the node.
.SS "body"
.IX Subsection "body"
.Vb 1
\& $node\->body( [ $new_body ] );
.Ve
.PP
Get or set the node body text. This is \s-1NOT\s0 the child tree of the node,
it is the literal text as used by text/verbatim nodes.
.SS "param"
.IX Subsection "param"
.Vb 1
\& $node\->param( $p_name [, $p_value ] );
.Ve
.PP
Get or set the named parameter. Any value can be used, but for
document attributes a Pod::Abstract::Node should be set.
.SS "duplicate"
.IX Subsection "duplicate"
.Vb 1
\& my $new_node = $node\->duplicate;
.Ve
.PP
Make a deep-copy of the node. The duplicate node returned has an
identical document tree, but different node identifiers.
.SS "insert_before"
.IX Subsection "insert_before"
.Vb 1
\& $node\->insert_before($target);
.Ve
.PP
Inserts \f(CW$node\fR before \f(CW$target\fR, as a sibling of \f(CW$target\fR. If \f(CW$node\fR is
already in a document tree, it will be removed from it's existing
position.
.SS "insert_after"
.IX Subsection "insert_after"
.Vb 1
\& $node\->insert_after($target);
.Ve
.PP
Inserts \f(CW$node\fR after \f(CW$target\fR, as a sibling of \f(CW$target\fR. If \f(CW$node\fR is
already in a document tree, it will be removed from it's existing
position.
.SS "hoist"
.IX Subsection "hoist"
.Vb 1
\& $node\->hoist;
.Ve
.PP
Inserts all children of \f(CW$node\fR, in order, immediately after
\&\f(CW$node\fR. After this operation, \f(CW$node\fR will have no children. In pictures:
.PP
.Vb 5
\& \- a
\&  \- b
\&  \- c
\&   \- d
\& \-f
\&
\& $a\->hoist; # \->
\&
\& \- a
\& \- b
\& \- c
\&  \- d
\& \- f
.Ve
.SS "clear"
.IX Subsection "clear"
.Vb 1
\& $node\->clear;
.Ve
.PP
Detach all children of \f(CW$node\fR. The detached nodes will be returned, and
can be safely reused, but they will no longer be in the document tree.
.SS "push"
.IX Subsection "push"
.Vb 1
\& $node\->push($target);
.Ve
.PP
Pushes \f(CW$target\fR at the end of \f(CW$node\fR's children.
.SS "nest"
.IX Subsection "nest"
.Vb 1
\& $node\->nest(@new_children);
.Ve
.PP
Adds \f(CW@new_children\fR to \f(CW$node\fR's children. The new nodes will be added at
the end of any existing children. This can be considered the inverse
of hoist.
.SS "unshift"
.IX Subsection "unshift"
.Vb 1
\& $node\->unshift($target);
.Ve
.PP
The reverse of push, add a node to the start of \f(CW$node\fR's children.
.SS "serial"
.IX Subsection "serial"
.Vb 1
\& $node\->serial;
.Ve
.PP
The unique serial number of \f(CW$node\fR. This should never be modified.
.SS "attached"
.IX Subsection "attached"
.Vb 1
\& $node\->attached;
.Ve
.PP
Returns true if \f(CW$node\fR is attached to a document tree.
.SS "detach"
.IX Subsection "detach"
.Vb 1
\& $node\->detach;
.Ve
.PP
Removes a node from it's document tree. Returns true if the node was
removed from a tree, false otherwise. After this operation, the node
will be detached.
.PP
Detached nodes can be reused safely.
.SS "parent"
.IX Subsection "parent"
.Vb 1
\& $node\->parent;
.Ve
.PP
Returns the parent of \f(CW$node\fR if available. Returns undef if no parent.
.SS "root"
.IX Subsection "root"
.Vb 1
\& $node\->root
.Ve
.PP
Find the root node for the tree holding this node \- this may be the
original node if it has no parent.
.SS "children"
.IX Subsection "children"
.Vb 1
\& my @children = $node\->children;
.Ve
.PP
Returns the children of the node in document order.
.SS "next"
.IX Subsection "next"
.Vb 1
\& my $next = $node\->next;
.Ve
.PP
Returns the following sibling of \f(CW$node\fR, if one exists. If there is no
following node undef will be returned.
.SS "previous"
.IX Subsection "previous"
.Vb 1
\& my $previous = $node\->previous;
.Ve
.PP
Returns the preceding sibling of \f(CW$node\fR, if one exists. If there is no
preceding node, undef will be returned.
.SS "coalesce_body"
.IX Subsection "coalesce_body"
.Vb 1
\& $node\->coalesce_body(\*(Aq:verbatim\*(Aq);
.Ve
.PP
This performs node coalescing as required by perlpodspec. Successive
verbatim nodes can be merged into a single node. This is also done
with text nodes, primarily for =begin/=end blocks.
.PP
The named node type will be merged together in the child document
wherever there are two or more successive nodes of that type. Don't
use for anything except \f(CW\*(C`:text\*(C'\fR and \f(CW\*(C`:verbatim\*(C'\fR nodes unless you're
really sure you know what you want.
.SH "AUTHOR"
.IX Header "AUTHOR"
Ben Lilburne <bnej@mac.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2009 Ben Lilburne
.PP
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.