libpod-tree-perl 1.25-1 / usr / share / perl5 / Pod / Tree / Node.pm

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

package Pod::Tree::Node;

use strict;
use warnings;
use Pod::Escapes ();

our $VERSION = '1.25';

sub root    # ctor
{
	my ( $class, $children ) = @_;

	my $node = {
		type     => 'root',
		children => $children
	};

	bless $node, $class;
}

sub code    #ctor
{
	my ( $class, $paragraph ) = @_;

	my $node = {
		type => 'code',
		text => $paragraph
	};

	bless $node, $class;
}

sub verbatim    # ctor
{
	my ( $class, $paragraph ) = @_;

	my $node = {
		type => 'verbatim',
		raw  => $paragraph,
		text => $paragraph
	};

	bless $node, $class;
}

my %Argumentative = map { $_ => 1 } qw(=over
	=for =begin =end);

sub command    # ctor
{
	my ( $class, $paragraph ) = @_;
	my ( $command, $arg, $text );

	($command) = split( /\s/, $paragraph );

	if ( $Argumentative{$command} ) {
		( $command, $arg, $text ) = split( /\s+/, $paragraph, 3 );
	}
	else {
		( $command, $text ) = split( /\s+/, $paragraph, 2 );
		$arg = '';
	}

	$command =~ s/^=//;

	my $node = {
		type    => 'command',
		raw     => $paragraph,
		command => $command,
		arg     => $arg,
		text    => $text
	};

	bless $node, $class;
}

sub ordinary    # ctor
{
	my ( $class, $paragraph ) = @_;

	my $node = {
		type => 'ordinary',
		raw  => $paragraph,
		text => $paragraph
	};

	bless $node, $class;
}

sub letter    # ctor
{
	my ( $class, $token ) = @_;

	my $node = {
		type => 'letter',
		letter => substr( $token, 0, 1 ),
		width  => $token =~ tr/</</
	};

	bless $node, $class;
}

sub sequence    # ctor
{
	my ( $class, $letter, $children ) = @_;

	my $node = {
		type     => 'sequence',
		'letter' => $letter->{'letter'},
		children => $children
	};

	bless $node, $class;
}

sub text    # ctor
{
	my ( $class, $text ) = @_;

	my $node = {
		type => 'text',
		text => $text
	};

	bless $node, $class;
}

sub target    # ctor
{
	my ( $class, $children ) = @_;

	my $node = bless {
		type     => 'target',
		children => $children
	}, $class;

	$node->unescape;
	my $text = $node->get_deep_text;

	if ( $text =~ m(^[A-Za-z]+:(?!:)) )    # a URL
	{
		$node->{page}    = $text;
		$node->{section} = '';
		$node->{domain}  = 'HTTP';
	}
	else                                   # a POD link
	{
		my ( $page, $section ) = SplitTarget($text);
		$node->{page}    = $page;
		$node->{section} = $section;
		$node->{domain}  = 'POD';
	}

	$node;
}

sub SplitTarget {
	my $text = shift;
	my ( $page, $section );

	if ( $text =~ /^"(.*)"$/s )    # L<"sec">;
	{
		$page    = '';
		$section = $1;
	}
	else                           # all other cases
	{
		( $page, $section ) = ( split( m(/), $text, 2 ), '', '' );

		$page =~ s/\s*\(\d\)$//;         # ls (1) -> ls
		$section =~ s( ^" | "$ )()xg;    # lose the quotes

		# L<section in this man page> (without quotes)
		if ( $page !~ /^[\w.-]+(::[\w.-]+)*$/ and $section eq '' ) {
			$section = $page;
			$page    = '';
		}
	}

	$section =~ s(   \s*\n\s*   )( )xg;    # close line breaks
	$section =~ s( ^\s+ | \s+$  )()xg;     # clip leading and trailing WS

	( $page, $section );
}

