Text::Markdown::Discount - markdown to HTML using the Discount C library
0.3.0
use Text::Markdown::Discount;
my $raw-md = '# Hello `World`!'
# render HTML into string...
say markdown($raw-md ); # from a string
say markdown('README.md'.IO); # from a file, note the `.IO`
# ...or directly into files
markdown($raw-md, 'sample.html');
markdown('README.md'.IO, 'README.html');
You can also use the various #Flags in Discount:
say markdown($raw-md, :autolink, :!image ); # MKD_AUTOLINK | MKD_NOIMAGE
say markdown($raw-md, :AUTOLINK, :NOIMAGE); # same thing
The API from Text::Markdown is also supported:
my $md = Text::Markdown::Discount.new($raw-md);
say $md.render;
$md = parse-markdown($raw-md);
say $md.to-html;
say $md.to_html; # same thing
This library provides bindings to the Discount library via NativeCall. You need to have it installed as the libmarkdown shared library.
On Ubuntu 15.04, it's available via apt-get as the libmarkdown2-dev package, the same goes for several Debians. If it's not available as a binary for your system, you can compile it from source.
sub markdown( Cool:D $str, Cool $to-file?, *%flags --> Cool) is export
sub markdown(IO::Path:D $file, Cool $to-file?, *%flags --> Cool) is export
This function is probably enough for most cases. It will either take the markdown from the given $str or $file and convert it to HTML. If $to-file is given, the result will be written to the file at that path and returns True. Otherwise returns a Str with the HTML in it.
Will throw an exception if there's a problem reading or writing files, or if the markdown can't be converted for some reason.
See #Flags about the *%flags parameter.
method from-str(Cool $str, *%flags --> Text::Markdown::Discount:D)
Parses the given $str as markdown and returns an object you can call HTML conversion methods on.
You can call this method on both a class and an object instance.
See #Flags about the *%flags parameter.
method from-file(Cool $file, *%flags --> Text::Markdown::Discount:D)
As #from-str, except will read the markdown from the given $file.
Will fail with an #X::Text::Markdown::Discount::File if it can't fopen the given $file and warn if it can't fclose it.
method to-str(Text::Markdown::Discount:D: --> Str)
Converts the markdown in the caller into HTML and returns the result.
Will fail with a #X::Text::Markdown::Discount::File if Discount can't compile the markdown for some reason.
method to-file(Text::Markdown::Discount:D: Str $file --> Bool)
Converts the markdown in the caller into HTML and writes the result to the given $file. Returns True or an appropriate Failure.
multi method dump-flags(Int:D $fd = 1)
multi method dump-flags(Str:D $file)
Dumps all flag options applied to the caller. Either to the given $file path, or to the file descriptor $fd. Defaults to dumping to file descriptor 1 (stderr).
This function may be useful in figuring out if the Discount library you're linked to actually has the flags you need.
method title(Text::Markdown::Discount:D: --> Str)
Returns the title parsed from the document header.
method author(Text::Markdown::Discount:D: --> Str)
Returns the author parsed from the document header.
method date(Text::Markdown::Discount:D: --> Str)
Returns the date parsed from the document header.
These functions exist so that you can use Text::Markdown::Discount as a drop-in replacement for Text::Markdown. They just dispatch to existing functions:
multi method new($text, *%flags)
sub parse-markdown($text *%flags) is export
Dispatch to #from-str.
method render()
method to-html()
method to_html()
Dispatch to #to-str.
class X::Text::Markdown::Discount is Exception
The base exception class for this module. All other exception types inherit from this. Not actually thrown directly.
class X::Text::Markdown::Discount::File is X::Text::Markdown:Discount
Thrown when an fopen, fdopen or fclose fails. The latter will only be a warning.
class X::Text::Markdown::Discount::Flag is X::Text::Markdown:Discount
Thrown when you try to use a non-existent flag.
class X::Text::Markdown::Discount::Compile is X::Text::Markdown:Discount
Thrown when Discount can't compile markdown. I can't tell when this would happen or where to get the error message from though.
Discount provides a variety of flags that change how the conversion behavior. You can pass flags to all routines that take a *%flags parameter.
The following list of flags is taken from Discount's documentation. Depending on your version of the library, they might not all be available, see #dump-flags.
All of these flags map to the respective MKD_ constants. The keys are case-insensitive. Constants that originally start with NO can be used without it and negated. For example, :!links is the same as :nolinks.
:!links, :nolinks
Don't do link processing, block <a> tags.
:!image, :noimage
Don't do image processing, block <img> .
:!pants, :nopants
Don't run smartypants()
:!html, :nohtml
Don't allow raw html through AT ALL.
:strict
Disable SUPERSCRIPT, RELAXED_EMPHASIS.
:tagtext
Process text inside an html tag; no <em> , no <bold> , no html or [] expansion.
:!ext, :noext
Don't allow pseudo-protocols.
:cdata
Generate code for xml ![CDATA[...]].
:!superscript, :nosuperscript
No A^B.
:!relaxed, :norelaxed
Emphasis happens everywhere.
:!tables, :notables
Don't process PHP Markdown Extra tables.
:!strikethrough, :nostrikethrough
Forbid ~~strikethrough~~.
:toc
Do table-of-contents processing.
:compat
Compatability with MarkdownTest_1.0.
:autolink
Make http://foo.com a link even without <> s.
:safelink
Paranoid check for link protocol.
:!header, :noheader
Don't process document headers.
:tabstop
Expand tabs to 4 spaces.
:!divquote, :nodivquote
Forbid >%class% blocks.
:!alphalist, :noalphalist
Forbid alphabetic lists.
:!dlist, :nodlist
Forbid definition lists.
:extra_footnote
Enable PHP Markdown Extra-style footnotes.
There's probably some bugs in the NativeCall handling. I'm not sure if the types are specified correctly and if the destructor for the native pointers gets called when it needs to.
There seems to be a bug in Discount's mkd_generatehtml function, where it adds excessive nuls to the output if it has previously been compiled to a string. Due to that, the #to-file currently just spurts the string output into the file.
Please report bugs on GitHub.
-
Depend on
Native::LibCforFILEstuff -
Make sure that my NativeCall usage is correct
-
Finish this documentation
-
Ilmari Vacklin - support for document headers.
-
Carsten Hartenfels - original author.
Text::Markdown, Discount, Discount GitHub repository, Text::Markdown::Discount for Perl 5.
This software is copyright 2015 - 2017 by Carsten Hartenfels, with some parts copyright 2017 by Ilmari Vacklin.
This program is distributed under the terms of the Artistic License 2.0.
For further information, please see LICENSE or visit http://www.perlfoundation.org/attachment/legal/artistic-2_0.txt.