1HTML::Entities(3)     User Contributed Perl Documentation    HTML::Entities(3)
2
3
4

NAME

6       HTML::Entities - Encode or decode strings with HTML entities
7

SYNOPSIS

9        use HTML::Entities;
10
11        $a = "Våre norske tegn bør &#230res";
12        decode_entities($a);
13        encode_entities($a, "\200-\377");
14
15       For example, this:
16
17        $input = "vis-A~ -vis BeyoncA~X's naA~Xve\npapier-mA~XchA~X rA~XsumA~X";
18        print encode_entities($input), "\n"
19
20       Prints this out:
21
22        vis-à-vis Beyoncé's naïve
23        papier-mâché résumé
24

DESCRIPTION

26       This module deals with encoding and decoding of strings with HTML
27       character entities.  The module provides the following functions:
28
29       decode_entities( $string, ... )
30           This routine replaces HTML entities found in the $string with the
31           corresponding Unicode character.  Under perl 5.6 and earlier only
32           characters in the Latin-1 range are replaced. Unrecognized entities
33           are left alone.
34
35           If multiple strings are provided as argument they are each decoded
36           separately and the same number of strings are returned.
37
38           If called in void context the arguments are decoded in-place.
39
40           This routine is exported by default.
41
42       _decode_entities( $string, \%entity2char )
43       _decode_entities( $string, \%entity2char, $expand_prefix )
44           This will in-place replace HTML entities in $string.  The
45           %entity2char hash must be provided.  Named entities not found in
46           the %entity2char hash are left alone.  Numeric entities are
47           expanded unless their value overflow.
48
49           The keys in %entity2char are the entity names to be expanded and
50           their values are what they should expand into.  The values do not
51           have to be single character strings.  If a key has ";" as suffix,
52           then occurrences in $string are only expanded if properly
53           terminated with ";".  Entities without ";" will be expanded
54           regardless of how they are terminated for compatibility with how
55           common browsers treat entities in the Latin-1 range.
56
57           If $expand_prefix is TRUE then entities without trailing ";" in
58           %entity2char will even be expanded as a prefix of a longer
59           unrecognized name.  The longest matching name in %entity2char will
60           be used. This is mainly present for compatibility with an MSIE
61           misfeature.
62
63              $string = "foo&nbspbar";
64              _decode_entities($string, { nb => "@", nbsp => "\xA0" }, 1);
65              print $string;  # will print "fooA bar"
66
67           This routine is exported by default.
68
69       encode_entities( $string )
70       encode_entities( $string, $unsafe_chars )
71           This routine replaces unsafe characters in $string with their
72           entity representation. A second argument can be given to specify
73           which characters to consider unsafe.  The unsafe characters is
74           specified using the regular expression character class syntax (what
75           you find within brackets in regular expressions).
76
77           The default set of characters to encode are control chars, high-bit
78           chars, and the "<", "&", ">", "'" and """ characters.  But this,
79           for example, would encode just the "<", "&", ">", and """
80           characters:
81
82             $encoded = encode_entities($input, '<>&"');
83
84           and this would only encode non-plain ascii:
85
86             $encoded = encode_entities($input, '^\n\x20-\x25\x27-\x7e');
87
88           This routine is exported by default.
89
90       encode_entities_numeric( $string )
91       encode_entities_numeric( $string, $unsafe_chars )
92           This routine works just like encode_entities, except that the
93           replacement entities are always "&#xhexnum;" and never "&entname;".
94           For example, "encode_entities("r\xF4le")" returns "r&ocirc;le", but
95           "encode_entities_numeric("r\xF4le")" returns "r&#xF4;le".
96
97           This routine is not exported by default.  But you can always export
98           it with "use HTML::Entities qw(encode_entities_numeric);" or even
99           "use HTML::Entities qw(:DEFAULT encode_entities_numeric);"
100
101       All these routines modify the string passed as the first argument, if
102       called in a void context.  In scalar and array contexts, the encoded or
103       decoded string is returned (without changing the input string).
104
105       If you prefer not to import these routines into your namespace, you can
106       call them as:
107
108         use HTML::Entities ();
109         $decoded = HTML::Entities::decode($a);
110         $encoded = HTML::Entities::encode($a);
111         $encoded = HTML::Entities::encode_numeric($a);
112
113       The module can also export the %char2entity and the %entity2char
114       hashes, which contain the mapping from all characters to the
115       corresponding entities (and vice versa, respectively).
116

118       Copyright 1995-2006 Gisle Aas. All rights reserved.
119
120       This library is free software; you can redistribute it and/or modify it
121       under the same terms as Perl itself.
122
123
124
125perl v5.10.1                      2009-10-25                 HTML::Entities(3)
Impressum