/ 
String-Tagged-Markdown-0.05
River stage one • 1 direct dependent • 3 total dependents
/ String::Tagged::Markdown

NAME

String::Tagged::Markdown - parse and emit text with Markdown inline formatting

SYNOPSIS

use String::Tagged::Markdown;

my $st = String::Tagged::Markdown->parse_markdown( $markdown );

# Conforms to the String::Tagged::Formatting API
String::Tagged::Terminal->new_from_formatting(
   $st->as_formatting
)->say_to_terminal;

DESCRIPTION

This subclass of String::Tagged handles text that contains inline markers to give formatting hints, in the style used by Markdown. For example, text wrapped in double-asterisks indicates it should be bold (as **bold**), or single-asterisks to indicate italics (as *italics*).

This module does not provide a full Markdown parser, but it does handle enough of the simple inline markers that it could be used to handle Markdown-style formatting hints of small paragraphs of text.

TAGS

This module provides the following tags.

bold, italic, strike, fixed

Boolean values indicating bold, italics, strike-through or fixed-width.

String value indicating a link. The value itself is the link target.

CONSTRUCTORS

parse_markdown

$st = String::Tagged::InlineFormatted->parse_markdown( $str )

Parses a text string containing Markdown-like formatting as described above.

Recognises the following kinds of inline text markers:

**bold**

*italic*

~~strike~~

`fixed`

[link](target)

backslashes escape any special characters as \*

In addition, within `fixed` width spans, the other formatting markers are not recognised and are interpreted literally. To include literal backticks inside a `fixed` width span, use multiple backticks and a space to surround the sequence. Any sequence of fewer backticks within the sequence is interpreted literally. A single space on each side immediately within the outer backticks will be stripped, if present.

`` fixed width with `literal backticks` inside it ``

HTML entities - such as &, – or Ӓ are decoded, but only when not inside `fixed` spans.

new_from_formatting

$st = String::Tagged::Markdown->new_from_formatting( $fmt, %args )

Returns a new instance by convertig String::Tagged::Formatting standard tags.

The bold, italic and strike tags are preserved. monospace is renamed to fixed.

Supports the following extra named arguments:

convert_tags => HASH

Optionally provides additional tag conversion callbacks, as defined by "clone" in String::Tagged.

METHODS

build_markdown

$str = $st->build_markdown

Returns a plain text string containing Markdown-like inline formatting markers to format the tags in the given instance. Uses the notation given in the "parse_markdown" method above.

Non-ASCII Unicode characters are not generally emitted as HTML entities; though & and   are generated for convenience.

as_formatting

$fmt = $st->as_formatting( %args )

Returns a new String::Tagged instance tagged with String::Tagged::Formatting standard tags.

The bold, italic and strike tags are preserved, fixed is renamed to monospace. The link tag is currently not represented at all.

Supports the following extra named arguments:

convert_tags => HASH

Optionally provides additional tag conversion callbacks, as defined by "clone" in String::Tagged.

TODO

  • Fine-grained control of what HTML entities are generated on output.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>