NAME

Perldoc::DOM::Node - node in a Perldoc::DOM tree

SYNOPSIS

 # construct a Perldoc::DOM fragment from this:
 #
 #  =head1 NAME
 #
 #  foo
 #
 #  =cut
 #
 # corresponding normative XML tree;
 #
 #  <sect1><title>NAME</title><para>foo</para></sect1>

 # Perldoc::DOM::Node representation;
 my $node = Perldoc::DOM::Element->new
     ({ name => "sect1",
        source => "=head1 ",  # text "eaten" by this node
     });


 # no "source", as this is an "implied" tag
 my $title = Perldoc::DOM::Element->new ({ name => "title" });
 $node->add_daughter($title);

 # text nodes are different, like W3C DOM - don't moan
 # kiddies, this is for your own good :)
 my $text = Perldoc::DOM::Text->new ("NAME");

 # note that Texts *can* have an alternate source fragment, but it
 # defaults to be the same as the content, modulo whatever we end up
 # doing with whitespace for the round-tripping

 $title->add_daughter($text);

 # etc etc
 my $para = Perldoc::DOM::Element->new({ name => "para",
                                      source => "\n\n" });
 $node->add_daughter($para);
 # alternate way of creating Texts with content
 $para->add_daughter(Perldoc::DOM::Text->new
                         ({ content => "foo" }));

 # dummy nodes used only for reconstruction to source.
 # represented as processing instructions, or maybe comments
 # in the "normative XML"
 $node->add_daughter
    (Perldoc::DOM::PI->new({ source => "\n\n=cut"}));

DESCRIPTION

Well, with that informative but utterly confusing synopsis, you should be left with nothing but questions about what this object represents.

It represents a node in the Perldoc DOM tree (see Perldoc::DOM for more). The DOM tree has a root node, which is a "body" element of sorts.

Different types of nodes in a Perldoc DOM tree have different properties, you should see the subclasses for more.

In short, those subclasses are;

Perldoc::DOM::Element

It's all about meta-data and structure, not content!

Perldoc::DOM::Text

The Text nodes are where it's at, baby, yeah!

Perldoc::DOM::PI

Placeholder for dummy nodes that contain only source representation.

API METHODS

These methods must be implemented by subclasses... though a default implementation exists, too.

source

source($new_source)

Returns the representation of this node in the original text, or at least a valid representation of it that "honours the spirit of the dialect", if the original form is not available or has been discarded.

SEE ALSO

Tree::DAG_Node - details on how to navigate the DAG.