sub link                                   # ctor
{
	my ( $class, $node, $page, $section ) = @_;

	my $target = bless {
		type     => 'target',
		domain   => 'POD',
		children => [$node],
		page     => $page,
		section  => $section
	}, $class;

	my $link = bless {
		type     => 'sequence',
		letter   => 'L',
		children => [$node],
		target   => $target
	}, $class;

	$link;
}

sub is_code     { shift->{type} eq 'code' }
sub is_command  { shift->{type} eq 'command' }
sub is_for      { shift->{type} eq 'for' }
sub is_item     { shift->{type} eq 'item' }
sub is_letter   { shift->{type} eq 'letter' }
sub is_list     { shift->{type} eq 'list' }
sub is_ordinary { shift->{type} eq 'ordinary' }
sub is_root     { shift->{type} eq 'root' }
sub is_sequence { shift->{type} eq 'sequence' }
sub is_text     { shift->{type} eq 'text' }
sub is_verbatim { shift->{type} eq 'verbatim' }

sub is_link {
	my $node = shift;
	is_sequence $node and $node->{'letter'} eq 'L';
}

sub is_pod {
	my $node = shift;
	not is_code $node and not is_c_cut $node and not is_c_pod $node;
}

sub is_c_head1 {
	my $node = shift;
	$node->{type} eq 'command' and $node->{'command'} eq 'head1';
}

sub is_c_head2 {
	my $node = shift;
	$node->{type} eq 'command' and $node->{'command'} eq 'head2';
}

sub is_c_head3 {
	my $node = shift;
	$node->{type} eq 'command' and $node->{'command'} eq 'head3';
}

sub is_c_head4 {
	my $node = shift;
	$node->{type} eq 'command' and $node->{'command'} eq 'head4';
}

sub is_c_cut {
	my $node = shift;
	$node->{type} eq 'command' and $node->{'command'} eq 'cut';
}

sub is_c_pod {
	my $node = shift;
	$node->{type} eq 'command' and $node->{'command'} eq 'pod';
}

sub is_c_over {
	my $node = shift;
	$node->{type} eq 'command' and $node->{'command'} eq 'over';
}

sub is_c_back {
	my $node = shift;
	$node->{type} eq 'command' and $node->{'command'} eq 'back';
}

sub is_c_item {
	my $node = shift;
	$node->{type} eq 'command' and $node->{'command'} eq 'item';
}

sub is_c_for {
	my $node = shift;
	$node->{type} eq 'command' and $node->{'command'} eq 'for';
}

sub is_c_begin {
	my $node = shift;
	$node->{type} eq 'command' and $node->{'command'} eq 'begin';
}

sub is_c_end {
	my $node = shift;
	$node->{type} eq 'command' and $node->{'command'} eq 'end';
}

sub get_arg       { shift->{arg} }
sub get_back      { shift->{back} }
sub get_children  { shift->{children} }
sub get_command   { shift->{'command'} }
sub get_domain    { shift->{domain} }
sub get_item_type { shift->{item_type} }
sub get_letter    { shift->{'letter'} }
sub get_list_type { shift->{list_type} }
sub get_page      { shift->{page} }
sub get_raw       { shift->{raw} }
sub get_raw_kids  { shift->{raw_kids} }
sub get_section   { shift->{section} }
sub get_siblings  { shift->{siblings} }
sub get_target    { shift->{'target'} }
sub get_text      { shift->{'text'} }
sub get_type      { shift->{'type'} }
sub get_url       { shift->{'url'} }

sub get_brackets {
	my $node     = shift;
	my $brackets = $node->{brackets};
	$brackets;
}

sub get_deep_text {
	my $node = shift;

	for ( $node->get_type ) {
		/text/     and return $node->{'text'};
		/verbatim/ and return $node->{'text'};
	}

	join '', map { $_->get_deep_text } @{ $node->{children} };
}

sub force_text {
	my ( $node, $text ) = @_;
	$node->{type} = 'text';
	$node->{'text'} = $text;
	undef $node->{children};
}

