view release on metacpan or  search on metacpan

lib/Encode/Wide.pm  view on Meta::CPAN

		[ 'ç', 'ç' ],
		[ 'ê', 'ê' ],
		[ 'ë', 'ë' ],
		[ 'ð', 'ð' ],
		[ 'í', 'í' ],
		[ 'ï', 'ï' ],
		[ 'ÃŽ', 'Î' ],
		[ '©', '©' ],
		[ '®', '®' ],
		[ 'ó', 'ó' ],
		[ 'ô', 'ô' ],
		[ 'ö', 'ö' ],
		[ 'ø', 'ø' ],
		[ 'Å›', 'ś' ],
		[ 'Þ', 'Þ' ],
		[ 'þ', 'þ' ],
		[ 'û', 'û' ],
		[ 'ü', 'ü' ],
		[ 'ú', 'ú' ],
		[ 'µ', 'µ'],
		[ '£', '£' ],
		[ 'ß', 'ß' ],
		[ '–', '–' ],
		[ '—', '—' ],
		[ 'ñ', 'ñ' ],
		[ '“', '"' ],
		[ '”', '"' ],
		[ '«', '"' ],
		[ '»', '"' ],
		[ '…', '...' ],
		[ 'â„¢', '™' ],
		[ '●', '●' ],
		[ "\x80\$", ' ' ],
	);

	$string = _sub_map(\$string, \@byte_map);

	if($string =~ /[^[:ascii:]]/) {
		$string = HTML::Entities::encode_entities_numeric($string, '\x80-\x{10FFFF}');
		if($string =~ /[^[:ascii:]]/) {
			$complain->("TODO: wide_to_html($string)") if($complain);
			# Sanitize non-ASCII to hex tokens before embedding in the error message
			$string =~ s{
					([^[:ascii:]])
				}{
					'>>>>' . sprintf('%04X', ord($1)) . '<<<<'
				}gex;
			carp "TODO: wide_to_html($string)";
			croak "BUG: wide_to_html($string)";
		}
	}

	return $string;
}

=head2 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. C<&#x0E9;>).  Only numeric entities are used because named HTML entities
such as C<&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 C<->.
Bare ampersands, angle brackets, and double-quotes are escaped so the output
is valid XML element content.

=head3 Arguments

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

See L</COMMON PARAMETERS> for C<string>, C<keep_hrefs>, and C<complain>.
This function does not accept C<keep_apos>.

=head3 Returns

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

=head3 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;'

=head3 MESSAGES

=over 4

=item C<Usage: wide_to_xml() string not set>

B<Fatal> (via C<croak>).  The C<string> parameter was C<undef>.
Resolution: pass a defined scalar or scalar reference.

=item C<TODO: wide_to_xml(E<lt>hex-tokens...E<gt>)>

B<Warning> (via C<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 L<https://rt.cpan.org/Public/Dist/Display.html?Name=Encode-Wide>.