/ 
CommonMark-0.1802
River stage one • 5 direct dependents • 6 total dependents
/ CommonMark

NAME

CommonMark - Interface to the CommonMark C library

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;

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. 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.

markdown_to_html

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

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

Equivalent to

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

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 string or file options must be provided. When given a string, calls parse_document. When given a file, calls parse_file. If smart if provided and true, enables the OPT_SMART parser option.

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 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 OPT_DEFAULT.

Parser options

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

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

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.

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 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.