NAME
PLP::Functions - Functions that are available in PLP documents
DESCRIPTION
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.
Most of these functions are context-hybird. Before using them, one should know about contexts in Perl. The three major contexts are: void, scalar and list context. You'll find more about context in perlfunc.
Some context examples:
print foo(); # foo is in list context (print LIST)
foo(); # foo is in void context
$bar = foo(); # foo is in scalar context
@bar = foo(); # foo is in list context
length foo(); # foo is in scalar context (length EXPR)
The functions
- Include FILENAME
-
Executes another PLP file, that will be parsed (i.e. code must be in
<: :>
). As with Perl'sdo
, the file is evaluated in its own lexical file scope, so lexical variables (my
variables) are not shared. PLP's<(filename)>
includes at compile-time, is faster and is doesn't create a lexical scope (it shares lexical variables).Include can be used recursively, and there is no depth limit:
<!-- This is crash.plp --> <: include 'crash.plp'; # This example will loop forever, # and dies with an out of memory error. # Do not try this at home. :>
- include FILENAME
-
An alias for
Include
. - PLP_END BLOCK
-
Adds a piece of code that is executed when at the end of the PLP document. This is useful when creating a template file:
<html><body> <!-- this is template.plp --> <: PLP_END { :> </body></html> <: } :> <(template.plp)> <!-- this is index.plp --> Hello, world!
You should use this function instead of Perl's built-in
END
blocks, because those do not work properly with mod_perl. - 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.
In void context, changes the values of the given variables. In other contexts, returns the changed versions.
<: print Entity($user_input); :>
Be warned that this function also HTMLizes consecutive whitespace and newlines (using and <br> respectively). For simple escaping, use XML::Quote. To escape high-bit characters as well, use HTML::Entities.
- EncodeURI LIST
-
Encodes URI strings according to RFC 3986. All disallowed characters are replaced by their %-encoded values.
In void context, changes the values of the given variables. In other contexts, returns the changed versions.
<a href="/foo.plp?name=<:= EncodeURI($name) :>">Link</a>
Note that the following reserved characters are not percent-encoded, even though they may have a special meaning in URIs:
/ ? : @ $
This should be safe for escaping query values (as in the example above), but it may be a better idea to use URI::Escape instead.
- DecodeURI LIST
-
Decodes %-encoded strings. Unlike URI::Escape, it also translates + characters to spaces (as browsers use those).
In void context, changes the values of the given variables. In other contexts, returns the changed versions.
- ReadFile FILENAME
-
Returns the contents of FILENAME in one large string. Returns undef on failure.
- WriteFile FILENAME, STRING
-
Writes STRING to FILENAME (overwrites FILENAME if it already exists). Returns true on success, false on failure.
- Counter FILENAME
-
Increases the contents of FILENAME by one and returns the new value. Returns undef on failure. Fails silently.
You are visitor number <:= Counter('counter.txt') :>.
- AutoURL STRING
-
Replaces URLs (actually, replace things that look like URLs) by links.
In void context, changes the value of the given variable. In other contexts, returns the changed version.
<: print AutoURL(Entity($user_input)); :>
- AddCookie STRING
-
Adds a Set-Cookie header. STRING must be a valid Set-Cookie header value.
AUTHOR
Juerd Waalboer <juerd@cpan.org>
Current maintainer: Mischa POSLAWSKY <shiar@cpan.org>