Provided by: libcommonmark-perl_0.290000-2build2_amd64 
NAME
CommonMark - Interface to the CommonMark C library
SYNOPSIS
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;
DESCRIPTION
This module is a wrapper around the official CommonMark C library libcmark. It closely
follows the original API.
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.
Installation
Installation of libcmark
Please note that the libcmark 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.
It is recommended to use the libcmark packages provided by recent Linux distros. On Debian
or Ubuntu, run:
sudo apt-get install libcmark-dev
On Red Hat or CentOS, run:
sudo yum install cmark-devel
To install libcmark from source:
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
See the libcmark README for details.
Installation from a CPAN tarball
If libcmark is in a standard location:
perl Makefile.PL
make
make test
make install
Otherwise:
perl Makefile.PL \
INC="-I/prefix/include" \
LIBS="-L/prefix/lib -lcmark"
make
make test
make install
See the documentation of ExtUtils::MakeMaker for additional options. The PERL_MM_OPT
environment variable is especially useful.
export PERL_MM_OPT='INC="-I..." LIBS="-L... -lcmark"'
Build from a repository checkout
This distribution uses Dist::Zilla with the external plugins MakeMaker::Awesome and
CopyFilesFromBuild. You can build and test with dzil:
dzil test
dzil build
The files generated by Dist::Zilla are included in the repository, so you can use the
standard build process as well.
markdown_to_html
my $html = CommonMark->markdown_to_html( $markdown, [$options] );
Converts a Markdown string to HTML. $options is a bit field containing the parser and
render options. It defaults to zero ("OPT_DEFAULT").
Equivalent to
my $html = CommonMark->parse_document($markdown)->render_html;
parse
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
);
Convenience function to parse documents. Exactly one of the "string" or "file" options
must be provided. When given a string, calls "parse_document". When given a file, calls
"parse_file". "normalize", "smart", and "validate_utf8" enable the respective parser
options.
Returns the CommonMark::Node of the root document.
parse_document
my $doc = CommonMark->parse_document( $markdown, [$options] )
Parses a CommonMark document from a string returning the CommonMark::Node of the document
root. $options is a bit field containing the parser options. It defaults to zero
("OPT_DEFAULT").
parse_file
my $doc = CommonMark->parse_file( $file, [$options] );
Parses a CommonMark document from a file handle returning the CommonMark::Node of the
document root. $options is a bit field containing the parser options. It defaults to zero
("OPT_DEFAULT").
Parser options
The parser options are a bit field created by ORing the following constants:
CommonMark::OPT_DEFAULT => 0
CommonMark::OPT_NORMALIZE
CommonMark::OPT_VALIDATE_UTF8
CommonMark::OPT_SMART
Parser options can be imported from CommonMark with tag "opt".
use CommonMark qw(:opt);
"OPT_NORMALIZE" 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.
"OPT_SMART" 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.
"OPT_VALIDATE_UTF8" 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.
Node creation
my $document = CommonMark->create_document(
children => \@children,
);
my $header = CommonMark->create_heading(
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_block(
literal => $html,
);
my $custom_block = CommonMark->create_custom_block(
on_enter => $raw_prefix,
on_exit => $raw_suffix,
children => \@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 => \@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 $custom_inline = CommonMark->create_custom_inline(
on_enter => $raw_prefix,
on_exit => $raw_suffix,
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 "children" parameter expects an arrayref of nodes to be added as children. The special
"text" parameter adds a single text child with literal $literal. It can't be used together
with "children". All other parameters correspond to a node property.
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.
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.