.PP
Adding support for more markup languages is straight-forward, and patches
adding them to this distribution are also welcome. See \*(L"Add a Parser\*(R" for
step-by-step instructions.
.PP
Or if you just want to use this module, then read on!
.SH "Interface"
.IX Header "Interface"
.SS "Constructor"
.IX Subsection "Constructor"
\fI\f(CI\*(C`new\*(C'\fI\fR
.IX Subsection "new"
.PP
.Vb 1
\& my $parser = Text::Markup\->new(default_format => \*(Aqmarkdown\*(Aq);
.Ve
.PP
Supported parameters:
.ie n .IP """default_format""" 4
.el .IP "\f(CWdefault_format\fR" 4
.IX Item "default_format"
The default format to use if one isn't passed to \f(CW\*(C`parse()\*(C'\fR and one can't be
guessed.
.ie n .IP """default_encoding""" 4
.el .IP "\f(CWdefault_encoding\fR" 4
.IX Item "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
\&\*(L"\s-1UTF\-8\*(R".\s0
.SS "Class Methods"
.IX Subsection "Class Methods"
\fI\f(CI\*(C`register\*(C'\fI\fR
.IX Subsection "register"
.PP
.Vb 1
\& Text::Markup\->register(foobar => qr{fb|foob(?:ar)?});
.Ve
.PP
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 \*(L"Add a Parser\*(R" for details.
.PP
\fI\f(CI\*(C`formats\*(C'\fI\fR
.IX Subsection "formats"
.PP
.Vb 1
\& my @formats = Text::Markup\->formats;
.Ve
.PP
Returns a list of all of the formats currently recognized by Text::Markup.
This will include all core parsers (except for \*(L"None\*(R") and any that have been
loaded elsewhere and that call \f(CW\*(C`register\*(C'\fR to register themselves.
.PP
\fI\f(CI\*(C`format_matchers\*(C'\fI\fR
.IX Subsection "format_matchers"
.PP
.Vb 1
\& my %matchers = Text::Markup\->format_matchers;
.Ve
.PP
Returns a list of key/value pairs mapping all the formats returned by
\&\f(CW\*(C`formats\*(C'\fR to the regular expressions used to match them.
.SS "Instance Methods"
.IX Subsection "Instance Methods"
\fI\f(CI\*(C`parse\*(C'\fI\fR
.IX Subsection "parse"
.PP
.Vb 1
\& my $html = $parser\->parse(file => $file_to_parse);
.Ve
.PP
Parses a file and return the generated \s-1HTML,\s0 or \f(CW\*(C`undef\*(C'\fR if no markup was
found in the file. Supported parameters:
.ie n .IP """file""" 4
.el .IP "\f(CWfile\fR" 4
.IX Item "file"
The file from which to read the markup to be parsed. Required.
.ie n .IP """format""" 4
.el .IP "\f(CWformat\fR" 4
.IX Item "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 \f(CW\*(C`default_format\*(C'\fR. And if that
attribute is not set, it uses the \f(CW\*(C`none\*(C'\fR parser, which simply encodes the
entire file and wraps it in a \f(CW\*(C`\*(C'\fR element.
.ie n .IP """encoding""" 4
.el .IP "\f(CWencoding\fR" 4
.IX Item "encoding"
The character encoding to assume the source file is encoded in (if such cannot
be determined by other means, such as a
\&\s-1BOM\s0 ). If not specified, the
value of the \f(CW\*(C`default_encoding\*(C'\fR attribute will be used, and if that attribute
is not set, \s-1UTF\-8\s0 will be assumed.
.ie n .IP """options""" 4
.el .IP "\f(CWoptions\fR" 4
.IX Item "options"
An array reference of options for the parser. See the documentation of the
various parser modules for details.
.PP
\fI\f(CI\*(C`default_format\*(C'\fI\fR
.IX Subsection "default_format"
.PP
.Vb 2
\& my $format = $parser\->default_format;
\& $parser\->default_format(\*(Aqmarkdown\*(Aq);
.Ve
.PP
An accessor for the default format attribute.
.PP
\fI\f(CI\*(C`default_encoding\*(C'\fI\fR
.IX Subsection "default_encoding"
.PP
.Vb 2
\& my $encoding = $parser\->default_encoding;
\& $parser\->default_encoding(\*(AqBig5\*(Aq);
.Ve
.PP
An accessor for the default encoding attribute.
.PP
\fI\f(CI\*(C`guess_format\*(C'\fI\fR
.IX Subsection "guess_format"
.PP
.Vb 1
\& my $format = $parser\->guess_format($filename);
.Ve
.PP
Compares the passed file name's suffix to the regular expressions of all
registered formatting parser and returns the first one that matches. Returns
\&\f(CW\*(C`undef\*(C'\fR if none matches.
.SH "Add a Parser"
.IX Header "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 \*(L"FooBar\*(R"
markup parser. Here are the steps to take:
.IP "1." 4
Fork this project on GitHub
.IP "2." 4
Clone your fork and create a new branch in which to work:
.Sp
.Vb 3
\& git clone git@github.com:$USER/text\-markup.git
\& cd text\-markup
\& git checkout \-b foobar
.Ve
.IP "3." 4
Create a new module named \f(CW\*(C`Text::Markup::FooBar\*(C'\fR. The simplest thing to do is
copy an existing module and modify it. The \s-1HTML\s0 parser is probably the simplest:
.Sp
.Vb 3
\& cp lib/Text/Markup/HTML.pm lib/Text/Markup/FooBar.pm
\& perl \-i \-pe \*(Aqs{HTML}{FooBar}g\*(Aq lib/Text/Markup/FooBar.pm
\& perl \-i \-pe \*(Aqs{html}{foobar}g\*(Aq lib/Text/Markup/FooBar.pm
.Ve
.IP "4." 4
Implement the \f(CW\*(C`parser\*(C'\fR function in your new module. If you were to use a
\&\f(CW\*(C`Text::FooBar\*(C'\fR module, it might look something like this:
.Sp
.Vb 1
\& 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 =~ /\eS/;
\& utf8::encode($html);
\& return join( "\en",
\& \*(Aq\*(Aq,
\& \*(Aq\*(Aq,
\& \*(Aq\*(Aq,
\& $html,
\& \*(Aq\*(Aq,
\& \*(Aq