1Pod::Abstract::BuildNodUes(e3r)Contributed Perl DocumentPaotdi:o:nAbstract::BuildNode(3)
2
3
4

NAME

6       Pod::Abstract::BuildNode - Build new nodes for use in Pod::Abstract.
7

SYNOPSIS

9        use Pod::Abstract::BuildNode qw(node nodes); # shorthand
10
11        my $root_doc = node->root;
12        for(my $i = 1; $i < 10; $i ++) {
13           $root_doc->push(node->head1("Heading number $i"));
14        }
15        print $root_doc->pod;
16

DESCRIPTION

18       For building a new Pod::Abstract document, or adding nodes to an
19       existing one. This provides easy methods to generate correctly set
20       nodes for most common Pod::Abstract elements.
21

NOTES

23       Pod::Abstract::BuildNode can export two functions, "node" and "nodes".
24       These are constant functions to provide a shorthand so instead of
25       writing:
26
27        use Pod::Abstract::BuildNode;
28        # ...
29        my @nodes = Pod::Abstract::BuildNode->from_pod( $pod );
30
31       You can instead write:
32
33        use Pod::Abstract::BuildNode qw(node nodes);
34        # ...
35        my @nodes = nodes->from_pod($pod);
36
37       Which is more readable, and less typing. "node" and "nodes" are both
38       synonyms of "Pod::Abstract::BuildNode".
39
40       This shorthand form is shown in all the method examples below. All
41       methods operate on the class.
42

METHODS

44   from_pod
45        my @nodes = nodes->from_pod($pod_text);
46
47       Given some literal Pod text, generate a full subtree of nodes. The
48       returned array is all of the top level nodes. The full document tree
49       will be populated under the returned nodes.
50
51   root
52        my $root = node->root;
53
54       Generate a root node. A root node generates no output, and is used to
55       hold a document tree. Use this to make a new document.
56
57   begin
58        my $begin_block = node->begin($command);
59
60       Generates a begin/end block. Nodes nested inside the begin node will
61       appear between the begin/end.
62
63       Note that there is no corresponding "end" method - the end command
64       belongs to it's corresponding begin.
65
66   for
67        my $for = node->for('overlay from <class>');
68
69       Create a =for node. The argument is the literal body of the for node,
70       no parsing will be performed.
71
72   paragraph
73        my $para = node->paragraph('Pod text');
74
75       Generates a Pod paragraph, possibly containing interior sequences. The
76       argument will be parsed as Pod, and will generate text and sequence
77       nodes inside the paragraph.
78
79   verbatim
80        my $v = node->verbatim($text);
81
82       Add the given text as a verbatim node to the document. All lines in the
83       fiven $text will be indented by one space to ensure they are treated as
84       verbatim.
85
86   heading
87        my $head2 = node->heading(2, $heading);
88
89       Generate a heading node at the given level. Nodes that "belong" in the
90       heading's section should be nested in the heading node. The $heading
91       text will be parsed for interior sequences.
92
93   head1
94        node->head1($heading);
95
96   head2
97        node->head2($heading);
98
99   head3
100        node->head3($heading);
101
102   head4
103        node->head4($heading);
104
105   over
106        my $list = node->over([$num]);
107
108       Generates an over/back block, to contain list items. The optional
109       parameter $num specifies the number of spaces to indent by. Note that
110       the back node is part of the over, there is no separate back method.
111
112   item
113        my $item = node->item('*');
114
115       Generates an item with the specified label. To fill in the text of the
116       item, nest paragraphs into the item. Items should be contained in over
117       nodes.
118
119   text
120        my $text = node->text('Literal text');
121
122       Generates a literal text node. You generally do not want this, you
123       probably want a paragraph. Use this if you want to, for example, append
124       a word at the end of a paragraph.
125
126   pod
127        my $n = node->pod;
128
129       Generates an "=pod" command. Can be useful to force pod mode at the end
130       of cut nodes.
131
132       Do not confuse with "from_pod"!
133
134
135        my $cut = node->cut;
136
137       Generates an explicit "=cut" command.
138

AUTHOR

140       Ben Lilburne <bnej@mac.com>
141
143       Copyright (C) 2009 Ben Lilburne
144
145       This program is free software; you can redistribute it and/or modify it
146       under the same terms as Perl itself.
147
148
149
150perl v5.38.0                      2023-07-21       Pod::Abstract::BuildNode(3)
Impressum