sub force_for {
	my $node = shift;
	$node->{type} = 'for';

	my ($bracket) = $node->{raw} =~ /^(=\w+\s+\w+\s+)/;

	$node->{brackets} = [$bracket];
}

sub parse_begin {
	my ( $node, $nodes ) = @_;

	my $foreign;
	my @raw;
	while (@$nodes) {
		$foreign = shift @$nodes;
		is_c_end $foreign and last;
		push @raw, $foreign->{'raw'};
	}
	$node->{'text'} = join '', @raw;

	my $interpreter = $foreign->{arg};
	$interpreter
		and $interpreter ne $node->{arg}
		and $node->_warn("Mismatched =begin/=end tags around\n$node->{'text'}");

	$node->{type} = 'for';
	$node->{brackets} = [ $node->{raw}, $foreign->{raw} ];
}

sub set_children {
	my ( $node, $children ) = @_;
	$node->{children} = $children;
}

sub make_sequences {
	my $node      = shift;
	my $text      = $node->{'text'};
	my @tokens    = split /( [A-Z]<<+\s+ | [A-Z]< | \s+>>+ | > )/x, $text;
	my $sequences = _parse_text( \@tokens );
	$node->{children} = $sequences;
}

sub _parse_text {
	my $tokens = shift;
	my ( @stack, @width );

	while (@$tokens) {
		my $token = shift @$tokens;
		length $token or next;

		$token =~ /^[A-Z]</ and do {
			my $width = $token =~ tr/</</;
			push @width, $width;
			my $node = letter Pod::Tree::Node $token;
			push @stack, $node;
			next;
		};

		@width and $token =~ />{$width[-1],}$/ and do {
			my $width = pop @width;
			my ( $letter, $interior ) = _pop_sequence( \@stack, $width );
			my $node = sequence Pod::Tree::Node $letter, $interior;
			push @stack, $node;
			$token =~ s/^\s*>{$width}//;
			my @tokens = split //, $token;
			unshift @$tokens, @tokens;
			next;
		};

		my $node = text Pod::Tree::Node $token;
		push @stack, $node;
	}

	if (@width) {
		my @text = map { $_->get_deep_text } @stack;
		Pod::Tree::Node->_warn("Missing '>' delimiter in\n@text");
	}

	\@stack;
}

sub _pop_sequence {
	my ( $stack, $width ) = @_;
	my ( $node, @interior );

	while (@$stack) {
		$node = pop @$stack;
		is_letter $node
			and $node->{width} == $width
			and return ( $node, \@interior );
		unshift @interior, $node;
	}

	my @text = map { $_->get_deep_text } @interior;
	$node->_warn("Mismatched sequence delimiters around\n@text");

	$node = letter Pod::Tree::Node ' ';
	$node, \@interior;
}

sub parse_links {
	my $node = shift;

	is_link $node and $node->_parse_link;

	my $children = $node->{children};
	for my $child (@$children) {
		$child->parse_links;
	}
}

sub _parse_link {
	my $node = shift;

	$node->{raw_kids} = $node->clone->{children};

	my $children = $node->{children};
	my ( $text_kids, $target_kids ) = SplitBar($children);

	$node->{children} = $text_kids;
	$node->{'target'} = target Pod::Tree::Node $target_kids;
}

sub SplitBar {
	my $children = shift;
	my ( @text, @link );

	while (@$children) {
		my $child = shift @$children;

		is_text $child or do {
			push @text, $child;
			next;
		};

		my ( $text, $link ) = split m(\|), $child->{'text'}, 2;
		$link and do {
			push @text, text Pod::Tree::Node $text if $text;
			push @link, ( text Pod::Tree::Node $link), @$children;
			return ( \@text, \@link );
		};

		push @text, $child;
	}

	( \@text, \@text );
}

sub unescape {
	my $node = shift;

	my $children = $node->{children};
	for my $child (@$children) {
		$child->unescape;
	}

	is_sequence $node and $node->_unescape_sequence;
}

