Text::Markup(3pm)

📦
version 0.41 · 3 versions
, in ubuntu resolute, ubuntu stonking

✨ NAME ✨

Text::Markup — parse text markup into HTML 💅

(yes bestie, this is the manual page for Text::Markup(3pm), the Perl module that looks at a file, figures out what kind of markup it's written in, and hands you back HTML. it's giving main character energy.)

🌈 SYNOPSIS 🌈

my $parser = Text::Markup->new(
    default_format   => 'markdown',
    default_encoding => 'UTF-8',
);

my $html = $parser->parse(file => $markup_file);

💖 DESCRIPTION 💖

okay so this class is genuinely simple. like, uncomplicated. it takes the name of a file and gives you back an HTML-formatted version of that file. periodt.

the whole idea is: you might have files sitting around in a whole bunch of different markup languages, and you do not know — and honestly could not care less — which markup each one is using. so that's the job of this module: figure it out, parse it, and hand you the resulting HTML. 🫶

this distribution comes with support for a bunch of markup formats:

modules living under the Text::Markup namespace are the ones providing these parsers, and Text::Markup automatically loads them the second it recognizes file name suffixes documented for each module. 🎀

so if you want to change which file extensions get recognized for a particular parser (heads up: this does not apply to Text::Markup::None), just load that parser directly and pass it a regular expression. like, say you wanted the Mediawiki parser to recognize files with the suffixes truck, truc, track, or trac — you'd load it like this:

use Text::Markup::Mediawiki qr{tr[au]ck?};

adding support for even more markup languages is straight-forward, and ngl, patches that add them to this distribution are super welcome. check out "Add a Parser" for the step-by-step.

or, if you're just here to use this module, then read on bestie 💅

🎀 INTERFACE 🎀

🧚 CONSTRUCTOR

new

my $parser = Text::Markup->new(default_format => 'markdown');

here are the parameters it supports:

  • 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. realistically you won't need this method unless you're creating a brand new markup parser and not contributing it back to the Text::Markup project. details are in "Add a Parser".

formats

my @formats = Text::Markup->formats;

returns a list of every format Text::Markup currently recognizes. that includes all the core parsers (except for None) plus any that got loaded somewhere else and called 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 returns the generated HTML — or undef if no markup was found in the file. 👀 here's what it supports:

  • 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 you don't specify it, 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 isn't set either, it uses the none parser, which just encodes the entire file and wraps it in a <pre> element.
  • encoding — the character encoding to assume the source file is encoded in (if that can't be determined by other means, like a BOM — https://en.wikipedia.org/wiki/Byte_order_mark). if not specified, the value of the default_encoding attribute gets used, and if that attribute isn't set, UTF-8 is assumed.
  • options — an array reference of options for the parser. go read the documentation of the various parser modules for the deets.

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 against the regular expressions of all registered formatting parsers and returns the first one that matches. returns undef if none of them match. 😭

🦋 ADD A PARSER 🦋

adding support for markup formats that the core Text::Markup distribution doesn't support is a straight-forward exercise, fr fr. 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
  1. 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 one:
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
  1. 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 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 =~ /\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, using File::BOM is recommended, so that an explicit BOM will determine the encoding. otherwise, fall back on the specified encoding. heads up tho: some parsers, like an HTML parser, would want text encoded before it parsed it. in that 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 — https://en.wikipedia.org/wiki/Character_encodings_in_HTML — like a content-type <meta> element:

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

this will let any consumers of the returned HTML parse it correctly. and if the parser parsed no content, parser() should return undef.

  1. 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 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)?},
  1. 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.
  2. Add an HTML file, t/html/foobar.html, which should be the expected output once t/markups/foobar.txt is parsed into HTML. this gets used to test that your parser works correctly. ⭐
  3. 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
  1. Test your new parser by running
prove -lv t/formats.t

this tests all the included parsers, but obviously you should only be paying 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 make sure the parser finds no content and returns undef.

  1. Don't forget to write the documentation in your new parser module! if you copied Text::Markup::HTML, you can just modify as appropriate. 📝
  2. Add any new module requirements to the requires section of Build.PL.
  3. 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
  1. 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. just skip editing the %REGEX_FOR hash in this module and make sure you register the parser manually with a default regular expression in the import method, like so:

package My::Markup::FooBar;
use Text::Markup;
sub import {
    Text::Markup->register( foobar => $_[1] || qr{fb|foob(?:ar)?} );
}

this will be useful for creating private parsers you might not want to contribute, or ones you'd want to distribute independently. 💅

✨ See Also ✨

  • The markup Ruby library — https://github.com/github/markup — this is literally the inspiration for this module, bestie. It provides similar functionality, and it's used to parse README.your_favorite_markup on GitHub. 💖
  • Markup::Unified — offers similar functionality, so if you vibe with that, go off. 🦋

🫶 Support 🫶

This module is stored in an open GitHub repository — https://github.com/theory/text-markup/ — feel free to fork and contribute! No gatekeeping here. 💅

Please file bug reports via GitHub Issues — https://github.com/theory/text-markup/issues/ — and that's the move, periodt. 🐛

👑 Author 👑

David E. Wheeler david@justatheory.com — that's the icon, the moment, the whole vibe. ✨

Copyright (c) 2011-2025 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. So yes, it's giving open source, but keep the license intact, bestie. 💖

This page was brought to you by perl v5.40.1, dated 2025-12-18, and it's Text::Markup(3pm) signing off — periodt. 💅✨

📦 where this page comes from