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.

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.

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.

The character encoding to assume the source file is encoded in (if such cannot be determined by other means, such as a BOM). 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.

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, 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.

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)?},

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.

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.

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

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.

Don't forget to write the documentation in your new parser module! If you copied Text::Markup::HTML, you can just modify as appropriate.

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: