Commit | Line | Data |
e1b4b35c |
1 | package HTML::String; |
2 | |
3 | use strictures 1; |
4 | use HTML::String::Value; |
5 | use Exporter 'import'; |
6 | |
fc59799f |
7 | our $VERSION = '1.000002'; # 1.0.2 |
a38082d4 |
8 | |
9 | $VERSION = eval $VERSION; |
10 | |
e1b4b35c |
11 | our @EXPORT = qw(html); |
12 | |
13 | sub html { |
14 | HTML::String::Value->new($_[0]); |
15 | } |
16 | |
17 | 1; |
d86bdf82 |
18 | |
19 | __END__ |
20 | |
21 | =head1 NAME |
22 | |
23 | HTML::String - mark strings as HTML to get auto-escaping |
24 | |
25 | =head1 SYNOPSIS |
26 | |
27 | use HTML::String; |
28 | |
29 | my $not_html = 'Hello, Bob & Jake'; |
30 | |
31 | my $html = html('<h1>').$not_html.html('</h1>'); |
32 | |
882026d2 |
33 | print html($html); # <h1>Hello, Bob & Jake</h1> |
d86bdf82 |
34 | |
35 | or, alternatively, |
36 | |
37 | use HTML::String::Overload; |
38 | |
39 | my $not_html = 'Hello, Bob & Jake'; |
40 | |
41 | my $html = do { |
42 | use HTML::String::Overload; |
43 | "<h1>${not_html}</h1>"; |
44 | } |
45 | |
882026d2 |
46 | print html($html); # <h1>Hello, Bob & Jake</h1> |
d86bdf82 |
47 | |
48 | (but see the L<HTML::String::Overload> documentation for details and caveats). |
49 | |
50 | See also L<HTML::String::TT> for L<Template Toolkit|Template> integration. |
51 | |
52 | =head1 DESCRIPTION |
53 | |
54 | Tired of trying to remember which strings in your program need HTML escaping? |
55 | |
56 | Working on something small enough to not need a templating engine - or code |
57 | heavy enough to be better done with strings - but wanting to be careful about |
58 | user supplied data? |
59 | |
60 | Yeah, me too, sometimes. So I wrote L<HTML::String>. |
61 | |
62 | The idea here is to have pervasive HTML escaping that fails closed - i.e. |
63 | escapes everything that it isn't explicitly told not to. Since in the era |
64 | of XSS (cross site scripting) attacks it's a matter of security as well as |
65 | of not serving mangled markup, I've preferred to err on the side of |
66 | inconvenience in places in order to make it as hard as possible to screw up. |
67 | |
68 | We export a single subroutine, L</html>, whose sole purpose in life |
69 | is to construct an L<HTML::String::Value> object from a string, which then |
70 | obsessively refuses to be concatenated to anything else without escaping it |
71 | unless you asked for that not to happen by marking the other thing as HTML |
72 | too. |
73 | |
74 | So |
75 | |
76 | html($thing).$other_thing |
77 | |
78 | will return an object where C<$thing> won't be escaped, but C<$other_thing> |
79 | will. Keeping concatenating stuff is fine; internally it's an array of parts. |
80 | |
81 | Because html() will happily take something that's already wrapped into a |
82 | value object, when we print it out we can do: |
83 | |
84 | print html($final_result); |
85 | |
86 | safe in the knowledge that if we got passed a value object that won't break |
87 | anything, but if by some combination of alarums, excursions and murphy |
88 | strikes we still have just a plain string by that point, the plain string |
89 | will still get escaped on the way out. |
90 | |
91 | If you've got distinct blocks of code where you're assembling HTML, instead |
92 | of using L</html> a lot you can say "all strings in this block are HTML |
93 | so please mark them all to not be escaped" using L<HTML::String::Overload> - |
94 | |
95 | my $string = 'This is a "normal" string'; |
96 | |
97 | my $html; |
98 | |
99 | { |
100 | use HTML::String::Overload; # valid until the end of the block |
101 | |
102 | $html = '<foo>'.$string.'</foo>'; # the two strings are html()ified |
103 | } |
104 | |
105 | print $html; # prints <foo>This is a "normal" string</foo> |
106 | |
107 | Note however that due to a perl bug, you can't use backslash escapes in |
108 | a string and have it still get marked as an HTML value, so instead of |
109 | |
110 | "<h1>\n<div>" |
111 | |
112 | you need to write |
113 | |
114 | "<h1>"."\n"."</div>" |
115 | |
116 | at least as far as 5.16.1, which is current as I write this. See |
117 | L<HTML::String::Overload> for more details. |
118 | |
119 | For integration with L<Template Toolkit|Template>, see L<HTML::String::TT>. |
120 | |
fc076557 |
121 | =head1 CHARACTERS THAT WILL BE ESCAPED |
122 | |
123 | HTML::String concerns itself with characters that have special meaning in |
124 | HTML. Those which begin and end tags (< and >), those which begin an entity |
125 | (&) and those which delimit attribute values (" and '). It outputs them |
126 | in a fashion compatible with HTML 4 and newer and all versions of XHTML |
127 | (assuming support for named entities in the parser). There are no known |
128 | incompatibilities with browsers. |
129 | |
130 | HTML::String does not concern itself with other characters, it is assumed |
131 | that HTML documents will be marked with a suitable character encoding via |
132 | a Content-Type HTTP header and/or a meta element. |
133 | |
d86bdf82 |
134 | =head1 EXPORTS |
135 | |
136 | =head2 html |
137 | |
138 | my $html = html($do_not_escape_this); |
139 | |
140 | Returns an L<HTML::String::Value> object containing a single string part |
141 | marked not to be escaped. |
142 | |
143 | If you need to do something clever such as specifying packages for which |
144 | to ignore escaping requests, see the L<HTML::String::Value> documentation |
145 | and write your own subroutine - this one is as simple as |
146 | |
147 | sub html { |
148 | return HTML::String::Value->new($_[0]); |
149 | } |
150 | |
151 | so providing configuration options would likely be more complicated and |
152 | confusing than just writing the code. |
153 | |
154 | =head1 AUTHOR |
155 | |
156 | mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk> |
157 | |
158 | =head1 CONTRIBUTORS |
159 | |
fc076557 |
160 | dorward - David Dorward (cpan:DORWARD) <david@dorward.me.uk> |
d86bdf82 |
161 | |
162 | =head1 COPYRIGHT |
163 | |
164 | Copyright (c) 2012 the HTML::String L</AUTHOR> and L</CONTRIBUTORS> |
165 | as listed above. |
166 | |
167 | =head1 LICENSE |
168 | |
169 | This library is free software and may be distributed under the same terms |
170 | as perl itself. |
171 | |
172 | =cut |