.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Text::Markup 3pm"
.TH Text::Markup 3pm 2024-03-03 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH Name
.IX Header "Name"
Text::Markup \- Parse text markup into HTML
.SH Synopsis
.IX Header "Synopsis"
.Vb 4
\&  my $parser = Text::Markup\->new(
\&      default_format   => \*(Aqmarkdown\*(Aq,
\&      default_encoding => \*(AqUTF\-8\*(Aq,
\&  );
\&
\&  my $html = $parser\->parse(file => $markup_file);
.Ve
.SH Description
.IX Header "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.
.PP
This distribution includes support for a number of markup formats:
.IP \(bu 4
Asciidoc <https://asciidoc.org>
.IP \(bu 4
BBcode <https://www.bbcode.org/>
.IP \(bu 4
Creole <https://www.wikicreole.org/>
.IP \(bu 4
HTML <https://whatwg.org/html>
.IP \(bu 4
Markdown <https://daringfireball.net/projects/markdown/>
.IP \(bu 4
MediaWiki <https://en.wikipedia.org/wiki/Help:Contents/Editing_Wikipedia>
.IP \(bu 4
MultiMarkdown <https://fletcherpenney.net/multimarkdown/>
.IP \(bu 4
Pod
.IP \(bu 4
reStructuredText <https://docutils.sourceforge.io/rst.html>
.IP \(bu 4
Textile <https://textile-lang.com/>
.IP \(bu 4
Trac <https://trac.edgewall.org/wiki/WikiFormatting>
.PP
Modules under the Text::Markup namespace provide these parsers, and Text::Markup
automatically loads them on recognizing file name suffixes documented for each
module. To change the file extensions recognized for a particular parser (except
for Text::Markup::None), load it directly and pass a regular expression. For
example, to have the Mediawiki parser recognized files with the suffixes
\&\f(CW\*(C`truck\*(C'\fR, \f(CW\*(C`truc\*(C'\fR, \f(CW\*(C`track\*(C'\fR, or \f(CW\*(C`trac\*(C'\fR, load it like so:
.PP
.Vb 1
\&  use Text::Markup::Mediawiki qr{tr[au]ck?};
.Ve
.PP
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.
.PP
Or if you just want to use this module, then read on!
.SH Interface
.IX Header "Interface"
.SS Constructor
.IX Subsection "Constructor"
\fR\f(CI\*(C`new\*(C'\fR\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(CWparse()\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
"UTF\-8".
.SS "Class Methods"
.IX Subsection "Class Methods"
\fR\f(CI\*(C`register\*(C'\fR\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 "Add a Parser" for details.
.PP
\fR\f(CI\*(C`formats\*(C'\fR\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 "None") and any that have been
loaded elsewhere and that call \f(CW\*(C`register\*(C'\fR to register themselves.
.PP
\fR\f(CI\*(C`format_matchers\*(C'\fR\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"
\fR\f(CI\*(C`parse\*(C'\fR\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 HTML, 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`<pre>\*(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
BOM <https://en.wikipedia.org/wiki/Byte_order_mark>). 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, UTF\-8 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
\fR\f(CI\*(C`default_format\*(C'\fR\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
\fR\f(CI\*(C`default_encoding\*(C'\fR\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
\fR\f(CI\*(C`guess_format\*(C'\fR\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 "FooBar"
markup parser. Here are the steps to take:
.IP 1. 4
Fork this project on GitHub <https://github.com/theory/text-markup/>
.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 HTML 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 import {
\&      # Replace the regex if passed one.
\&      Text::Markup\->register( foobar => $_[1] ) if $_[1];
\&  }
\&
\&  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<meta http\-equiv="Content\-Type" content="text/html; charset=UTF\-8" />\*(Aq,
\&          \*(Aq</head>\*(Aq,
\&          \*(Aq<body>\*(Aq,
\&          $html,
\&          \*(Aq</body>\*(Aq,
\&          \*(Aq</html>\*(Aq,
\&      );
\&  }
.Ve
.Sp
Use the \f(CW$encoding\fR 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:
.Sp
.Vb 1
\&      open my $fh, \*(Aq<:raw\*(Aq, $file or die "Cannot open $file: $!\en";
.Ve
.Sp
The returned HTML, however, \fBmust be encoded in UTF\-8\fR. Please include an
encoding declaration <https://en.wikipedia.org/wiki/Character_encodings_in_HTML>,
such as a content-type \f(CW\*(C`<meta>\*(C'\fR element:
.Sp
.Vb 1
\&  <meta http\-equiv="Content\-Type" content="text/html; charset=UTF\-8" />
.Ve
.Sp
This will allow any consumers of the returned HTML to parse it correctly.
If the parser parsed no content, \f(CWparser()\fR should return \f(CW\*(C`undef\*(C'\fR.
.IP 5. 4
Edit \fIlib/Text/Markup.pm\fR and add an entry to its \f(CW%REGEX_FOR\fR 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:
.Sp
.Vb 1
\&    foobar => qr{fb|foob(?:ar)?},
.Ve
.IP 6. 4
Add a file in your parser's markup language to \fIt/markups\fR. It should be
named for your parser and end in \fI.txt\fR, that is, \fIt/markups/foobar.txt\fR.
.IP 7. 4
Add an HTML file, \fIt/html/foobar.html\fR, which should be the expected output
once \fIt/markups/foobar.txt\fR is parsed into HTML. This will be used to test
that your parser works correctly.
.IP 8. 4
Edit \fIt/formats.t\fR by adding a line to its \f(CW\*(C`_\|_DATA_\|_\*(C'\fR section. The line
should be a comma-separated list describing your parser. The columns are:
.RS 4
.IP \(bu 4
Format
.Sp
The lowercased name of the format.
.IP \(bu 4
Format Module
.Sp
The name of the parser module.
.IP \(bu 4
Required Module
.Sp
The name of a module that's required to be installed in order for your parser
to load.
.IP \(bu 4
Extensions
.Sp
Additional comma-separated values should be a list of file extensions that
your parser should recognize.
.RE
.RS 4
.Sp
So for our FooBar parser, it might look like this:
.Sp
.Vb 1
\&  markdown,Text::Markup::FooBar,Text::FooBar 0.22,fb,foob,foobar
.Ve
.RE
.IP 9. 4
Test your new parser by running
.Sp
.Vb 1
\&  prove \-lv t/formats.t
.Ve
.Sp
This will test \fIall\fR 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 \f(CW\*(C`undef\*(C'\fR.
.IP 10. 4
Don't forget to write the documentation in your new parser module! If you
copied \fIText::Markup::HTML\fR, you can just modify as appropriate.
.IP 11. 4
Add any new module requirements to the \f(CW\*(C`requires\*(C'\fR section of \fIBuild.PL\fR.
.IP 12. 4
Commit and push the branch to your fork on GitHub:
.Sp
.Vb 3
\&  git add .
\&  git commit \-am \*(AqAdd great new FooBar parser!\*(Aq
\&  git push origin \-u foobar
.Ve
.IP 13. 4
And finally, submit a pull request to the upstream repository via the GitHub
UI.
.PP
If you don't want to submit your parser, you can still create and use one
independently. Just omit editing the \f(CW%REGEX_FOR\fR hash in this module and make
sure you \f(CW\*(C`register\*(C'\fR the parser manually with a default regular expression
in the \f(CW\*(C`import\*(C'\fR method, like so:
.PP
.Vb 5
\&  package My::Markup::FooBar;
\&  use Text::Markup;
\&  sub import {
\&      Text::Markup\->register( foobar => $_[1] || qr{fb|foob(?:ar)?} );
\&  }
.Ve
.PP
This will be useful for creating private parsers you might not want to
contribute, or that you'd want to distribute independently.
.SH "See Also"
.IX Header "See Also"
.IP \(bu 4
The markup <https://github.com/github/markup> Ruby library \-\- the inspiration
for this module \-\- provides similar functionality, and is used to parse
\&\fIREADME.your_favorite_markup\fR on GitHub.
.IP \(bu 4
Markup::Unified offers similar functionality.
.SH Support
.IX Header "Support"
This module is stored in an open
GitHub repository <https://github.com/theory/text-markup/>. Feel free to
fork and contribute!
.PP
Please file bug reports via
GitHub Issues <https://github.com/theory/text-markup/issues/>.
.SH Author
.IX Header "Author"
David E. Wheeler <david@justatheory.com>
.SH "Copyright and License"
.IX Header "Copyright and License"
Copyright (c) 2011\-2024 David E. Wheeler. Some Rights Reserved.
.PP
This module is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.