1CommonMark(3) User Contributed Perl Documentation CommonMark(3)
2
6 CommonMark - Interface to the CommonMark C library
7
9 use CommonMark;
10 my $doc = CommonMark->parse(
12 file => $file,
13 smart => 1,
14 );
15 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
22 This module is a wrapper around the official CommonMark C library
23 libcmark. It closely follows the original API.
24 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 Installation
32 Installation of libcmark
33 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 It is recommended to use the libcmark packages provided by recent Linux
41 distros. On Debian or Ubuntu, run:
42 sudo apt-get install libcmark-dev
44 On Red Hat or CentOS, run:
46 sudo yum install cmark-devel
48 To install libcmark from source:
50 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 See the libcmark README for details.
59 Installation from a CPAN tarball
61 If libcmark is in a standard location:
63 perl Makefile.PL
65 make
66 make test
67 make install
68 Otherwise:
70 perl Makefile.PL \
72 INC="-I/prefix/include" \
73 LIBS="-L/prefix/lib -lcmark"
74 make
75 make test
76 make install
77 See the documentation of ExtUtils::MakeMaker for additional options.
79 The PERL_MM_OPT environment variable is especially useful.
80 export PERL_MM_OPT='INC="-I..." LIBS="-L... -lcmark"'
82 Build from a repository checkout
84 This distribution uses Dist::Zilla with the external plugins
86 MakeMaker::Awesome and CopyFilesFromBuild. You can build and test with
87 dzil:
88 dzil test
90 dzil build
91 The files generated by Dist::Zilla are included in the repository, so
93 you can use the standard build process as well.
94 markdown_to_html
96 my $html = CommonMark->markdown_to_html( $markdown, [$options] );
97 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 Equivalent to
102 my $html = CommonMark->parse_document($markdown)->render_html;
104 parse
106 my $doc = CommonMark->parse(
107 string => $string,
108 normalize => $bool, # Optional
109 smart => $bool, # Optional
110 validate_utf8 => $bool, # Optional
111 );
112 my $doc = CommonMark->parse(
114 file => $handle,
115 normalize => $bool, # Optional
116 smart => $bool, # Optional
117 validate_utf8 => $bool, # Optional
118 );
119 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 Returns the CommonMark::Node of the root document.
126 parse_document
128 my $doc = CommonMark->parse_document( $markdown, [$options] )
129 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 parse_file
135 my $doc = CommonMark->parse_file( $file, [$options] );
136 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 Parser options
142 The parser options are a bit field created by ORing the following
143 constants:
144 CommonMark::OPT_DEFAULT => 0
146 CommonMark::OPT_NORMALIZE
147 CommonMark::OPT_VALIDATE_UTF8
148 CommonMark::OPT_SMART
149 Parser options can be imported from CommonMark with tag "opt".
151 use CommonMark qw(:opt);
153 "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 "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 "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 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 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 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 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 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 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.
271perl v5.38.0 2023-07-20 CommonMark(3)