X-Git-Url: http://git.shiar.net/perl/plp/.git/blobdiff_plain/3dd60490b2f12aeabc457292b87fe43772ce0304..958d374e19b67a3c68050a1dd29f7a10a44c74c9:/lib/PLP/Functions.pm

diff --git a/lib/PLP/Functions.pm b/lib/PLP/Functions.pm
index 8c3886f..2a4bb99 100644
--- a/lib/PLP/Functions.pm
+++ b/lib/PLP/Functions.pm
@@ -4,10 +4,12 @@ use strict;
 use warnings;
 
 use base 'Exporter';
+use Carp;
 use Fcntl qw(:flock);
 
-our $VERSION = '1.00';
+our $VERSION = '1.01';
 our @EXPORT = qw/Entity DecodeURI EncodeURI Include include PLP_END
+                 EscapeHTML
                  AddCookie ReadFile WriteFile AutoURL Counter exit/;
 
 sub Include ($) {
@@ -35,6 +37,19 @@ sub PLP_END (&) {
 	push @PLP::END, shift;
 }
 
+sub EscapeHTML {
+	@_ == 1 or croak "Unsupported parameters given to EscapeHTML";
+	unshift @_, shift if defined wantarray;  # dereference if not void
+	for ($_[0]) {
+		defined or next;
+		s/&/&/g;
+		s/"/"/g;
+		s/</&lt;/g;
+		s/>/&gt;/g;
+	}
+	return $_[0];
+}
+
 sub Entity (@) {
 	my $ref = defined wantarray ? [@_] : \@_;
 	for (@$ref) {
@@ -210,17 +225,36 @@ Adds a piece of code that is executed when at the end of the PLP document. This
 
 You should use this function instead of Perl's built-in C<END> blocks, because those do not work properly with mod_perl.
 
+=item EscapeHTML STRING
+
+Replaces HTML syntax characters by HTML entities, so the text can be output safely.
+You should always use this when displaying user input (or database output),
+to avoid cross-site-scripting vurnerabilities.
+
+In void context, B<changes> the value of the given variable.
+
+    <: EscapeHTML($user_input); print "<pre>$user_input</pre>"; :>
+
+In other contexts, returns the changed version.
+
+    <a href="<:= EscapeHTML($ENV{REQUEST_URI}) :>">
+
+Be warned that single quotes are not substituted, so always use double quotes for attributes.
+Also does not convert whitespace for formatted output; use Entity() for that.
+
+To escape high-bit characters as well, refer to L<HTML::Entities|HTML::Entities>.
+
 =item Entity LIST
 
-Replaces HTML syntax characters by HTML entities, so they can be displayed literally. You should always use this when displaying user input (or database output), to avoid cross-site-scripting vurnerabilities.
+Formats given arguments for literal display in HTML documents.
+Similar to EscapeHTML(), but also preserves newlines and consecutive spaces
+using corresponding C<< <br> >> and C<&nbsp;> respectively.
 
 In void context, B<changes> the values of the given variables. In other contexts, returns the changed versions.
 
-    <: print Entity($user_input); :>
+    <: print '<p>' . Entity($user_input) . '</p>'; :>
 
-Be warned that this function also HTMLizes consecutive whitespace and newlines (using &nbsp; and <br> respectively).
-For simple escaping, use L<XML::Quote|XML::Quote>.
-To escape high-bit characters as well, use L<HTML::Entities|HTML::Entities>.
+Inside attributes, always use EscapeHTML() instead.
 
 =item EncodeURI LIST
 
@@ -235,7 +269,7 @@ Note that the following reserved characters are I<not> percent-encoded, even tho
 	/ ? : @ $
 
 This should be safe for escaping query values (as in the example above),
-but it may be a better idea to use L<URI::Escape|URI::Escape> instead.
+but otherwise it may be a better idea to use L<URI::Escape|URI::Escape> instead.
 
 =item DecodeURI LIST