sub _unescape_sequence {
	my $node = shift;

	for ( $node->{'letter'} ) {
		/Z/ and $node->force_text(''), last;
		/E/ and do {
			my $child = $node->{children}[0];
			$child or last;
			my $text = $child->_unescape_text;
			$text and $node->force_text($text);
			last;
		};
	}
}

sub _unescape_text {
	my $node = shift;
	my $text = $node->{'text'};

	defined $text ? Pod::Escapes::e2char($text) : "E<UNDEF?!>";
}

sub consolidate {
	my $node = shift;
	my $old  = $node->{children};
	$old and @$old or return;

	my $new = [];

	push @$new, shift @$old;

	while (@$old) {
		if (   is_text $new->[-1] and is_text $old->[0]
			or is_verbatim $new->[-1] and is_verbatim $old->[0]
			or is_code $new->[-1] and is_code $old->[0] )
		{
			$new->[-1]{'text'} .= $old->[0]{'text'};
			shift @$old;
		}
		else {
			push @$new, shift @$old;
		}
	}

	$node->{children} = $new;

	for my $child (@$new) {
		$child->consolidate;
	}
}

sub make_lists {
	my $root  = shift;
	my $nodes = $root->{children};

	$root->_make_lists($nodes);
}

sub _make_lists {
	my ( $node, $old ) = @_;
	my $new = [];
	my $back;

	while (@$old) {
		my $child = shift @$old;
		is_c_over $child and $child->_make_lists($old);
		is_c_item $child and $child->_make_item($old);
		is_c_back $child and $back = $child, last;
		push @$new, $child;
	}

	$node->{children} = $new;

	is_root $node and return;

	$node->{type} = 'list';
	$node->{back} = $back;
	$node->_set_list_type;
}

sub _set_list_type {
	my $list     = shift;
	my $children = $list->{children};

	$list->{list_type} = '';    # -w

	for my $child (@$children) {
		$child->{type} eq 'item' or next;
		$list->{list_type} = $child->{item_type};
		last;
	}
}

sub _make_item {
	my ( $item, $old ) = @_;
	my $siblings = [];

	while (@$old) {
		my $sibling = $old->[0];
		is_c_item $sibling and last;
		is_c_back $sibling and last;

		shift @$old;
		is_c_over $sibling and do {
			$sibling->_make_lists($old);
		};
		push @$siblings, $sibling;
	}

	$item->{type}     = 'item';
	$item->{siblings} = $siblings;
	$item->_set_item_type;
}

sub _set_item_type {
	my $item = shift;
	my $text = $item->{'text'};

	$text =~ m(^\s* \*  \s*$ )x and $item->{item_type} = 'bullet';
	$text =~ m(^\s* \d+ \s*$ )x and $item->{item_type} = 'number';
	$item->{item_type} or $item->{item_type} = 'text';
}

sub clone {
	my $node  = shift;
	my $clone = {%$node};

	my $children = $node->{children};
	$clone->{children} = [ map { $_->clone } @$children ];

	bless $clone, ref $node;
}

my $Indent;
my $String;

sub dump {
	my $node = shift;

	$Indent = 0;
	$String = '';
	$node->_dump;
	$String;
}

sub _dump {
	my $node = shift;
	my $type = $node->get_type;

	$String .= ' ' x $Indent . uc $type . " ";

	for ($type) {
		/command/  and $String .= $node->_dump_command;
		/code/     and $String .= $node->_dump_code;
		/for/      and $String .= $node->_dump_for;
		/item/     and $String .= $node->_dump_item;
		/list/     and $String .= $node->_dump_list;
		/ordinary/ and $String .= "\n";
		/root/     and $String .= "\n";
		/sequence/ and $String .= $node->_dump_sequence;
		/text/     and $String .= $node->_dump_text;
		/verbatim/ and $String .= $node->_dump_verbatim;
	}

	$node->_dump_children;
	$node->_dump_siblings;
}

