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