Provided by: libtext-markup-perl_0.24-1_all 
Name
Text::Markup - Parse text markup into HTML
Synopsis
my $parser = Text::Markup->new(
default_format => 'markdown',
default_encoding => 'UTF-8',
);
my $html = $parser->parse(file => $markup_file);
Description
This class is really simple. All it does is take the name of a file and return an HTML-formatted version
of that file. The idea is that one might have files in lots of different markups, and not know or care
what markups each uses. It's the job of this module to figure that out, parse it, and give you the
resulting HTML.
This distribution includes support for a number of markup formats:
• Asciidoc <http://www.methods.co.nz/asciidoc/>
• BBcode <http://www.bbcode.org/>
• Creole <http://www.wikicreole.org/>
• HTML <http://whatwg.org/html>
• Markdown <http://daringfireball.net/projects/markdown/>
• MultiMarkdown <http://fletcherpenney.net/multimarkdown/>
• MediaWiki <http://en.wikipedia.org/wiki/Help:Contents/Editing_Wikipedia>
• Pod
• reStructuredText <http://docutils.sourceforge.net/docs/user/rst/quickref.html>
• Textile <http://textism.com/tools/textile/>
• Trac <http://trac.edgewall.org/wiki/WikiFormatting>
Adding support for more markup languages is straight-forward, and patches adding them to this
distribution are also welcome. See "Add a Parser" for step-by-step instructions.
Or if you just want to use this module, then read on!
Interface
Constructor
"new"
my $parser = Text::Markup->new(default_format => 'markdown');
Supported parameters:
"default_format"
The default format to use if one isn't passed to "parse()" and one can't be guessed.
"default_encoding"
The character encoding in which to assume a file is encoded if it's not otherwise explicitly
determined by examination of the source file. Defaults to "UTF-8".
Class Methods
"register"
Text::Markup->register(foobar => qr{fb|foob(?:ar)?});
Registers a markup parser. You likely won't need to use this method unless you're creating a new markup
parser and not contributing it back to the Text::Markup project. See "Add a Parser" for details.
"formats"
my @formats = Text::Markup->formats;
Returns a list of all of the formats currently recognized by Text::Markup. This will include all core
parsers (except for "None") and any that have been loaded elsewhere and that call "register" to register
themselves.
"format_matchers"
my %matchers = Text::Markup->format_matchers;
Returns a list of key/value pairs mapping all the formats returned by "formats" to the regular
expressions used to match them.
Instance Methods
"parse"
my $html = $parser->parse(file => $file_to_parse);
Parses a file and return the generated HTML, or "undef" if no markup was found in the file. Supported
parameters:
"file"
The file from which to read the markup to be parsed. Required.
"format"
The markup format in the file, which determines the parser used to parse it. If not specified,
Text::Markup will try to guess the format from the file's suffix. If it can't guess, it falls back on
"default_format". And if that attribute is not set, it uses the "none" parser, which simply encodes
the entire file and wraps it in a "<pre>" element.
"encoding"
The character encoding to assume the source file is encoded in (if such cannot be determined by other
means, such as a BOM <http://en.wikipedia.org/wiki/Byte_order_mark>). If not specified, the value of
the "default_encoding" attribute will be used, and if that attribute is not set, UTF-8 will be
assumed.
"options"
An array reference of options for the parser. See the documentation of the various parser modules for
details.
"default_format"
my $format = $parser->default_format;
$parser->default_format('markdown');
An accessor for the default format attribute.
"default_encoding"
my $encoding = $parser->default_encoding;
$parser->default_encoding('Big5');
An accessor for the default encoding attribute.
"guess_format"
my $format = $parser->guess_format($filename);
Compares the passed file name's suffix to the regular expressions of all registered formatting parser and
returns the first one that matches. Returns "undef" if none matches.
Add a Parser
Adding support for markup formats not supported by the core Text::Markup distribution is a straight-
forward exercise. Say you wanted to add a "FooBar" markup parser. Here are the steps to take:
1. Fork this project on GitHub <https://github.com/theory/text-markup/>
2. Clone your fork and create a new branch in which to work:
git clone git@github.com:$USER/text-markup.git
cd text-markup
git checkout -b foobar
3. Create a new module named "Text::Markup::FooBar". The simplest thing to do is copy an existing module
and modify it. The HTML parser is probably the simplest:
cp lib/Text/Markup/HTML.pm lib/Text/Markup/FooBar.pm
perl -i -pe 's{HTML}{FooBar}g' lib/Text/Markup/FooBar.pm
perl -i -pe 's{html}{foobar}g' lib/Text/Markup/FooBar.pm
4. Implement the "parser" function in your new module. If you were to use a "Text::FooBar" module, it
might look something like this:
package Text::Markup::FooBar;
use 5.8.1;
use strict;
use Text::FooBar ();
use File::BOM qw(open_bom)
sub parser {
my ($file, $encoding, $opts) = @_;
my $md = Text::FooBar->new(@{ $opts || [] });
open_bom my $fh, $file, ":encoding($encoding)";
local $/;
my $html = $md->parse(<$fh>);
return unless $html =~ /\S/;
utf8::encode($html);
return join( "\n",
'<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />',
'</head>',
'<body>',
$html,
'</body>',
'</html>',
);
}
Use the $encoding argument as appropriate to read in the source file. If your parser requires that
text be decoded to Perl's internal form, use of File::BOM is recommended, so that an explicit BOM
will determine the encoding. Otherwise, fall back on the specified encoding. Note that some parsers,
such as an HTML parser, would want text encoded before it parsed it. In such a case, read in the
file as raw bytes:
open my $fh, '<:raw', $file or die "Cannot open $file: $!\n";
The returned HTML, however, must be encoded in UTF-8. Please include an encoding declaration
<http://en.wikipedia.org/wiki/Character_encodings_in_HTML>, such as a content-type "<meta>" element:
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
This will allow any consumers of the returned HTML to parse it correctly. If the parser parsed no
content, "parser()" should return "undef".
5. Edit lib/Text/Markup.pm and add an entry to its %REGEX_FOR hash for your new format. The key should
be the name of the format (lowercase, the same as the last part of your module's name). The value
should be a regular expression that matches the file extensions that suggest that a file is formatted
in your parser's markup language. For our FooBar parser, the line might look like this:
foobar => qr{fb|foob(?:ar)?},
6. Add a file in your parser's markup language to t/markups. It should be named for your parser and end
in .txt, that is, t/markups/foobar.txt.
7. Add an HTML file, t/html/foobar.html, which should be the expected output once t/markups/foobar.txt
is parsed into HTML. This will be used to test that your parser works correctly.
8. Edit t/formats.t by adding a line to its "__DATA__" section. The line should be a comma-separated
list describing your parser. The columns are:
• Format
The lowercased name of the format.
• Format Module
The name of the parser module.
• Required Module
The name of a module that's required to be installed in order for your parser to load.
• Extensions
Additional comma-separated values should be a list of file extensions that your parser should
recognize.
So for our FooBar parser, it might look like this:
markdown,Text::Markup::FooBar,Text::FooBar 0.22,fb,foob,foobar
9. Test your new parser by running
prove -lv t/formats.t
This will test all included parsers, but of course you should only pay attention to how your parser
works. Tweak until your tests pass. Note that one test has the parser parse a file with just a couple
of empty lines, to ensure that the parser finds no content and returns "undef".
10. Don't forget to write the documentation in your new parser module! If you copied Text::Markup::HTML,
you can just modify as appropriate.
11. Add any new module requirements to the "requires" section of Build.PL.
12. Commit and push the branch to your fork on GitHub:
git add .
git commit -am 'Add great new FooBar parser!'
git push origin -u foobar
13. And finally, submit a pull request to the upstream repository via the GitHub UI.
If you don't want to submit your parser, you can still create and use one independently. Rather than add
its information to the %REGEX_FOR hash in this module, you can just load your parser manually, and have
it call the "register" method, like so:
package My::Markup::FooBar;
use Text::Markup;
Text::Markup->register(foobar => qr{fb|foob(?:ar)?});
This will be useful for creating private parsers you might not want to contribute, or that you'd want to
distribute independently.
See Also
• The markup <https://github.com/github/markup> Ruby library -- the inspiration for this module --
provides similar functionality, and is used to parse README.your_favorite_markup on GitHub.
• Markup::Unified offers similar functionality.
Support
This module is stored in an open GitHub repository <http://github.com/theory/text-markup/>. Feel free to
fork and contribute!
Please file bug reports via GitHub Issues <http://github.com/theory/text-markup/issues/> or by sending
mail to bug-Text-Markup@rt.cpan.org <mailto:bug-Text-Markup@rt.cpan.org>.
Author
David E. Wheeler <david@justatheory.com>
Copyright and License
Copyright (c) 2011-2019 David E. Wheeler. Some Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl
itself.
perl v5.30.0 2019-12-14 Text::Markup(3pm)