CommonMark - Interface to the CommonMark C library
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;
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 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.
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;
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.
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").
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").
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.
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.
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.
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.