+
+=head1 NAME
+
+PLP::Functions - Functions that are available in PLP documents
+
+=head1 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: B<void>, B<scalar> and B<list> context. You'll find more about context in L<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)
+
+=head2 The functions
+
+=over 10
+
+=item Include FILENAME
+
+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).
+
+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.
+ :>
+
+=item include FILENAME
+
+An alias for C<Include>.
+
+=item 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 C<END> blocks, because those do not work properly with mod_perl.
+
+=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.
+
+In void context, B<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 L<XML::Quote|XML::Quote>.
+To escape high-bit characters as well, use L<HTML::Entities|HTML::Entities>.
+
+=item EncodeURI LIST
+
+Encodes URI strings according to RFC 3986. All disallowed characters are replaced by their %-encoded values.
+
+In void context, B<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 I<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 L<URI::Escape|URI::Escape> instead.
+
+=item DecodeURI LIST
+
+Decodes %-encoded strings. Unlike L<URI::Escape|URI::Escape>,
+it also translates + characters to spaces (as browsers use those).
+
+In void context, B<changes> the values of the given variables. In other contexts, returns the changed versions.
+
+=item ReadFile FILENAME
+
+Returns the contents of FILENAME in one large string. Returns undef on failure.
+
+=item WriteFile FILENAME, STRING
+
+Writes STRING to FILENAME (overwrites FILENAME if it already exists). Returns true on success, false on failure.
+
+=item 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') :>.
+
+=item AutoURL STRING
+
+Replaces URLs (actually, replace things that look like URLs) by links.
+
+In void context, B<changes> the value of the given variable. In other contexts, returns the changed version.
+
+ <: print AutoURL(Entity($user_input)); :>
+
+=item AddCookie STRING
+
+Adds a Set-Cookie header. STRING must be a valid Set-Cookie header value.
+
+=back
+
+=head1 AUTHOR
+
+Juerd Waalboer <juerd@cpan.org>
+
+Current maintainer: Mischa POSLAWSKY <shiar@cpan.org>
+
+=cut
+