1 package PLP::Functions;
7 our @EXPORT = qw/HiddenFields Entity DecodeURI EncodeURI Entity include PLP_END
8 AddCookie ReadFile WriteFile AutoURL Counter Include exit/;
16 eval 'package PLP::Script; ' . PLP::source($PLP::file, 0, join ' ', (caller)[2,1]);
18 PLP::Functions::exit() if $@ =~ /\cS\cT\cO\cP/;
32 push @PLP::END, shift;
35 sub HiddenFields ($@) {
40 print qq{<input type=hidden name="$_" value="$hash->{$_}">}
41 unless exists $saves{$_};
48 if (defined wantarray) {
61 s/\t/ /g;
64 # if ($@){ return defined wantarray ? @_ : undef }
66 return defined wantarray ? (wantarray ? @$ref : "@$ref") : undef;
70 # Browsers do s/ /+/ - I don't care about RFC's, but I do care about real-life
77 $dec =~ s/%([0-9A-Fa-f][0-9A-Fa-f])/chr hex $1/ge;
78 if (defined wantarray) {
82 # return undef if $@; # ;DecodeURI("foo");
85 return defined wantarray ? (wantarray ? @r : "@r") : undef;
95 ([^\/?:@\$,A-Za-z0-9\-_.!~*\'()])
97 sprintf("%%%02x", ord($1))
99 if (defined wantarray) {
103 # return undef if $@; # ;EncodeURI("foo");
106 return defined wantarray ? (wantarray ? @r : "@r") : undef;
110 if ($PLP::Script::header{'Set-Cookie'}) {
111 $PLP::Script::header{'Set-Cookie'} .= "\nSet-Cookie: $_[0]";
113 $PLP::Script::header{'Set-Cookie'} = $_[0];
119 open (my $fh, '<', $_[0]) or do {
120 PLP::error("Cannot open $_[0] for reading ($!)", 1);
123 my $r = readline $fh;
129 open (my $fh, '>', $_[0]) or do {
130 PLP::error("Cannot open $_[0] for writing ($!)", 1);
134 print $fh $_[1] or do {
135 PLP::error("Cannot write to $_[0] ($!)");
139 PLP::error("Cannot close $_[0] ($!)");
148 open $fh, '+<', $_[0] or
149 open $fh, '>', $_[0] or return undef;
155 print $fh ++$counter or return undef;
156 close $fh or return undef;
161 # This sub assumes your string does not match /(["<>])\cC\1/
163 if (defined wantarray){
164 $ref = \(my $copy = $_[0]);
169 $$ref =~ s/"/"\cC"/g; # Single characters are easier to match :)
170 $$ref =~ s/>/>\cC>/g; # so we can just use a character class []
171 $$ref =~ s/</<\cC</g;
173 # Now this is a big, ugly regex! But hey - it works :)
174 $$ref =~ s{((\w+://|www\.|WWW\.)[a-zA-Z0-9\.\@:-]+[^\"\'>< \r\t\n]*)}{
177 s/// if (my $trailing) = /([\.,!\?\(\)\[\]]+$)/;
178 s/&(?!\x23?\w+;)/&/g;
180 my $href = ($scheme =~ /www\./i ? "http://$_" : $_);
181 qq{<a href="$href" target="_blank">$_</a>$trailing};
184 $$ref =~ s/"\cC"/"/g;
185 $$ref =~ s/>\cC>/>/g;
186 $$ref =~ s/<\cC</</g;
188 if ($@){ return defined wantarray ? @_ : undef }
189 return defined wantarray ? $$ref : undef;
196 PLP::Functions - Functions that are available in PLP documents
200 The functions are exported into the PLP::Script package that is used by PLP documents. Although uppercased letters are unusual in Perl, they were chosen to stand out.
202 Most of these functions are context-hybird. Before using them, one should know about contexts in Perl. The three major contexts are: B<void>, B<scalar> and B<list> context. You'll find more about context in L<perlfunc>.
204 Some context examples:
206 print foo(); # foo is in list context (print LIST)
207 foo(); # foo is in void context
208 $bar = foo(); # foo is in scalar context
209 @bar = foo(); # foo is in list context
210 length foo(); # foo is in scalar context (length EXPR)
216 =item Include FILENAME
218 Executes another PLP file, that will be parsed (i.e. code must be in C<< <: :> >>). As with Perl's C<do>, the file is evaluated in its own lexical file scope, so lexical variables (C<my> variables) are not shared. PLP's C<< <(filename)> >> includes at compile-time, is faster and is doesn't create a lexical scope (it shares lexical variables).
220 Include can be used recursively, and there is no depth limit:
222 <!-- This is crash.plp -->
225 # This example will loop forever,
226 # and dies with an out of memory error.
227 # Do not try this at home.
230 =item include FILENAME
232 An alias for C<Include>.
236 Adds a piece of code that is executed when at the end of the PLP document. This is useful when creating a template file:
238 <html><body> <!-- this is template.plp -->
243 <(template.plp)> <!-- this is index.plp -->
246 You should use this function instead of Perl's built-in C<END> blocks, because those do not work properly with mod_perl.
250 Replaces HTML syntax characters by HTML entities, so they can be displayed literally. You should always use this on user input (or database output), to avoid cross-site-scripting vurnerabilities. This function does not do everything the L<HTML::Entity> does.
252 In void context, B<changes> the values of the given variables. In other contexts, returns the changed versions.
254 <: print Entity($user_input); :>
256 Be warned that this function also HTMLizes consecutive whitespace and newlines (using and <br> respectively).
257 For simple escaping, use L<XML::Quote>. To escape high-bit characters as well, use L<HTML::Entities>.
261 Encodes URI strings according to RFC 3986. All disallowed characters are replaced by their %-encoded values.
263 In void context, B<changes> the values of the given variables. In other contexts, returns the changed versions.
265 <a href="/foo.plp?name=<:= EncodeURI($name) :>">Link</a>
267 Note that the following reserved characters are I<not> percent-encoded, even though they may have a special meaning in URIs:
271 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> instead.
275 Decodes %-encoded strings. Unlike L<URI::Escape>, it also translates + characters to spaces (as browsers use those).
277 In void context, B<changes> the values of the given variables. In other contexts, returns the changed versions.
279 =item ReadFile FILENAME
281 Returns the contents of FILENAME in one large string. Returns undef on failure.
283 =item WriteFile FILENAME, STRING
285 Writes STRING to FILENAME (overwrites FILENAME if it already exists). Returns true on success, false on failure.
287 =item Counter FILENAME
289 Increases the contents of FILENAME by one and returns the new value. Returns undef on failure. Fails silently.
291 You are visitor number <:= Counter('counter.txt') :>.
295 Replaces URLs (actually, replace things that look like URLs) by links.
297 In void context, B<changes> the value of the given variable. In other contexts, returns the changed version.
299 <: print AutoURL(Entity($user_input)); :>
301 =item AddCookie STRING
303 Adds a Set-Cookie header. STRING must be a valid Set-Cookie header value.
309 Juerd Waalboer <juerd@cpan.org>
311 Current maintainer: Mischa POSLAWSKY <shiar@cpan.org>