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>