NAME
    HTML::HTML5::Entities - drop-in replacement for HTML::Entities

SYNOPSIS
     use HTML::Entities;
 
     my $enc = encode_entities('fish & chips');
     print "$enc\n";   # fish & chips
 
     my $dec = decode_entities($enc);
     print "$dec\n";   # fish & chips

DESCRIPTION
    This is a drop-in replacement for HTML::Entities, providing the character
    entities defined in HTML5. Some caveats:

    *   The implementation is pure perl, hence in some cases slower,
        especially decoding.

    *   It will not work in Perl < 5.8.1.

  Functions
    `decode_entities($string, ...)`
        This routine replaces HTML entities found in the $string with the
        corresponding Unicode character. If multiple strings are provided as
        arguments they are each decoded separately and the same number of
        strings are returned.

        If called in void context the arguments are decoded in-place.

        This routine is exported by default.

    `_decode_entities($string, \%entity2char)`
    `_decode_entities($string, \%entity2char, $expand_prefix)`
        This will in-place replace HTML entities in $string. The %entity2char
        hash must be provided. Named entities not found in the %entity2char
        hash are left alone. Numeric entities are always expanded.

        If $expand_prefix is TRUE then entities without trailing ";" in
        %entity2char will even be expanded as a prefix of a longer
        unrecognized name.

         $string = "foo&nbspbar";
         _decode_entities($string, { nb => "@", nbsp => "\xA0" }, 1);
         print $string;  # will print "foo bar"

        This routine is exported by default.

    `encode_entities($string)`
    `encode_entities($string, $unsafe_chars)`
        This routine replaces unsafe characters in $string with their entity
        representation. A second argument can be given to specify which
        characters to consider unsafe (i.e., which to escape). This may be a
        regular expression.

        If called in void context the string is encoded in-place.

        This routine is exported by default.

    `encode_entities_numeric($string)`
        This routine works just like encode_entities, except that the
        replacement entities are always numeric.

        This routine is not exported by default.

    `num_entity($string)`
        Given a single character string, encodes it as a numeric entity.

        This routine is not exported by default.

    The following functions cannot be exported. They behave the same as the
    exportable functions.

    `HTML::Entities::decode($string, ...)`
    `HTML::Entities::encode($string)`
    `HTML::Entities::encode($string, $unsafe_characters)`
    `HTML::Entities::encode_numeric($string)`
    `HTML::Entities::encode_numeric($string, $unsafe_characters)`
    `HTML::Entities::encode_numerically($string)`
    `HTML::Entities::encode_numerically($string, $unsafe_characters)`

  Variables
    $HTML::HTML5::Entities::hex
        This variable controls whether numeric entities will use hexadecimal
        or decimal notation. It is TRUE (hexadecimal) by default, but can be
        set to FALSE.

        It only affects the encoding functions. Decoding always understands
        both notations.

    %HTML::HTML5::Entities::char2entity
    %HTML::HTML5::Entities::entity2char
        There contain the mapping from all characters to the corresponding
        entities (and vice versa, respectively). These variables may be
        exported.

        Note that %char2entity is a more conservative set of mappings,
        intended to be safe for serialising strings to HTML4, HTML5 and XHTML
        1.x. And for hysterical raisins, %entity2char does not include the
        leading ampersands, while %char2entity does.

BUGS
    Please report any bugs to
    <http://rt.cpan.org/Dist/Display.html?Queue=HTML-HTML5-Entities>.

SEE ALSO
    HTML::Entities, HTML::HTML5::Parser, HTML::HTML5::Writer.

AUTHOR
    Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE
  Encoding and Decoding Functions
    Copyright (c) 1995-2006 by Gisle Aas.

    Copyright (c) 2012 by Toby Inkster.

    This is free software; you can redistribute it and/or modify it under the
    same terms as the Perl 5 programming language system itself.

  Entity Tables
    Copyright (c) 2004-2007 by Apple Computer Inc, Mozilla Foundation, and
    Opera Software ASA.

    Copyright (c) 2007-2011 by Wakaba <w@suika.fam.cx>.

    Copyright (c) 2009-2012 by Toby Inkster <tobyink@cpan.org>.

DISCLAIMER OF WARRANTIES
    THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
    WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
    MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.