sub _dump_command {
	my $node    = shift;
	my $command = $node->get_command;
	my $arg     = $node->get_arg;

	"$command $arg\n";
}

sub _dump_code {
	my $node = shift;

	my $text = _indent( $node->get_text, 3 );
	my $block = "\n{\n$text}\n";

	_indent( $block, $Indent );
}

sub _dump_for {
	my $node = shift;
	my $arg  = $node->get_arg;
	my $text = _indent( $node->get_text, $Indent + 3 );

	"$arg\n$text\n";
}

sub _dump_item {
	my $node = shift;
	uc $node->get_item_type . "\n";
}

sub _dump_list {
	my $node = shift;
	uc $node->get_list_type . "\n";
}

sub _dump_sequence {
	my $node   = shift;
	my $letter = $node->get_letter;
	my $link   = $node->is_link ? $node->_dump_target : '';

	"$letter$link\n";
}

sub _dump_text {
	my $node = shift;
	my $text = $node->get_text;

	$text =~ s/([\x80-\xff])/sprintf("\\x%02x", ord($1))/eg;

	my $indent = ' ' x ( $Indent + 5 );
	$text =~ s( (?<=\n) (?=.) )($indent)xg;
	"$text\n";
}

sub _dump_verbatim {
	my $node = shift;
	"\n" . $node->get_text . "\n";
}

sub _dump_target {
	my $node    = shift;
	my $target  = $node->get_target;
	my $page    = $target->{page};
	my $section = $target->{section};
	" $page / $section";
}

sub _dump_children {
	my $node     = shift;
	my $children = $node->get_children;
	$children and DumpList( $children, '{', '}' );
}

sub _dump_siblings {
	my $node     = shift;
	my $siblings = $node->get_siblings;
	$siblings and DumpList( $siblings, '[', ']' );
}

sub DumpList {
	my ( $nodes, $open, $close ) = @_;

	$String .= ' ' x $Indent . "$open\n";
	$Indent += 3;

	for my $node (@$nodes) {
		$node->_dump;
	}

	$Indent -= 3;
	$String .= ' ' x $Indent . "$close\n";
}

sub _indent {
	my ( $text, $spaces ) = @_;
	my $indent = ' ' x $spaces;
	$text =~ s( (?<=\n) (?=.) )($indent)xg;
	$indent . $text;
}

sub _warn {
	my ( $node, $message ) = @_;

	my $filename = $node->get_filename;
	my $tag = $filename ? "in $filename" : $filename;
	warn "$message $tag\n";
}

sub set_filename {
	my ( $package, $filename ) = @_;

	$Pod::Tree::Node::filename = $filename;
}

sub get_filename {
	$Pod::Tree::Node::filename;
}

1

__END__


=head1 NAME

Pod::Tree::Node - nodes in a Pod::Tree

=head1 SYNOPSIS

  $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;
  
  is_code     $node and ...
  is_command  $node and ...
  is_for      $node and ...
  is_item     $node and ...
  is_letter   $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_link     $node and ...
  
  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 ...
  
  $arg       = get_arg       $node;
  $brackets  = get_brackets  $node;
  $children  = get_children  $node;
  $command   = get_command   $node;
  $domain    = get_domain    $node;
  $item_type = get_item_type $node;
  $letter    = get_letter    $node;
  $list_type = get_list_type $node;
  $page      = get_page      $node;
  $raw       = get_raw       $node;
  $raw_kids  = get_raw_kids  $node;
  $section   = get_section   $node;
  $siblings  = get_siblings  $node;
  $target    = get_target    $node;
  $text      = get_text      $node;
  $type      = get_type      $node;
  $deep_text = get_deep_text $node;
  
  $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;


=head1 REQUIRES

Pod::Escapes


=head1 DESCRIPTION

C<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

=over 4

=item *

creating nodes in the tree

=item *

parsing the POD into nodes

=item *

returning information about nodes

=item *

walking the tree

=back


=head1 TREE STRUCTURE


=head2 Root node

The tree descends from a single root node;
C<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.


