=head1 NAME

CommonMark::Node - Node of the CommonMark parse tree

=head1 SYNOPSIS

    my $header    = $doc->first_child;
    my $level     = $header->get_header_level;
    my $paragraph = $header->next;

    my $link = CommonMark::Node->new(CommonMark::NODE_LINK);
    $link->set_url('http://example.com/');
    my $text = CommonMark::Node->new(CommonMark::NODE_TEXT);
    $text->set_literal('link text');
    $link->append_child($link_text);
    $paragraph->append_child($link);

    $doc->render_html;


=head1 DESCRIPTION

C<CommonMark::Node> represents a node of the parse tree.

=head2 new

   my $node = CommonMark::Node->new($type);

Creates a new node of type C<$type>. See L</"Node types"> for a list of
types.

=head2 iterator

    my $iterator = $node->iterator;

Creates a new L<CommonMark::Iterator> to walk through the descendants of
the node.

=head2 Rendering

    my $html = $node->render_html( [$options] )
    my $xml  = $node->render_xml( [$options] )
    my $man  = $node->render_man( [$options] )

These methods render the contents of the node in the respective format and
return an B<encoded> UTF-8 byte string. This is useful when passing the
results to external parties. If you want to process the string contents,
you should consider decoding the byte string using C<utf8::decode>.

C<$options> is a bit field created by ORing the following constants:

    CommonMark::OPT_DEFAULT    => 0
    CommonMark::OPT_SOURCEPOS  => 1
    CommonMark::OPT_HARDBREAKS => 2
    CommonMark::OPT_NORMALIZE  => 4

C<$options> may be omitted and defaults to C<OPT_DEFAULT>. See the
documentation of I<libcmark> for more details.

=head2 Accessors

    # Integer values

    my $int = $node->get_type;
    my $int = $node->get_header_level;
    my $int = $node->get_list_type;
    my $int = $node->get_list_delim;
    my $int = $node->get_list_start;
    my $int = $node->get_list_tight;
    my $int = $node->get_start_line;
    my $int = $node->get_start_column;
    my $int = $node->get_end_line;
    my $int = $node->get_end_column;

    $node->set_header_level($int);
    $node->set_list_type($int);
    $node->set_list_delim($int);
    $node->set_list_start($int);
    $node->set_list_tight($int);

    # String values

    my $string = $node->get_type_string;
    my $string = $node->get_literal;
    my $string = $node->get_title;
    my $string = $node->get_url;
    my $string = $node->get_fence_info;

    $node->set_literal($string);
    $node->set_title($string);
    $node->set_url($string);
    $node->set_fence_info($string);

Various accessors to get and set integer and string values of a node. Not
all values are supported by every type of node. Getters return C<0> or
C<undef> for unsupported values. Setters die on faliure.

See L</"Constants"> for a list of constants used for node types, list
types, and list delimiters.

=head2 Tree traversal

    my $next   = $node->next;
    my $prev   = $node->previous;
    my $parent = $node->parent;
    my $child  = $node->first_child;
    my $child  = $node->last_child;

These methods return the respective node in tree structure.

=head2 Tree manipulation

    $node->unlink;
    $node->insert_before($other);
    $node->insert_after($other);
    $node->prepend_child($other);
    $node->append_child($other);

C<unlink> removes a node and all its descendants from the tree.

C<insert_before> and C<insert_after> insert the C<$other> node before or
after C<$node>. C<append_child> and C<prepend_child> append or prepend
C<$other> to the children of C<$node>.

C<$other> is unlinked before it is inserted into its new position.

These methods may die on failure.

=head2 Constants

=head3 Node types

    CommonMark::NODE_NONE        =>  0
    CommonMark::NODE_DOCUMENT    =>  1
    CommonMark::NODE_BLOCK_QUOTE =>  2
    CommonMark::NODE_LIST        =>  3
    CommonMark::NODE_ITEM        =>  4
    CommonMark::NODE_CODE_BLOCK  =>  5
    CommonMark::NODE_HTML        =>  6
    CommonMark::NODE_PARAGRAPH   =>  7
    CommonMark::NODE_HEADER      =>  8
    CommonMark::NODE_HRULE       =>  9
    CommonMark::NODE_TEXT        => 10
    CommonMark::NODE_SOFTBREAK   => 11
    CommonMark::NODE_LINEBREAK   => 12
    CommonMark::NODE_CODE        => 13
    CommonMark::NODE_INLINE_HTML => 14
    CommonMark::NODE_EMPH        => 15
    CommonMark::NODE_STRONG      => 16
    CommonMark::NODE_LINK        => 17
    CommonMark::NODE_IMAGE       => 18

=head3 List types

    CommonMark::NO_LIST      => 0
    CommonMark::BULLET_LIST  => 1
    CommonMark::ORDERED_LIST => 2

=head3 Delimiter types for ordered lists

    CommonMark::NO_DELIM     => 0
    CommonMark::PERIOD_DELIM => 1
    CommonMark::PAREN_DELIM  => 2

=head1 COPYRIGHT

This software is copyright (C) by Nick Wellnhofer.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut

