blib/lib/HTML/Entities.pm

filter: Statementstmt 98.0% 49 / 50 Branchbran 81.2% 13 / 16 Conditioncond 66.6% 4 / 6 MC/DCmcdc 25.0% 1 / 4 Subroutinesub 80.0% 4 / 5 Podpod 75.0% 3 / 4 totaltotal 87.0% 74 / 85 CC 9 SCAR 19.1
CC
9
Cov
92%
encode_entities
9.2
Version
2.0
BEGIN
1.0
CRAP 6.7
« blib/lib/HTML/Parser.pm ↑ Summary blib/lib/HTML/LinkExtor.pm »
1 package HTML::Entities;
2  
3 =encoding utf8
4  
5 =head1 NAME
6  
7 HTML::Entities - Encode or decode strings with HTML entities
8  
9 =head1 SYNOPSIS
10  
11 use HTML::Entities;
12  
13 $a = "Våre norske tegn bør &#230res";
14 decode_entities($a);
15 encode_entities($a, "\200-\377");
16  
17 For example, this:
18  
19 $input = "vis-à-vis Beyoncé's naïve\npapier-mâché résumé";
20 print encode_entities($input), "\n"
21  
22 Prints this out:
23  
24 vis-à-vis Beyoncé's naïve
25 papier-mâché résumé
26  
27 =head1 DESCRIPTION
28  
29 This module deals with encoding and decoding of strings with HTML
30 character entities. The module provides the following functions:
31  
32 =over 4
33  
34 =item decode_entities( $string, ... )
35  
36 This routine replaces HTML entities found in the $string with the
37 corresponding Unicode character. Unrecognized entities are left alone.
38  
39 If multiple strings are provided as argument they are each decoded
40 separately and the same number of strings are returned.
41  
42 If called in void context the arguments are decoded in-place.
43  
44 This routine is exported by default.
45  
46 =item _decode_entities( $string, \%entity2char )
47  
48 =item _decode_entities( $string, \%entity2char, $expand_prefix )
49  
50 This will in-place replace HTML entities in $string. The %entity2char
51 hash must be provided. Named entities not found in the %entity2char
52 hash are left alone. Numeric entities are expanded unless their value
53 overflow.
54  
55 The keys in %entity2char are the entity names to be expanded and their
56 values are what they should expand into. The values do not have to be
57 single character strings. If a key has ";" as suffix,
58 then occurrences in $string are only expanded if properly terminated
59 with ";". Entities without ";" will be expanded regardless of how
60 they are terminated for compatibility with how common browsers treat
61 entities in the Latin-1 range.
62  
63 If $expand_prefix is TRUE then entities without trailing ";" in
64 %entity2char will even be expanded as a prefix of a longer
65 unrecognized name. The longest matching name in %entity2char will be
66 used. This is mainly present for compatibility with an MSIE
67 misfeature.
68  
69 $string = "foo&nbspbar";
70 _decode_entities($string, { nb => "@", nbsp => "\xA0" }, 1);
71 print $string; # will print "foo bar"
72  
73 An entity whose value is the string being decoded expands to the value
74 that string had when the call began. This routine does not scan
75 replacement text again, so any entities inside it are left alone.
76  
77 Looking up a value can run Perl code, through a tied hash or an
78 overloaded object. If that code modifies the string being decoded,
79 this routine dies.
80  
81 This routine is exported by default.
82  
83 =item encode_entities( $string )
84  
85 =item encode_entities( $string, $unsafe_chars )
86  
87 This routine replaces unsafe characters in $string with their entity
88 representation. A second argument can be given to specify which characters to
89 consider unsafe. The unsafe characters is specified using the regular
90 expression character class syntax (what you find within brackets in regular
91 expressions).
92  
93 The default set of characters to encode are control chars, high-bit chars, and
94 the C<< < >>, C<< & >>, C<< > >>, C<< ' >> and C<< " >> characters. But this,
95 for example, would encode I<just> the C<< < >>, C<< & >>, C<< > >>, and C<< "
96 >> characters:
97  
98 $encoded = encode_entities($input, '<>&"');
99  
100 and this would only encode non-plain ASCII:
101  
102 $encoded = encode_entities($input, '^\n\x20-\x25\x27-\x7e');
103  
104 This routine is exported by default.
105  
106 =item encode_entities_numeric( $string )
107  
108 =item encode_entities_numeric( $string, $unsafe_chars )
109  
110 This routine works just like encode_entities, except that the replacement
111 entities are always C<&#xI<hexnum>;> and never C<&I<entname>;>. For
112 example, C<encode_entities("r\xF4le")> returns "r&ocirc;le", but
113 C<encode_entities_numeric("r\xF4le")> returns "r&#xF4;le".
114  
115 This routine is I<not> exported by default. But you can always
116 export it with C<use HTML::Entities qw(encode_entities_numeric);>
117 or even C<use HTML::Entities qw(:DEFAULT encode_entities_numeric);>
118  
119 =back
120  
121 All these routines modify the string passed as the first argument, if
122 called in a void context. In scalar and array contexts, the encoded or
123 decoded string is returned (without changing the input string).
124  
125 If you prefer not to import these routines into your namespace, you can
126 call them as:
127  
128 use HTML::Entities ();
129 $decoded = HTML::Entities::decode($a);
130 $encoded = HTML::Entities::encode($a);
131 $encoded = HTML::Entities::encode_numeric($a);
132  
133 The module can also export the %char2entity and the %entity2char
134 hashes, which contain the mapping from all characters to the
135 corresponding entities (and vice versa, respectively).
136  
137 =head1 COPYRIGHT
138  
139 Copyright 1995-2006 Gisle Aas. All rights reserved.
140  
141 This library is free software; you can redistribute it and/or
142 modify it under the same terms as Perl itself.
143  
144 =cut
145  
146 49 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
147 49 our $VERSION = '3.87';
148 49 our (%entity2char, %char2entity);
149  
150 49 require 5.008;
151 49 require Exporter;
152 49 our @ISA = qw(Exporter);
153  
154 49 our @EXPORT = qw(encode_entities decode_entities _decode_entities);
155 49 our @EXPORT_OK = qw(%entity2char %char2entity encode_entities_numeric);
156  
157 0 ▶sub Version { $VERSION; }
Subroutine Version: not called CC=1 SCAR=6.9
Pod documented
158  
159 49 require HTML::Parser; # for fast XS implemented decode_entities
160  
161  
162 49 %entity2char = (
163 # Some normal chars that have special meaning in SGML context
164 amp => '&', # ampersand
165 'gt' => '>', # greater than
166 'lt' => '<', # less than
167 quot => '"', # double quote
168 apos => "'", # single quote
169  
170 # PUBLIC ISO 8879-1986//ENTITIES Added Latin 1//EN//HTML
171 AElig => chr(198), # capital AE diphthong (ligature)
172 Aacute => chr(193), # capital A, acute accent
173 Acirc => chr(194), # capital A, circumflex accent
174 Agrave => chr(192), # capital A, grave accent
175 Aring => chr(197), # capital A, ring
176 Atilde => chr(195), # capital A, tilde
177 Auml => chr(196), # capital A, dieresis or umlaut mark
178 Ccedil => chr(199), # capital C, cedilla
179 ETH => chr(208), # capital Eth, Icelandic
180 Eacute => chr(201), # capital E, acute accent
181 Ecirc => chr(202), # capital E, circumflex accent
182 Egrave => chr(200), # capital E, grave accent
183 Euml => chr(203), # capital E, dieresis or umlaut mark
184 Iacute => chr(205), # capital I, acute accent
185 Icirc => chr(206), # capital I, circumflex accent
186 Igrave => chr(204), # capital I, grave accent
187 Iuml => chr(207), # capital I, dieresis or umlaut mark
188 Ntilde => chr(209), # capital N, tilde
189 Oacute => chr(211), # capital O, acute accent
190 Ocirc => chr(212), # capital O, circumflex accent
191 Ograve => chr(210), # capital O, grave accent
192 Oslash => chr(216), # capital O, slash
193 Otilde => chr(213), # capital O, tilde
194 Ouml => chr(214), # capital O, dieresis or umlaut mark
195 THORN => chr(222), # capital THORN, Icelandic
196 Uacute => chr(218), # capital U, acute accent
197 Ucirc => chr(219), # capital U, circumflex accent
198 Ugrave => chr(217), # capital U, grave accent
199 Uuml => chr(220), # capital U, dieresis or umlaut mark
200 Yacute => chr(221), # capital Y, acute accent
201 aacute => chr(225), # small a, acute accent
202 acirc => chr(226), # small a, circumflex accent
203 aelig => chr(230), # small ae diphthong (ligature)
204 agrave => chr(224), # small a, grave accent
205 aring => chr(229), # small a, ring
206 atilde => chr(227), # small a, tilde
207 auml => chr(228), # small a, dieresis or umlaut mark
208 ccedil => chr(231), # small c, cedilla
209 eacute => chr(233), # small e, acute accent
210 ecirc => chr(234), # small e, circumflex accent
211 egrave => chr(232), # small e, grave accent
212 eth => chr(240), # small eth, Icelandic
213 euml => chr(235), # small e, dieresis or umlaut mark
214 iacute => chr(237), # small i, acute accent
215 icirc => chr(238), # small i, circumflex accent
216 igrave => chr(236), # small i, grave accent
217 iuml => chr(239), # small i, dieresis or umlaut mark
218 ntilde => chr(241), # small n, tilde
219 oacute => chr(243), # small o, acute accent
220 ocirc => chr(244), # small o, circumflex accent
221 ograve => chr(242), # small o, grave accent
222 oslash => chr(248), # small o, slash
223 otilde => chr(245), # small o, tilde
224 ouml => chr(246), # small o, dieresis or umlaut mark
225 szlig => chr(223), # small sharp s, German (sz ligature)
226 thorn => chr(254), # small thorn, Icelandic
227 uacute => chr(250), # small u, acute accent
228 ucirc => chr(251), # small u, circumflex accent
229 ugrave => chr(249), # small u, grave accent
230 uuml => chr(252), # small u, dieresis or umlaut mark
231 yacute => chr(253), # small y, acute accent
232 yuml => chr(255), # small y, dieresis or umlaut mark
233  
234 # Some extra Latin 1 chars that are listed in the HTML3.2 draft (21-May-96)
235 copy => chr(169), # copyright sign
236 reg => chr(174), # registered sign
237 nbsp => chr(160), # non breaking space
238  
239 # Additional ISO-8859/1 entities listed in rfc1866 (section 14)
240 iexcl => chr(161),
241 cent => chr(162),
242 pound => chr(163),
243 curren => chr(164),
244 yen => chr(165),
245 brvbar => chr(166),
246 sect => chr(167),
247 uml => chr(168),
248 ordf => chr(170),
249 laquo => chr(171),
250 'not' => chr(172), # not is a keyword in perl
251 shy => chr(173),
252 macr => chr(175),
253 deg => chr(176),
254 plusmn => chr(177),
255 sup1 => chr(185),
256 sup2 => chr(178),
257 sup3 => chr(179),
258 acute => chr(180),
259 micro => chr(181),
260 para => chr(182),
261 middot => chr(183),
262 cedil => chr(184),
263 ordm => chr(186),
264 raquo => chr(187),
265 frac14 => chr(188),
266 frac12 => chr(189),
267 frac34 => chr(190),
268 iquest => chr(191),
269 'times' => chr(215), # times is a keyword in perl
270 divide => chr(247),
271  
272 'OElig;' => chr(338),
273 'oelig;' => chr(339),
274 'Scaron;' => chr(352),
275 'scaron;' => chr(353),
276 'Yuml;' => chr(376),
277 'fnof;' => chr(402),
278 'circ;' => chr(710),
279 'tilde;' => chr(732),
280 'Alpha;' => chr(913),
281 'Beta;' => chr(914),
282 'Gamma;' => chr(915),
283 'Delta;' => chr(916),
284 'Epsilon;' => chr(917),
285 'Zeta;' => chr(918),
286 'Eta;' => chr(919),
287 'Theta;' => chr(920),
288 'Iota;' => chr(921),
289 'Kappa;' => chr(922),
290 'Lambda;' => chr(923),
291 'Mu;' => chr(924),
292 'Nu;' => chr(925),
293 'Xi;' => chr(926),
294 'Omicron;' => chr(927),
295 'Pi;' => chr(928),
296 'Rho;' => chr(929),
297 'Sigma;' => chr(931),
298 'Tau;' => chr(932),
299 'Upsilon;' => chr(933),
300 'Phi;' => chr(934),
301 'Chi;' => chr(935),
302 'Psi;' => chr(936),
303 'Omega;' => chr(937),
304 'alpha;' => chr(945),
305 'beta;' => chr(946),
306 'gamma;' => chr(947),
307 'delta;' => chr(948),
308 'epsilon;' => chr(949),
309 'zeta;' => chr(950),
310 'eta;' => chr(951),
311 'theta;' => chr(952),
312 'iota;' => chr(953),
313 'kappa;' => chr(954),
314 'lambda;' => chr(955),
315 'mu;' => chr(956),
316 'nu;' => chr(957),
317 'xi;' => chr(958),
318 'omicron;' => chr(959),
319 'pi;' => chr(960),
320 'rho;' => chr(961),
321 'sigmaf;' => chr(962),
322 'sigma;' => chr(963),
323 'tau;' => chr(964),
324 'upsilon;' => chr(965),
325 'phi;' => chr(966),
326 'chi;' => chr(967),
327 'psi;' => chr(968),
328 'omega;' => chr(969),
329 'thetasym;' => chr(977),
330 'upsih;' => chr(978),
331 'piv;' => chr(982),
332 'ensp;' => chr(8194),
333 'emsp;' => chr(8195),
334 'thinsp;' => chr(8201),
335 'zwnj;' => chr(8204),
336 'zwj;' => chr(8205),
337 'lrm;' => chr(8206),
338 'rlm;' => chr(8207),
339 'ndash;' => chr(8211),
340 'mdash;' => chr(8212),
341 'lsquo;' => chr(8216),
342 'rsquo;' => chr(8217),
343 'sbquo;' => chr(8218),
344 'ldquo;' => chr(8220),
345 'rdquo;' => chr(8221),
346 'bdquo;' => chr(8222),
347 'dagger;' => chr(8224),
348 'Dagger;' => chr(8225),
349 'bull;' => chr(8226),
350 'hellip;' => chr(8230),
351 'permil;' => chr(8240),
352 'prime;' => chr(8242),
353 'Prime;' => chr(8243),
354 'lsaquo;' => chr(8249),
355 'rsaquo;' => chr(8250),
356 'oline;' => chr(8254),
357 'frasl;' => chr(8260),
358 'euro;' => chr(8364),
359 'image;' => chr(8465),
360 'weierp;' => chr(8472),
361 'real;' => chr(8476),
362 'trade;' => chr(8482),
363 'alefsym;' => chr(8501),
364 'larr;' => chr(8592),
365 'uarr;' => chr(8593),
366 'rarr;' => chr(8594),
367 'darr;' => chr(8595),
368 'harr;' => chr(8596),
369 'crarr;' => chr(8629),
370 'lArr;' => chr(8656),
371 'uArr;' => chr(8657),
372 'rArr;' => chr(8658),
373 'dArr;' => chr(8659),
374 'hArr;' => chr(8660),
375 'forall;' => chr(8704),
376 'part;' => chr(8706),
377 'exist;' => chr(8707),
378 'empty;' => chr(8709),
379 'nabla;' => chr(8711),
380 'isin;' => chr(8712),
381 'notin;' => chr(8713),
382 'ni;' => chr(8715),
383 'prod;' => chr(8719),
384 'sum;' => chr(8721),
385 'minus;' => chr(8722),
386 'lowast;' => chr(8727),
387 'radic;' => chr(8730),
388 'prop;' => chr(8733),
389 'infin;' => chr(8734),
390 'ang;' => chr(8736),
391 'and;' => chr(8743),
392 'or;' => chr(8744),
393 'cap;' => chr(8745),
394 'cup;' => chr(8746),
395 'int;' => chr(8747),
396 'there4;' => chr(8756),
397 'sim;' => chr(8764),
398 'cong;' => chr(8773),
399 'asymp;' => chr(8776),
400 'ne;' => chr(8800),
401 'equiv;' => chr(8801),
402 'le;' => chr(8804),
403 'ge;' => chr(8805),
404 'sub;' => chr(8834),
405 'sup;' => chr(8835),
406 'nsub;' => chr(8836),
407 'sube;' => chr(8838),
408 'supe;' => chr(8839),
409 'oplus;' => chr(8853),
410 'otimes;' => chr(8855),
411 'perp;' => chr(8869),
412 'sdot;' => chr(8901),
413 'lceil;' => chr(8968),
414 'rceil;' => chr(8969),
415 'lfloor;' => chr(8970),
416 'rfloor;' => chr(8971),
417 'lang;' => chr(9001),
418 'rang;' => chr(9002),
419 'loz;' => chr(9674),
420 'spades;' => chr(9824),
421 'clubs;' => chr(9827),
422 'hearts;' => chr(9829),
423 'diams;' => chr(9830),
424 );
425  
426  
427 # Make the opposite mapping
428 49 ▶while (my($entity, $char) = each(%entity2char)) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %HTML::Entities::entity2char) 12397 49 12446
429 12397 $entity =~ s/;\z//;
430 12397 $char2entity{$char} = "&$entity;";
431 }
432 49 delete $char2entity{"'"}; # only one-way decoding
433  
434 # Fill in missing entities
435 49 for (0 .. 255) {
436 12544 ▶ next if exists $char2entity{chr($_)};
Branch: 1 branch
BranchTrueFalseTotal
if exists $HTML::Entities::char2entity{chr $_} 4900 7644 12544
437 7644 $char2entity{chr($_)} = "&#$_;";
438 }
439  
440 49 my %subst; # compiled encoding regexps
441  
442 sub encode_entities
443 28 ▶{
Subroutine encode_entities: called CC=9 SCAR=22.2
Pod documented
444 28 ▶ return undef unless defined $_[0];
Branch: 1 branch
BranchTrueFalseTotal
unless defined $_[0] 0 28 28
445 28 my $ref;
446 28 ▶ if (defined wantarray) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined wantarray) { } 25 3 28
447 25 my $x = $_[0];
448 25 $ref = \$x; # copy
449 } else {
450 3 $ref = \$_[0]; # modify in-place
451 }
452 28 my $regex;
453 28 ▶ if (defined $_[1] and length $_[1]) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $_[1] and length $_[1]) { } 17 11 28
Condition66%2/3
defined $_[1] and length $_[1]
!ll&&!rl&&r
11017
MC/DC50%1/2
defined $_[1] and length $_[1]
defined $_[1] length $_[1]
Truth table66%2/3
A and B
A= defined $_[1]B= length $_[1]
ABresult
0X0
100
111
454 17 $regex = $subst{$_[1]};
455 17 ▶ unless (defined $regex) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $regex) 17 0 17
456 17 my $chars = $_[1];
457  
458 # keep existing escapes, but also escape any unescaped special character:
459 # [ (technically unnecessary but included for symmetry with ])
460 # ] (end of character class)
461 # \ (escape character)
462 17 $chars =~ s{
463 # capture group 1: things to skip and keep
464 (
465 # any escaped character
466 \\.
467 |
468 # either an actual POSIX character class or anything
469 # similar enough to trigger a regex syntax error
470 \[: \^? [[:lower:][:digit:]]{3,} :\]
471 )
472 |
473 # capture group 2: things to be escaped
474 (
475 [\[\]\\]
476 )
477 }{
478 18 ▶ defined $1 ? $1 : '\\' . $2
Branch: 1 branch
BranchTrueFalseTotal
defined $1 ? : 12 6 18
479 }xseg;
480  
481 17 $regex = eval { qr/([$chars])/ };
482 17 ▶ die( $@ . " while trying to turn range: \"$_[1]\"\n "
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 17 17
483 . "into code: /([$chars])/\n "
484 ) if $@;
485 17 $subst{$_[1]} = $regex;
486 }
487 } else {
488 # Encode control chars, high bit chars and '<', '&', '>', ''' and '"'
489 11 $regex = qr/([^\n\r\t !\#\$%\(-;=?-~])/;
490 }
491 28 ▶ $$ref =~ s/$regex/$char2entity{$1} || num_entity($1)/eg;
Condition66%2/3
$HTML::Entities::char2entity{$1} || num_entity($1)
l!l&&r!l&&!r
225250
MC/DC0%0/2
$HTML::Entities::char2entity{$1} || num_entity($1)
$HTML::Entities::char2entity{$1} num_entity($1)
Truth table66%2/3
A || B
A= $HTML::Entities::char2entity{$1}B= num_entity($1)
ABresult
1X1
011
000
492 28 $$ref;
493 }
494  
495 2 ▶sub encode_entities_numeric {
Subroutine encode_entities_numeric: called CC=1 SCAR=0.0
Pod documented
496 2 local %char2entity;
497 2 return &encode_entities; # a goto &encode_entities wouldn't work
498 }
499  
500  
501 25 ▶sub num_entity {
Subroutine num_entity: called CC=1 SCAR=0.0
Pod undocumented
502 25 sprintf "&#x%X;", ord($_[0]);
503 }
504  
505 # Set up aliases
506 49 *encode = \&encode_entities;
507 49 *encode_numeric = \&encode_entities_numeric;
508 49 *encode_numerically = \&encode_entities_numeric;
509 49 *decode = \&decode_entities;
510  
511 49 1;
« blib/lib/HTML/Parser.pm ↑ Summary blib/lib/HTML/LinkExtor.pm »