---
name: "Pod::Abstract::BuildNode"
section: "3pm"
platform: "linux"
package: "libpod-abstract-perl"
version: "0.20-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Pod::Abstract::BuildNode"
---

# Pod::Abstract::BuildNode(3pm)

Build new nodes for use in Pod::Abstract.

## 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.