view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

### MESSAGES

- `Usage: wide_to_html() string not set`

    **Fatal** (via `croak`).  The `string` parameter was `undef`.
    Resolution: pass a defined scalar or scalar reference.

- `TODO: wide_to_html(<hex-tokens...>)`

    **Warning** (via `carp`).  A character survived all three byte\_map passes and
    the `encode_entities_numeric` fallback.  The hex tokens in the message
    identify the unhandled codepoint(s).
    Resolution: add the character to the appropriate byte\_map array, or file a bug
    report at [https://rt.cpan.org/Public/Dist/Display.html?Name=Encode-Wide](https://rt.cpan.org/Public/Dist/Display.html?Name=Encode-Wide).

- `BUG: wide_to_html(<hex-tokens...>)`

    **Fatal** (via `croak`), always preceded by the `TODO` warning above.
    The same unhandled-character condition caused a hard failure.  This should
    never occur in normal use; it indicates a gap in the character tables.

### API SPECIFICATION

#### Input

    {
        string     => { type => SCALAR | SCALARREF, required => 1, defined => 1 },
        keep_hrefs => { type => BOOLEAN, optional => 1, default => 0 },
        keep_apos  => { type => BOOLEAN, optional => 1, default => 0 },
        complain   => { type => CODEREF,  optional => 1 },
    }

#### Output

    { type => SCALAR, constraint => sub { $_[0] !~ /[^[:ascii:]]/ } }

### PSEUDOCODE

     1. Unless keep_hrefs: decode HTML entities via HTML::Entities::decode
        and the four extra named entities (&ccaron; &zcaron; &Zcaron; &Scaron;)
     2. Escape bare & not followed by a valid entity name
        (possessive ++ quantifier prevents ReDoS backtracking)
     3. Unless keep_hrefs: escape <, >, and " using %_HTML_ESCAPE (no /e eval)
     4. First byte_map pass: typographic punctuation and exclamation mark
     5. Unless keep_apos: encode apostrophe variants to &apos;
        using an alternation regex built from the apostrophe key set
     6. Early return if the string is now pure ASCII
     7. Second byte_map pass: raw UTF-8 byte sequences -> named HTML entities
     8. Third byte_map pass: Perl Unicode chars (\N{U+...}) -> named HTML entities
     9. Fallback: HTML::Entities::encode_entities_numeric for any remaining
        non-ASCII codepoints
    10. If non-ASCII still remains after the fallback: invoke complain callback,
        carp a TODO warning, then croak a BUG error

## wide\_to\_xml

Convert a Unicode or UTF-8 string into a pure-ASCII XML fragment.  Every
non-ASCII character is replaced by a hexadecimal numeric entity
(e.g. `&#x0E9;`).  Only numeric entities are used because named HTML entities
such as `&eacute;` are not defined in XML 1.0 outside of XHTML with a DTD.
Em-dashes and en-dashes are folded to a plain ASCII hyphen `-`.
Bare ampersands, angle brackets, and double-quotes are escaped so the output
is valid XML element content.

### Arguments

All parameters are passed as a flat key-value list.  The `string` key may be
omitted when passing a bare positional string as the first argument.

See ["COMMON PARAMETERS"](#common-parameters) for `string`, `keep_hrefs`, and `complain`.
This function does not accept `keep_apos`.

### Returns

A defined scalar string whose every character is in the ASCII range
(code points 0x00-0x7F).  The empty string is returned unchanged.

### EXAMPLE

    use Encode::Wide qw(wide_to_xml);

    # Accented characters become numeric entities
    my $out = wide_to_xml(string => "SURN \x{017D}ganjar");
    # => 'SURN &#x17D;ganjar'

    # En-dash and em-dash are folded to a plain hyphen
    $out = wide_to_xml(string => "2020\x{2013}2026");
    # => '2020-2026'

    # Ampersands and angle brackets are XML-escaped
    $out = wide_to_xml(string => 'a < b & c > 0');
    # => 'a &lt; b &amp; c &gt; 0'

    # keep_hrefs: XML tags pass through; wide chars are still encoded
    $out = wide_to_xml(
        string     => '<item lang="fr">Caf\x{E9}</item>',
        keep_hrefs => 1,
    );
    # => '<item lang="fr">Caf&#x0E9;</item>'

    # Scalar reference input
    my $text = "caf\x{E9}";
    $out = wide_to_xml(string => \$text);
    # => 'caf&#x0E9;'

### MESSAGES

- `Usage: wide_to_xml() string not set`

    **Fatal** (via `croak`).  The `string` parameter was `undef`.
    Resolution: pass a defined scalar or scalar reference.

- `TODO: wide_to_xml(<hex-tokens...>)`

    **Warning** (via `carp`).  A character survived all three byte\_map passes.
    The hex tokens in the message identify the unhandled codepoint(s).
    Resolution: add the character to the appropriate byte\_map array, or file a bug
    report at [https://rt.cpan.org/Public/Dist/Display.html?Name=Encode-Wide](https://rt.cpan.org/Public/Dist/Display.html?Name=Encode-Wide).

- `BUG: wide_to_xml(<hex-tokens...>)`