| Text::Markup(3pm) | User Contributed Perl Documentation | Text::Markup(3pm) |
Text::Markup - Parse text markup into HTML
my $parser = Text::Markup->new(
default_format => 'markdown',
default_encoding => 'UTF-8',
);
my $html = $parser->parse(file => $markup_file);
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:
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!
"new"
my $parser = Text::Markup->new(default_format => 'markdown');
Supported parameters:
"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.
"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:
"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.
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:
git clone git@github.com:$USER/text-markup.git
cd text-markup
git checkout -b foobar
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
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".
foobar => qr{fb|foob(?:ar)?},
The lowercased name of the format.
The name of the parser module.
The name of a module that's required to be installed in order for your parser to load.
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
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".
git add .
git commit -am 'Add great new FooBar parser!'
git push origin -u foobar
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.
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>.
David E. Wheeler <david@justatheory.com>
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.
| 2019-12-14 | perl v5.30.0 |