=head1 NAME

CommonMark - Interface to the CommonMark C library

=head1 SYNOPSIS

    use CommonMark;

    my $html = CommonMark->markdown_to_html($markdown);
    my $doc  = CommonMark->parse_file($file);
    my $doc  = CommonMark->parse_document($markdown);
    my $doc  = CommonMark->create_document;

=head1 DESCRIPTION

This module is a wrapper around the official CommonMark C library
I<libcmark>. It closely follows the original API.

The main module provides some entry points to parse documents. The bulk of
features is available through L<CommonMark::Node> objects of which the
parse tree is made. L<CommonMark::Iterator> is a useful class to walk
through the nodes in a tree. L<CommonMark::Parser> provides a push parser
interface.

=head2 markdown_to_html

    my $html = CommonMark->markdown_to_html($markdown);

Converts a Markdown string to HTML. This methods returns 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>.

Equivalent to

    my $html = CommonMark->parse_document($markdown)->render_html;

=head2 parse

    my $doc = CommonMark->parse(
        string => $string,
        smart  => $smart,   # Optional
    );

    my $doc = CommonMark->parse(
        file  => $file,
        smart => $smart,    # Optional
    );

Convenience function to parse documents. Exactly one of the C<string> or
C<file> options must be provided. When given a string, calls
C<parse_document>. When given a file, calls C<parse_file>. If C<smart>
if provided and true, enables the C<OPT_SMART> parser option.

=head2 parse_document

    my $doc = CommonMark->parse_document( $markdown, [$options] )

Parses a CommonMark document from a string returning the L<CommonMark::Node>
of the document root. C<$options> is a bit field containing the parser
options. It defaults to C<OPT_DEFAULT>.

=head2 parse_file

    my $doc = CommonMark->parse_file( $file, [$options] );

Parses a CommonMark document from a file handle returning the
L<CommonMark::Node> of the document root. C<$options> is a bit field
containing the parser. It defaults to C<OPT_DEFAULT>.

=head2 Parser options

The parser options are a bit field created by ORing the following constants:

    CommonMark::OPT_DEFAULT => 0
    CommonMark::OPT_SMART   => 8

C<OPT_SMART> enables the "smart quote" features which turns vertical into
typographic quotation marks, double hyphens into en dashes, and triple
hyphens into em dashes.

=head2 Node creation

    my $document = CommonMark->create_document(
        children => \@children,
    );
    my $header = CommonMark->create_header(
        level    => $level,
        children => \@children,
        text     => $literal,
    );
    my $paragraph = CommonMark->create_paragraph(
        children => \@children,
        text     => $literal,
    );
    my $block_quote = CommonMark->create_block_quote(
        children => \@children,
    );
    my $list = CommonMark->create_list(
        type     => $type,
        delim    => $delim,
        start    => $start,
        tight    => $tight,
        children => \@children,
    );
    my $item = CommonMark->create_item(
        children => \@children,
    );
    my $code_block = CommonMark->create_code_block(
        fence_info => $fence_info,
        literal    => $literal,
    );
    my $html = CommonMark->create_html(
        literal => $html,
    );
    my $hrule = CommonMark->create_hrule;
    my $emph = CommonMark->create_emph(
        children => \@children,
        text     => $literal,
    );
    my $strong = CommonMark->create_strong(
        children => \@children,
        text     => $literal,
    );
    my $url = CommonMark->create_url(
        url      => $url,
        title    => $title,
        children => \@children,
        text     => $literal,
    );
    my $image = CommonMark->create_image(
        url      => $url,
        title    => $title,
        children => \@children,
        text     => $literal,
    );
    my $softbreak = CommonMark->create_softbreak;
    my $linebreak = CommonMark->create_linebreak;

These convenience functions can be used to create nodes, set properties,
and add children in a single operation. All parameters are optional.

The C<children> parameter expects an arrayref of nodes to be added as
children. The special C<text> parameter adds a single text child with
literal C<$literal>. It can't be used together with C<children>. All other
parameters correspond to a node property.

=head2 libcmark version information

    my $version = CommonMark->version;
    my $string  = CommonMark->version_string;
    my $version = CommonMark->compile_time_version;
    my $string  = CommonMark->compile_time_version_string;

Return the version number or version string of libcmark, either the
library version linked against at run time or compile time.

=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

