1CommonMark(3)         User Contributed Perl Documentation        CommonMark(3)
2
3
4

NAME

6       CommonMark - Interface to the CommonMark C library
7

SYNOPSIS

9           use CommonMark;
10
11           my $doc = CommonMark->parse(
12               file  => $file,
13               smart => 1,
14           );
15
16           my $html = CommonMark->markdown_to_html($markdown);
17           my $doc  = CommonMark->parse_file($file);
18           my $doc  = CommonMark->parse_document($markdown);
19           my $doc  = CommonMark->create_document;
20

DESCRIPTION

22       This module is a wrapper around the official CommonMark C library
23       libcmark. It closely follows the original API.
24
25       The main module provides some entry points to parse documents and
26       convenience functions for node creation. The bulk of features is
27       available through CommonMark::Node objects of which the parse tree is
28       made.  CommonMark::Iterator is a useful class to walk through the nodes
29       in a tree. CommonMark::Parser provides a push parser interface.
30
31   Installation
32       Installation of libcmark
33
34       Please note that the libcmark API isn't stable yet. This version of the
35       Perl bindings is known to work with all releases between 0.21.0 and
36       0.29.0, but there's no guarantee that it can be compiled with later
37       versions. Also note that upgrading a dynamically linked version of
38       libcmark may require recompilation of the Perl distribution.
39
40       It is recommended to use the libcmark packages provided by recent Linux
41       distros. On Debian or Ubuntu, run:
42
43           sudo apt-get install libcmark-dev
44
45       On Red Hat or CentOS, run:
46
47           sudo yum install cmark-devel
48
49       To install libcmark from source:
50
51           curl -LJO https://github.com/commonmark/cmark/archive/0.29.0.tar.gz
52           tar xzf cmark-0.29.0.tar.gz
53           cd cmark-0.29.0
54           make [INSTALL_PREFIX=/prefix]
55           make test
56           make install
57
58       See the libcmark README for details.
59
60       Installation from a CPAN tarball
61
62       If libcmark is in a standard location:
63
64           perl Makefile.PL
65           make
66           make test
67           make install
68
69       Otherwise:
70
71           perl Makefile.PL \
72               INC="-I/prefix/include" \
73               LIBS="-L/prefix/lib -lcmark"
74           make
75           make test
76           make install
77
78       See the documentation of ExtUtils::MakeMaker for additional options.
79       The PERL_MM_OPT environment variable is especially useful.
80
81           export PERL_MM_OPT='INC="-I..." LIBS="-L... -lcmark"'
82
83       Build from a repository checkout
84
85       This distribution uses Dist::Zilla with the external plugins
86       MakeMaker::Awesome and CopyFilesFromBuild. You can build and test with
87       dzil:
88
89           dzil test
90           dzil build
91
92       The files generated by Dist::Zilla are included in the repository, so
93       you can use the standard build process as well.
94
95   markdown_to_html
96           my $html = CommonMark->markdown_to_html( $markdown, [$options] );
97
98       Converts a Markdown string to HTML. $options is a bit field containing
99       the parser and render options. It defaults to zero ("OPT_DEFAULT").
100
101       Equivalent to
102
103           my $html = CommonMark->parse_document($markdown)->render_html;
104
105   parse
106           my $doc = CommonMark->parse(
107               string        => $string,
108               normalize     => $bool,    # Optional
109               smart         => $bool,    # Optional
110               validate_utf8 => $bool,    # Optional
111           );
112
113           my $doc = CommonMark->parse(
114               file          => $handle,
115               normalize     => $bool,    # Optional
116               smart         => $bool,    # Optional
117               validate_utf8 => $bool,    # Optional
118           );
119
120       Convenience function to parse documents. Exactly one of the "string" or
121       "file" options must be provided. When given a string, calls
122       "parse_document". When given a file, calls "parse_file". "normalize",
123       "smart", and "validate_utf8" enable the respective parser options.
124
125       Returns the CommonMark::Node of the root document.
126
127   parse_document
128           my $doc = CommonMark->parse_document( $markdown, [$options] )
129
130       Parses a CommonMark document from a string returning the
131       CommonMark::Node of the document root. $options is a bit field
132       containing the parser options. It defaults to zero ("OPT_DEFAULT").
133
134   parse_file
135           my $doc = CommonMark->parse_file( $file, [$options] );
136
137       Parses a CommonMark document from a file handle returning the
138       CommonMark::Node of the document root. $options is a bit field
139       containing the parser options. It defaults to zero ("OPT_DEFAULT").
140
141   Parser options
142       The parser options are a bit field created by ORing the following
143       constants:
144
145           CommonMark::OPT_DEFAULT => 0
146           CommonMark::OPT_NORMALIZE
147           CommonMark::OPT_VALIDATE_UTF8
148           CommonMark::OPT_SMART
149
150       Parser options can be imported from CommonMark with tag "opt".
151
152           use CommonMark qw(:opt);
153
154       "OPT_NORMALIZE" makes sure that adjacent text nodes are merged in the
155       parse tree. This option has no effect with libcmark 0.28 or higher
156       which always normalizes text nodes.
157
158       "OPT_SMART" enables the "smart quote" feature which turns vertical into
159       typographic quotation marks, double and triple hyphens into en and em
160       dashes, and triple periods into ellipses.
161
162       "OPT_VALIDATE_UTF8" turns on UTF-8 validation. Normally, this shouldn't
163       be necessary because Perl strings should always contain valid UTF-8.
164       But it is possible to create strings flagged as UTF-8 that contain
165       invalid UTF-8, for example with XS. The option may be used if you don't
166       trust the input data and want to make absolutely sure that the output
167       is valid UTF-8. If invalid bytes are found, they are replaced with the
168       Unicode replacement character U+FFFD.
169
170   Node creation
171           my $document = CommonMark->create_document(
172               children => \@children,
173           );
174           my $header = CommonMark->create_heading(
175               level    => $level,
176               children => \@children,
177               text     => $literal,
178           );
179           my $paragraph = CommonMark->create_paragraph(
180               children => \@children,
181               text     => $literal,
182           );
183           my $block_quote = CommonMark->create_block_quote(
184               children => \@children,
185           );
186           my $list = CommonMark->create_list(
187               type     => $type,
188               delim    => $delim,
189               start    => $start,
190               tight    => $tight,
191               children => \@children,
192           );
193           my $item = CommonMark->create_item(
194               children => \@children,
195           );
196           my $code_block = CommonMark->create_code_block(
197               fence_info => $fence_info,
198               literal    => $literal,
199           );
200           my $html = CommonMark->create_html_block(
201               literal => $html,
202           );
203           my $custom_block = CommonMark->create_custom_block(
204               on_enter => $raw_prefix,
205               on_exit  => $raw_suffix,
206               children => \@children,
207               text     => $literal,
208           );
209           my $thematic_break = CommonMark->create_thematic_break;
210           my $text = CommonMark->create_text(
211               literal => $literal,
212           );
213           my $code = CommonMark->create_code(
214               literal => $literal,
215           );
216           my $html_inline = CommonMark->create_html_inline(
217               literal => $literal,
218           );
219           my $emph = CommonMark->create_emph(
220               children => \@children,
221               text     => $literal,
222           );
223           my $strong = CommonMark->create_strong(
224               children => \@children,
225               text     => $literal,
226           );
227           my $url = CommonMark->create_url(
228               url      => $url,
229               title    => $title,
230               children => \@children,
231               text     => $literal,
232           );
233           my $image = CommonMark->create_image(
234               url      => $url,
235               title    => $title,
236               children => \@children,
237               text     => $literal,
238           );
239           my $custom_inline = CommonMark->create_custom_inline(
240               on_enter => $raw_prefix,
241               on_exit  => $raw_suffix,
242               children => \@children,
243               text     => $literal,
244           );
245           my $softbreak = CommonMark->create_softbreak;
246           my $linebreak = CommonMark->create_linebreak;
247
248       These convenience functions can be used to create nodes, set
249       properties, and add children in a single operation. All parameters are
250       optional.
251
252       The "children" parameter expects an arrayref of nodes to be added as
253       children. The special "text" parameter adds a single text child with
254       literal $literal. It can't be used together with "children". All other
255       parameters correspond to a node property.
256
257   libcmark version information
258           my $version = CommonMark->version;
259           my $string  = CommonMark->version_string;
260           my $version = CommonMark->compile_time_version;
261           my $string  = CommonMark->compile_time_version_string;
262
263       Return the version number or version string of libcmark, either the
264       library version linked against at run time or compile time.
265
267       This software is copyright (C) by Nick Wellnhofer.
268
269       This is free software; you can redistribute it and/or modify it under
270       the same terms as the Perl 5 programming language system itself.
271
272
273
274perl v5.32.0                      2020-07-28                     CommonMark(3)
Impressum