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.

FUNCTIONS

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_document

my $doc = CommonMark->parse_document($markdown)

Parses a CommonMark document from a string returning the CommonMark::Node of the document root.

parse_file

my $doc = CommonMark->parse_file($file);

Parses a CommonMark document from a file handle returning the CommonMark::Node of the document root.

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.

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.