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.

link

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

CONSTRUCTORS

parse_markdown

   $st = String::Tagged::Markdown->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, strike and link 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, strike and link tags are preserved, fixed is renamed to monospace.

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>

cpanm String::Tagged::Markdown

perl -MCPAN -e shell
install String::Tagged::Markdown