--- name: "Pod::Tree::Node" section: "3pm" platform: "linux" package: "libpod-tree-perl" version: "1.31-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Pod::Tree::Node" --- # Pod::Tree::Node(3pm) nodes in a Pod::Tree ## NAME Pod::Tree::Node - nodes in a Pod::Tree ## SYNOPSIS ``` $node = Pod::Tree::Node->root ( \@paragraphs ); $node = Pod::Tree::Node->code ( $paragraph ); $node = Pod::Tree::Node->verbatim ( $paragraph ); $node = Pod::Tree::Node->command ( $paragraph ); $node = Pod::Tree::Node->ordinary ( $paragraph ); $node = Pod::Tree::Node->letter ( $token ); $node = Pod::Tree::Node->sequence ( $letter, \@children ); $node = Pod::Tree::Node->text ( $text ); $node = Pod::Tree::Node->target ( $target ); $node = Pod::Tree::Node->link ( $node, $page, $section ); $node->is_code and ... $node->is_command and ... $node->is_for and ... $node->is_item and ... $node->is_letter and ... $node->is_list and ... $node->is_ordinary and ... $node->is_pod and ... $node->is_root and ... $node->is_sequence and ... $node->is_text and ... $node->is_verbatim and ... $node->is_link and ... $node->is_c_head1 and ... $node->is_c_head2 and ... $node->is_c_head3 and ... $node->is_c_head4 and ... $node->is_c_cut and ... $node->is_c_pod and ... $node->is_c_over and ... $node->is_c_back and ... $node->is_c_item and ... $node->is_c_for and ... $node->is_c_begin and ... $node->is_c_end and ... $arg = $node->get_arg ; $brackets = $node->get_brackets ; $children = $node->get_children ; $command = $node->get_command ; $domain = $node->get_domain ; $item_type = $node->get_item_type ; $letter = $node->get_letter ; $list_type = $node->get_list_type ; $page = $node->get_page ; $raw = $node->get_raw ; $raw_kids = $node->get_raw_kids ; $section = $node->get_section ; $siblings = $node->get_siblings ; $target = $node->get_target ; $text = $node->get_text ; $type = $node->get_type ; $deep_text = $node->get_deep_text ; $node->force_text($text); $node->force_for; $node->parse_begin (\@nodes); $node->set_children(\@children); $node->make_sequences; $node->parse_links; $node->unescape; $node->consolidate; $node->make_lists; $node->clone; $node->dump; Pod::Tree::Node->set_filename($filename); $filename = $node->get_filename; ``` ## REQUIRES Pod::Escapes ## DESCRIPTION `"Pod::Tree::Node"` objects are nodes in a tree that represents a POD. Applications walk the tree to recover the structure and content of the POD. Methods are provided for - • creating nodes in the tree - • parsing the POD into nodes - • returning information about nodes - • walking the tree ## TREE STRUCTURE ### Root node The tree descends from a single root node; `"is_root"` returns true on this node and no other. ``` $children = $root->get_children ``` returns a reference to an array of nodes. These nodes represent the POD. ### Node types For each node, call `"get_type"` to discover the type of the node ``` for $child (@$children) { $type = $child->get_type; } ``` *$type* will be one of these strings: - 'root' The node is the root of the tree. - 'code' The node represents a paragraph that is not part of the POD. - 'verbatim' The node represents a verbatim paragraph. - 'ordinary' The node represents an ordinary paragraph. - 'command' The node represents an =command paragraph (but not an =over paragraph). - 'sequence' The node represents an interior sequence. - 'target' The node represents the target of a link (An L\<\> markup). - 'text' The node represents text that contains no interior sequences. - 'list' The node represents an =over list. - 'item' The node represents an item in an =over list. - 'for' The node represents a =for paragraph, or it represents the paragraphs between =begin/=end commands. Here are instructions for walking these node types. ### root node Call ``` $children = $node->get_children ``` to get a list of nodes representing the POD. ### code nodes A code node contains the text of a paragraph that is not part of the POD, for example, a paragraph that follows an `"=cut"` command. Call ``` $text = $node->get_text ``` to recover the text of the paragraph. ### verbatim nodes A verbatim node contains the text of a verbatim paragraph. Call ``` $text = $node->get_text ``` to recover the text of the paragraph. ### ordinary nodes An ordinary node represents the text of an ordinary paragraph. The text is parsed into a list of text and sequence nodes; these nodes are the children of the ordinary node. Call ``` $children = $node->get_children ``` to get a list of the children. Iterate over this list to recover the text of the paragraph. ### command nodes A command node represents an =command paragraph. Call ``` $command = $node->get_command; ``` to recover the name of the command. The name is returned *without* the equals sign. \=over paragraphs are represented by list nodes, not command nodes; see "list nodes", below. The text of a command paragraph is parsed into a list of text and sequence nodes; these nodes are the children of the command node. Call ``` $children = $node->get_children; ``` to get a list of the children. Iterate over this list to recover the text of the paragraph. ### sequence nodes A sequence node represents a single interior sequence (a \<\> markup). Call ``` $node->get_letter ``` to recover the original markup letter. The contents of the markup are parsed into a list of text and sequence nodes; these nodes are the children of the sequence node. Call ``` $node->get_children ``` to recover them. Z\<\> and E\<\> markups do not generate sequence nodes; these markups are expanded by `"Pod::Tree"` when the tree is built. ### target nodes If a sequence node represents a link (an `"L<>"` markup), then ``` is_link $node ``` returns true and ``` $target = $node->get_target ``` returns a node representing the target of the link. `"Pod::Tree::Node"` can represent targets in two *domains*: `"POD"` and `"HTTP"`. The `"POD"` domain represents the ``` L ``` markups that are described in perlpod. The `"HTTP"` domain represents `"L<>"` markups that contain a URL, e.g. ``` L ``` Call ``` $domain = $target->get_domain ``` to discover the domain of the target. For targets in the POD domain, call ``` $page = $target->get_page; $section = $target->get_section; ``` to recover the man page and section that the link refers to. For targets in the HTTP domain, call ``` $url = $target->get_page; ``` to recover the URL for the link. *$target* is used only for constructing hyper-links; the text to be displayed for the link is recovered by walking the children of *$node*, as for any other interior sequence. ### text nodes A text node represents text that contains no interior sequences. Call ``` $text = $node->get_text ``` to recover the text. ### list nodes A list node represents an =over list. Call ``` $list_type = $node->get_list_type; ``` to discover the type of the list. This will be one of the strings - 'bullet' - 'number' - 'text' The type of a list is the type of the first item in the list. The children of a list node are item nodes; each item node represents one item in the list. You can call ``` $node->get_arg; ``` to recover the indent value following the =over. ### item nodes An item node represents one item in an =over list. Call ``` $item_type = $node->get_item_type; ``` to discover the type of the item. This will be one of the strings shown above for "list nodes". Typically, all the items in a list have the same type, but `"Pod::Tree::Node"` doesn't assume this. The children of an item node represent the text of the =item paragraph; this is usually of interest only for 'text' items. Call ``` $children = $node->get_children ``` to get a list of the children; these will be sequence and text nodes, as for any other =command paragraph. Each item node also has a list of nodes representing all the paragraphs following it, up to the next =item command, or the end of the list. These nodes are called *siblings* of the item node. Call ``` $siblings = $node->get_siblings ``` to get a list of sibling nodes. ### for nodes for nodes represent text that is to be passed to an external formatter. Call ``` $formatter = $node->get_arg; ``` to discover the name of the formatter. Call ``` $text = $node->get_text; ``` to obtain the text to be passed to the formatter. This will either be the text of an =for command, or all of the text between =begin and =end commands. ### Walking the tree PODs have a recursive structure; therefore, any application that walks a Pod::Tree must also be recursive. See *skeleton* for an example of the necessary code. ## METHODS ### Constructors These methods construct `"Pod::Tree::Node"` objects. They are used to build trees. They aren't necessary to walk trees. ``` $node = root Pod::Tree::Node \@paragraphs; $node = code Pod::Tree::Node $paragraph; $node = verbatim Pod::Tree::Node $paragraph; $node = command Pod::Tree::Node $paragraph; $node = ordinary Pod::Tree::Node $paragraph; $node = letter Pod::Tree::Node $token; $node = sequence Pod::Tree::Node $letter, \@children; $node = text Pod::Tree::Node $text; $node = target Pod::Tree::Node $target; $node = link Pod::Tree::Node $node, $page, $section; ``` - *$link* = "Pod::Tree::Node"-\>"link"(*$node*, *$page*, *$section*) Creates a new sequence node representing an `"L<>"` markup. *$node* becomes the sole child of the new node. The target of the node is constructed from *$page* and *$section*. This method isn't used to parse PODs. It is provided for applications that want to create new links in an existing `"Pod::Tree"` structure. ### Tests These methods return true iff *$node* has the type indicated by the method name. ``` is_code $node and ... is_command $node and ... is_for $node and ... is_item $node and ... is_letter $node and ... is_link $node and ... is_list $node and ... is_ordinary $node and ... is_pod $node and ... is_root $node and ... is_sequence $node and ... is_text $node and ... is_verbatim $node and ... ``` `"is_pod"` returns true for all nodes except code, `"=pod"`, and `"=cut"` nodes. These methods return true iff *$node* is a command node, and the command is the one indicated by the method name. ``` is_c_head1 $node and ... is_c_head2 $node and ... is_c_head3 $node and ... is_c_head4 $node and ... is_c_cut $node and ... is_c_pod $node and ... is_c_over $node and ... is_c_back $node and ... is_c_item $node and ... is_c_for $node and ... is_c_begin $node and ... is_c_end $node and ... ``` ### Accessors These methods return information about nodes. Most accessors are only relevant for certain types of nodes. - *$arg* = "get\_arg" *$node* Returns the argument of *$node*. This is the number following an =over command, or the name of an external translator for =for, =begin, and =end commands. Only relevant for these four command nodes. - *$brackets* = "get\_brackets" *$node* Only relevant for for nodes. If the node represents an =for command, *@$brackets* is a single-element list. The list element is the text of the =for command and its argument, i.e. the name of the external formatter. If the node represents a =begin/=end construct, *@$brackets* is a two-element list containing the text of the =begin and =end paragraphs. - *$children* = "get\_children" *$node* Returns a reference to the list of nodes that are children of *$node*. May be called on any node. The list may be empty. - *$command* = "get\_command" *$node* Returns the name of a command, without the equals sign. Only relevant for command nodes. - *$domain* = "get\_domain" *$node* Only relevant for target nodes. Returns the domain of the target. This will be one of the strings - 'HTTP' - 'POD' - *$item\_type* = "get\_item\_type" *$node* Returns the type of an item node. The type will be one of - 'bullet' - 'number' - 'text' - *$letter* = "get\_letter" *$node* Returns the letter that introduces an interior sequence. Only relevant for sequence nodes. - *$list\_type* = "get\_list\_type" *$node* Returns the type of a list node. The type of a list node is the type of the first item node in the list. - *$page* = "get\_page" *$node* Only relevant for target nodes. For targets in the `"POD"` domain, returns the man page that is the target of the link. For targets in the `"HTTP"` domain, returns the URL that is the target of the link. - *$raw* = "get\_raw" *$node* Returns the original text of a paragraph. Currently provided for command, verbatim, and ordinary paragraphs. - *$raw\_kids* = "get\_raw\_kids" *$node* Only provided for L\<\> sequence nodes. Returns a reference to a list of nodes representing the entire text of the L\<\> sequence, including any part following a vertical bar (\|). The original text of the L\<\> markup can be reconstructed from this list. - *$section* = "get\_section" *$node* Only relevant for target nodes in the `"POD"` domain. Returns the section that is the target of a link. - *$siblings* = "get\_siblings" *$node* Returns the siblings of a node. May be called on any node. Only item nodes have siblings. - *$target* = "get\_target" *$node* Returns the target of a node. Only relevant for sequence nodes that represent links (`"L<>"` markups). `"is_link"` returns true on these nodes. - *$text* = "get\_text" *$node* Returns the text of a node. *$text* will not contain any interior sequences. Only relevant for text nodes. - *$type* = "get\_type" *$node* Returns the type of *$node*. May be called on any node. See "TREE STRUCTURE" for descriptions of the node types. - *$deep\_text* = "get\_deep\_text" *$node* Recursively walks the children of a node, catenates together the text from each node, and returns all that text as a single string. All interior sequence markups are discarded. `"get_deep_text"` is provided as a convenience for applications that want to ignore markups in a POD paragraph. ### Parsing These methods manipulate the tree while it is being built. They aren't necessary to walk the tree. ``` $node->force_text($text) $node->force_for; $node->parse_begin (\@nodes); $node->set_children(\@children); $node->make_sequences; $node->parse_links; $node->unescape; $node->consolidate; $node->make_lists; ``` ### Utility - *$node*-\>"clone" Returns a deep copy of a node. Only implemented for `"text"` and `"sequence"` nodes. - *$node*-\>"dump" Returns a string containing a pretty-printed representation of the node. Calling `"dump"` on the root node of a tree will show the entire POD. - "Pod::Tree::Node"-\>"set\_filename"(*$filename*) Sets the file name to be reported in error messages. - *$filename* = $*node*-\>"getfile\_name" Returns the file name set by `"set_file_name"`. ## EXAMPLES The *t/* directory in the `"Pod::Tree"` distribution contains examples of PODs, together with dumps of the trees that `"Pod::Tree"` constructs for them. The tree for `"t/"`*file*`".pod"` is in `"t/"`*file*`".p_exp"`. `"Pod::Tree::Node::dump"` is a simple example of code that walks a POD tree. *skeleton* is a skeleton application that walks a POD tree. ## NOTES - • There is no provision in perlpod for `"L<>"` markups to contain URLs, but due to popular demand, this is now supported in `"Pod::Tree::Node"`. ## SEE ALSO [**perl**(1)](/perl/1.md), `"Pod::Tree"` ## AUTHOR Steven McDougall, swmcd@world.std.com ## COPYRIGHT Copyright (c) 1999-2004 by Steven McDougall. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.