=head2 Node types

For each node,
call C<get_type> to discover the type of the node

	for $child (@$children)
	{
	    $type = $child->get_type;
	}

I<$type> will be one of these strings:

=over 4

=item 'root'

The node is the root of the tree.

=item 'code'

The node represents a paragraph that is not part of the POD.

=item 'verbatim'

The node represents a verbatim paragraph.

=item 'ordinary'

The node represents an ordinary paragraph.

=item 'command'

The node represents an =command paragraph (but not an =over paragraph).

=item 'sequence'

The node represents an interior sequence.

=item 'target'

The node represents the target of a link (An LE<lt>E<gt> markup).

=item 'text'

The node represents text that contains no interior sequences.

=item 'list'

The node represents an =over list.

=item 'item'

The node represents an item in an =over list.

=item 'for'

The node represents a =for paragraph,
or it represents the paragraphs between =begin/=end commands.

=back

Here are instructions for walking these node types.


=head2 root node

Call

	$children = $node->get_children

to get a list of nodes representing the POD.


=head2 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 C<=cut> command. Call

	$text = $node->get_text

to recover the text of the paragraph.


=head2 verbatim nodes

A verbatim node contains the text of a verbatim paragraph.
Call

	$text = $node->get_text

to recover the text of the paragraph.


=head2 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.


=head2 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 I<without> the equals sign.

Z<>=over paragraphs are represented by list nodes,
not command nodes; see L<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.


=head2 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.

ZE<lt>E<gt> and EE<lt>E<gt> markups do not generate sequence nodes;
these markups are expanded by C<Pod::Tree> when the tree is built.


=head2 target nodes

If a sequence node represents a link (an C<< LZ<><> >> markup),
then

	is_link $node

returns true and

	$target = $node->get_target

returns a node representing the target of the link. 

C<Pod::Tree::Node> can represent targets in two I<domains>: C<POD> and C<HTTP>.
The C<POD> domain represents the

	L<page/section>

markups that are described in L<perlpod>. 
The C<HTTP> domain represents C<< LZ<><> >> markups that contain a URL, e.g.

	L<http://foo.bar.com/page.html#fragment>

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.

I<$target> is used only for constructing hyper-links;
the text to be displayed for the link is recovered by 
walking the children of I<$node>, as for any other interior sequence.


=head2 text nodes

A text node represents text that contains no interior sequences.
Call

	$text = $node->get_text

to recover the text.


=head2 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

=over 4

=item 'bullet'

=item 'number'

=item 'text'

=back

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.


=head2 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 L<list nodes>.
Typically, all the items in a list have the same type,
but C<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 I<siblings> of the item node.
Call

	$siblings = $node->get_siblings

to get a list of sibling nodes.


=head2 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.


=head2 Walking the tree

PODs have a recursive structure;
therefore, any application that walks a Pod::Tree must also be recursive.
See F<skeleton> for an example of the necessary code.


=head1 METHODS

=head2 Constructors

These methods construct C<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;

=over 4

=item I<$link> = C<Pod::Tree::Node>->C<link>(I<$node>, I<$page>, I<$section>)

Creates a new sequence node representing an C<< LZ<><> >> markup.
I<$node> becomes the sole child of the new node.
The target of the node is constructed from I<$page> and I<$section>.

This method isn't used to parse PODs.
It is provided for applications that want to create new links in an 
existing C<Pod::Tree> structure.

=back

=head2 Tests

These methods return true iff I<$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 ...

C<is_pod> returns true for all nodes except code, C<=pod>, 
and C<=cut> nodes. 


These methods return true iff I<$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 ...


=head2 Accessors

These methods return information about nodes.
Most accessors are only relevant for certain types of nodes.

=over 4


=item I<$arg> = C<get_arg> I<$node>

Returns the argument of I<$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.


=item I<$brackets> = C<get_brackets> I<$node>

Only relevant for for nodes.

