
class Perldoc::DOM::Node is Tree;

has $.source;
has $.sourcefile;
has $.sourceline;

# fixme - this is an abstract class, but I'm not sure how to
# specify/enforce that.

method dom_fields($self:) {
    <source sourcefile sourceline>;
}

method dom_attr($self:) returns Hash {
    { $self.dom_fields.map:{
	my $val = eval '$self.'~$_;
	say "warning: error $!" if $!;
	($val.defined ?? ($_ => $self.($_)) :: ())
    } };
}

=head1 NAME

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

=head1 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"}));

=head1 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 L<Perldoc::DOM> for more).
The DOM tree has a root node, which is a "C<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;

=over

=item L<Perldoc::DOM::Element>

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

=item L<Perldoc::DOM::Text>

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

=item L<Perldoc::DOM::PI>

Placeholder for dummy nodes that contain only source representation.

=back

=head1 API METHODS

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

=over

=item B<source>

=item B<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.

=head1 SEE ALSO

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

=cut

