.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "CommonMark 3pm"
.TH CommonMark 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
CommonMark \- Interface to the CommonMark C library
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&    use CommonMark;
\&
\&    my $doc = CommonMark\->parse(
\&        file  => $file,
\&        smart => 1,
\&    );
\&
\&    my $html = CommonMark\->markdown_to_html($markdown);
\&    my $doc  = CommonMark\->parse_file($file);
\&    my $doc  = CommonMark\->parse_document($markdown);
\&    my $doc  = CommonMark\->create_document;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module is a wrapper around the official CommonMark C library
\&\fIlibcmark\fR. It closely follows the original API.
.PP
The main module provides some entry points to parse documents and convenience
functions for node creation. The bulk of features is available through
CommonMark::Node objects of which the parse tree is made.
CommonMark::Iterator is a useful class to walk through the nodes in a
tree. CommonMark::Parser provides a push parser interface.
.SS Installation
.IX Subsection "Installation"
\fIInstallation of libcmark\fR
.IX Subsection "Installation of libcmark"
.PP
Please note that the \fIlibcmark\fR API isn't stable yet. This version of the
Perl bindings is known to work with all releases between 0.21.0 and 0.29.0,
but there's no guarantee that it can be compiled with later versions. Also
note that upgrading a dynamically linked version of libcmark may require
recompilation of the Perl distribution.
.PP
It is recommended to use the \fIlibcmark\fR packages provided by recent Linux
distros. On Debian or Ubuntu, run:
.PP
.Vb 1
\&    sudo apt\-get install libcmark\-dev
.Ve
.PP
On Red Hat or CentOS, run:
.PP
.Vb 1
\&    sudo yum install cmark\-devel
.Ve
.PP
To install \fIlibcmark\fR from source:
.PP
.Vb 6
\&    curl \-LJO https://github.com/commonmark/cmark/archive/0.29.0.tar.gz
\&    tar xzf cmark\-0.29.0.tar.gz
\&    cd cmark\-0.29.0
\&    make [INSTALL_PREFIX=/prefix]
\&    make test
\&    make install
.Ve
.PP
See the \fIlibcmark\fR README for details.
.PP
\fIInstallation from a CPAN tarball\fR
.IX Subsection "Installation from a CPAN tarball"
.PP
If \fIlibcmark\fR is in a standard location:
.PP
.Vb 4
\&    perl Makefile.PL
\&    make
\&    make test
\&    make install
.Ve
.PP
Otherwise:
.PP
.Vb 6
\&    perl Makefile.PL \e
\&        INC="\-I/prefix/include" \e
\&        LIBS="\-L/prefix/lib \-lcmark"
\&    make
\&    make test
\&    make install
.Ve
.PP
See the documentation of \fIExtUtils::MakeMaker\fR for additional options.
The \fIPERL_MM_OPT\fR environment variable is especially useful.
.PP
.Vb 1
\&    export PERL_MM_OPT=\*(AqINC="\-I..." LIBS="\-L... \-lcmark"\*(Aq
.Ve
.PP
\fIBuild from a repository checkout\fR
.IX Subsection "Build from a repository checkout"
.PP
This distribution uses \fIDist::Zilla\fR with the external plugins
\&\fIMakeMaker::Awesome\fR and \fICopyFilesFromBuild\fR. You can build and test with
\&\fIdzil\fR:
.PP
.Vb 2
\&    dzil test
\&    dzil build
.Ve
.PP
The files generated by \fIDist::Zilla\fR are included in the repository,
so you can use the standard build process as well.
.SS markdown_to_html
.IX Subsection "markdown_to_html"
.Vb 1
\&    my $html = CommonMark\->markdown_to_html( $markdown, [$options] );
.Ve
.PP
Converts a Markdown string to HTML. \f(CW$options\fR is a bit field
containing the parser and render options. It defaults to zero
(\f(CW\*(C`OPT_DEFAULT\*(C'\fR).
.PP
Equivalent to
.PP
.Vb 1
\&    my $html = CommonMark\->parse_document($markdown)\->render_html;
.Ve
.SS parse
.IX Subsection "parse"
.Vb 6
\&    my $doc = CommonMark\->parse(
\&        string        => $string,
\&        normalize     => $bool,    # Optional
\&        smart         => $bool,    # Optional
\&        validate_utf8 => $bool,    # Optional
\&    );
\&
\&    my $doc = CommonMark\->parse(
\&        file          => $handle,
\&        normalize     => $bool,    # Optional
\&        smart         => $bool,    # Optional
\&        validate_utf8 => $bool,    # Optional
\&    );
.Ve
.PP
Convenience function to parse documents. Exactly one of the \f(CW\*(C`string\*(C'\fR or
\&\f(CW\*(C`file\*(C'\fR options must be provided. When given a string, calls
"parse_document". When given a file, calls "parse_file". \f(CW\*(C`normalize\*(C'\fR,
\&\f(CW\*(C`smart\*(C'\fR, and \f(CW\*(C`validate_utf8\*(C'\fR enable the respective
parser options.
.PP
Returns the CommonMark::Node of the root document.
.SS parse_document
.IX Subsection "parse_document"
.Vb 1
\&    my $doc = CommonMark\->parse_document( $markdown, [$options] )
.Ve
.PP
Parses a CommonMark document from a string returning the CommonMark::Node
of the document root. \f(CW$options\fR is a bit field containing the parser
options. It defaults to zero (\f(CW\*(C`OPT_DEFAULT\*(C'\fR).
.SS parse_file
.IX Subsection "parse_file"
.Vb 1
\&    my $doc = CommonMark\->parse_file( $file, [$options] );
.Ve
.PP
Parses a CommonMark document from a file handle returning the
CommonMark::Node of the document root. \f(CW$options\fR is a bit field
containing the parser options. It defaults to zero (\f(CW\*(C`OPT_DEFAULT\*(C'\fR).
.SS "Parser options"
.IX Subsection "Parser options"
The parser options are a bit field created by ORing the following constants:
.PP
.Vb 4
\&    CommonMark::OPT_DEFAULT => 0
\&    CommonMark::OPT_NORMALIZE
\&    CommonMark::OPT_VALIDATE_UTF8
\&    CommonMark::OPT_SMART
.Ve
.PP
Parser options can be imported from CommonMark with tag \f(CW\*(C`opt\*(C'\fR.
.PP
.Vb 1
\&    use CommonMark qw(:opt);
.Ve
.PP
\&\f(CW\*(C`OPT_NORMALIZE\*(C'\fR makes sure that adjacent text nodes are merged in the parse
tree. This option has no effect with libcmark 0.28 or higher which always
normalizes text nodes.
.PP
\&\f(CW\*(C`OPT_SMART\*(C'\fR enables the "smart quote" feature which turns vertical into
typographic quotation marks, double and triple hyphens into en and em dashes,
and triple periods into ellipses.
.PP
\&\f(CW\*(C`OPT_VALIDATE_UTF8\*(C'\fR turns on UTF\-8 validation. Normally, this shouldn't be
necessary because Perl strings should always contain valid UTF\-8. But it is
possible to create strings flagged as UTF\-8 that contain invalid UTF\-8, for
example with XS. The option may be used if you don't trust the input data
and want to make absolutely sure that the output is valid UTF\-8. If invalid
bytes are found, they are replaced with the Unicode replacement character
U+FFFD.
.SS "Node creation"
.IX Subsection "Node creation"
.Vb 10
\&    my $document = CommonMark\->create_document(
\&        children => \e@children,
\&    );
\&    my $header = CommonMark\->create_heading(
\&        level    => $level,
\&        children => \e@children,
\&        text     => $literal,
\&    );
\&    my $paragraph = CommonMark\->create_paragraph(
\&        children => \e@children,
\&        text     => $literal,
\&    );
\&    my $block_quote = CommonMark\->create_block_quote(
\&        children => \e@children,
\&    );
\&    my $list = CommonMark\->create_list(
\&        type     => $type,
\&        delim    => $delim,
\&        start    => $start,
\&        tight    => $tight,
\&        children => \e@children,
\&    );
\&    my $item = CommonMark\->create_item(
\&        children => \e@children,
\&    );
\&    my $code_block = CommonMark\->create_code_block(
\&        fence_info => $fence_info,
\&        literal    => $literal,
\&    );
\&    my $html = CommonMark\->create_html_block(
\&        literal => $html,
\&    );
\&    my $custom_block = CommonMark\->create_custom_block(
\&        on_enter => $raw_prefix,
\&        on_exit  => $raw_suffix,
\&        children => \e@children,
\&        text     => $literal,
\&    );
\&    my $thematic_break = CommonMark\->create_thematic_break;
\&    my $text = CommonMark\->create_text(
\&        literal => $literal,
\&    );
\&    my $code = CommonMark\->create_code(
\&        literal => $literal,
\&    );
\&    my $html_inline = CommonMark\->create_html_inline(
\&        literal => $literal,
\&    );
\&    my $emph = CommonMark\->create_emph(
\&        children => \e@children,
\&        text     => $literal,
\&    );
\&    my $strong = CommonMark\->create_strong(
\&        children => \e@children,
\&        text     => $literal,
\&    );
\&    my $url = CommonMark\->create_url(
\&        url      => $url,
\&        title    => $title,
\&        children => \e@children,
\&        text     => $literal,
\&    );
\&    my $image = CommonMark\->create_image(
\&        url      => $url,
\&        title    => $title,
\&        children => \e@children,
\&        text     => $literal,
\&    );
\&    my $custom_inline = CommonMark\->create_custom_inline(
\&        on_enter => $raw_prefix,
\&        on_exit  => $raw_suffix,
\&        children => \e@children,
\&        text     => $literal,
\&    );
\&    my $softbreak = CommonMark\->create_softbreak;
\&    my $linebreak = CommonMark\->create_linebreak;
.Ve
.PP
These convenience functions can be used to create nodes, set properties,
and add children in a single operation. All parameters are optional.
.PP
The \f(CW\*(C`children\*(C'\fR parameter expects an arrayref of nodes to be added as
children. The special \f(CW\*(C`text\*(C'\fR parameter adds a single text child with
literal \f(CW$literal\fR. It can't be used together with \f(CW\*(C`children\*(C'\fR. All other
parameters correspond to a node property.
.SS "libcmark version information"
.IX Subsection "libcmark version information"
.Vb 4
\&    my $version = CommonMark\->version;
\&    my $string  = CommonMark\->version_string;
\&    my $version = CommonMark\->compile_time_version;
\&    my $string  = CommonMark\->compile_time_version_string;
.Ve
.PP
Return the version number or version string of libcmark, either the
library version linked against at run time or compile time.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
This software is copyright (C) by Nick Wellnhofer.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.