If the node represents an =for command, 
I<@$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, 
I<@$brackets> is a two-element list containing
the text of the =begin and =end paragraphs.


=item I<$children> = C<get_children> I<$node>

Returns a reference to the list of nodes that are children of I<$node>.
May be called on any node.
The list may be empty.


=item I<$command> = C<get_command> I<$node>

Returns the name of a command, without the equals sign.
Only relevant for command nodes.


=item I<$domain> = C<get_domain> I<$node>

Only relevant for target nodes.
Returns the domain of the target.
This will be one of the strings

=over 4

=item 'HTTP'

=item 'POD'

=back


=item I<$item_type> = C<get_item_type> I<$node>

Returns the type of an item node. The type will be one of

=over 4

=item 'bullet'

=item 'number'

=item 'text'

=back


=item I<$letter> = C<get_letter> I<$node>

Returns the letter that introduces an interior sequence.
Only relevant for sequence nodes.


=item I<$list_type> = C<get_list_type> I<$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.


=item I<$page> = C<get_page> I<$node>

Only relevant for target nodes.
For targets in the C<POD> domain,
returns the man page that is the target of the link.
For targets in the C<HTTP> domain,
returns the URL that is the target of the link.


=item I<$raw> = C<get_raw> I<$node>

Returns the original text of a paragraph.
Currently provided for command, verbatim, and ordinary paragraphs.


=item I<$raw_kids> = C<get_raw_kids> I<$node>

Only provided for LZ<><> sequence nodes.
Returns a reference to a list of nodes representing the entire text 
of the LZ<><> sequence, including any part following a vertical bar (|).

The original text of the LZ<><> markup can be reconstructed from this list.


=item I<$section> = C<get_section> I<$node>

Only relevant for target nodes in the C<POD> domain.
Returns the section that is the target of a link.


=item I<$siblings> = C<get_siblings> I<$node>

Returns the siblings of a node.
May be called on any node.
Only item nodes have siblings.


=item I<$target> = C<get_target> I<$node>

Returns the target of a node.
Only relevant for sequence nodes that represent links 
(C<LE<lt>E<gt>> markups).
C<is_link> returns true on these nodes.


=item I<$text> = C<get_text> I<$node>

Returns the text of a node.
I<$text> will not contain any interior sequences.
Only relevant for text nodes.


=item I<$type> = C<get_type> I<$node>

Returns the type of I<$node>.
May be called on any node.
See L</TREE STRUCTURE> for descriptions of the node types.


=item I<$deep_text> = C<get_deep_text> I<$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.

C<get_deep_text> is provided as a convenience for applications that
want to ignore markups in a POD paragraph.

=back


=head2 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;


=head2 Utility

=over 4

=item I<$node>->C<clone>

Returns a deep copy of a node.
Only implemented for C<text> and C<sequence> nodes.


=item I<$node>->C<dump>

Returns a string containing a pretty-printed representation of the node.
Calling C<dump> on the root node of a tree will show the entire POD.


=item C<Pod::Tree::Node>->C<set_filename>(I<$filename>)

Sets the file name to be reported in error messages.


=item I<$filename> = $I<node>->C<getfile_name>

Returns the file name set by C<set_file_name>.


=back


=head1 EXAMPLES

The F<t/> directory in the C<Pod::Tree> distribution contains
examples of PODs, 
together with dumps of the trees that C<Pod::Tree> constructs for them.
The tree for C<t/>F<file>C<.pod> is in C<t/>F<file>C<.p_exp>.

C<Pod::Tree::Node::dump> is a simple example of code that walks a POD tree.

F<skeleton> is a skeleton application that walks a POD tree.


=head1 NOTES

=over 4

=item *

There is no provision in L<perlpod> for C<< LZ<><> >> markups to contain
URLs, but due to popular demand, this is now supported in
C<Pod::Tree::Node>.

=back


=head1 SEE ALSO

perl(1), L<C<Pod::Tree>>


=head1 AUTHOR

Steven McDougall, swmcd@world.std.com


=head1 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.