README

   1 NAME
   2     PLP - Perl in HTML pages
   3
   4 MODULE INSTALLATION
   5
   6     perl Makefile.PL
   7     make
   8     make test
   9     make install
  10
  11 SYNOPSIS
  12   mod_perl installation
  13     * httpd.conf (for mod_perl setup)
  14                   <Files *.plp>
  15                       SetHandler perl-script
  16                       PerlHandler PLP
  17                       PerlSendHeader On
  18                       PerlSetVar PLPcache On
  19                   </Files>
  20
  21                   # Who said CGI was easier to set up? :)
  22
  23   CGI installation
  24     * /foo/bar/plp.cgi (local filesystem address)
  25                   #!/usr/bin/perl
  26                   use PLP;
  27                   PLP::everything();
  28
  29     * httpd.conf (for CGI setup)
  30                   ScriptAlias /foo/bar/ /PLP_COMMON/
  31                   <Directory /foo/bar/>
  32                       AllowOverride None
  33                       Options +ExecCGI
  34                       Order allow,deny
  35                       Allow from all
  36                   </Directory>
  37                   AddHandler plp-document plp
  38                   Action plp-document /PLP_COMMON/plp.cgi
  39
  40   Test script (test.plp)
  41         <html><body>
  42         <:
  43             print "Hurrah, it works!<br>" for 1..10;
  44         :>
  45         </body></html>
  46
  47 DESCRIPTION
  48     PLP is yet another Perl embedder, primarily for HTML documents. Unlike
  49     with other Perl embedders, there is no need to learn a meta-syntax or
  50     object model: one can just use the normal Perl constructs. PLP runs
  51     under mod_perl for speeds comparable to those of PHP, but can also be
  52     run as a CGI script.
  53
  54   PLP Syntax
  55     "<: perl_code(); :>"  With "<:" and ":>", you can add Perl code to your
  56                           document. This is what PLP is all about. All code
  57                           outside of these tags is printed. It is possible
  58                           to mix perl language constructs with normal HTML
  59                           parts of the document:
  60
  61                               <: unless ($ENV{REMOTE_USER}) { :>
  62                                   You are not logged in.
  63                               <: } :>
  64
  65                           ":>" always stops a code block, even when it is
  66                           found in a string literal.
  67
  68     "<:= $expression :>"  Includes a dynamic expression in your document.
  69                           The expression is evaluated in list context.
  70                           Please note that the expression should not end a
  71                           statement: avoid semi-colons. No whitespace may be
  72                           between "<:" and the equal sign.
  73
  74                           "foo <:= $bar :> $baz" is like "<: print 'foo ',
  75                           $bar, ' baz'; :>".
  76
  77     "<(filename)>"        Includes another file before the PLP code is
  78                           executed. The file is included literally, so it
  79                           shares lexical variables. Because this is a
  80                           compile-time tag, it's fast, but you can't use a
  81                           variable as the filename. You can create recursive
  82                           includes, so beware! (PLP will catch simple
  83                           recursion: the maximum depth is 128.) Whitespace
  84                           in the filename is not ignored so "<( foo.txt)>"
  85                           includes the file named " foo.txt", including the
  86                           space in its name. A compile-time alternative is
  87                           include(), which is described in PLP::Functions.
  88
  89   PLP Functions
  90     These are described in PLP::Functions.
  91
  92   PLP Variables
  93     $ENV{PLP_NAME}        The URI of the PLP document, without the query
  94                           string. (Example: "/foo.plp")
  95
  96     $ENV{PLP_FILENAME}    The filename of the PLP document. (Example:
  97                           "/var/www/index.plp")
  98
  99     $PLP::VERSION         The version of PLP.
 100
 101     $PLP::DEBUG           Controls debugging output, and should be treated
 102                           as a bitmask. The least significant bit (1)
 103                           controls if run-time error messages are reported
 104                           to the browser, the second bit (2) controls if
 105                           headers are sent twice, so they get displayed in
 106                           the browser. A value of 3 means both features are
 107                           enabled. The default value is 1.
 108
 109     $PLP::ERROR           Contains a reference to the code that is used to
 110                           report run-time errors. You can override this to
 111                           have it in your own design, and you could even
 112                           make it report errors by e-mail. The sub reference
 113                           gets two arguments: the error message as plain
 114                           text and the error message with special characters
 115                           encoded with HTML entities.
 116
 117     %header, %cookie, %get, %post, %fields
 118                           These are described in PLP::Fields.
 119
 120   (mod_perl only) PerlSetVar configuration directives
 121     PLPcache              Sets caching On/Off. When caching, PLP saves your
 122                           script in memory and doesn't re-read and re-parse
 123                           it if it hasn't changed. PLP will use more memory,
 124                           but will also run 50% faster.
 125
 126                           On is default, anything that isn't =~ /^off$/i is
 127                           considered On.
 128
 129   Things that you should know about
 130     Not only syntax is important, you should also be aware of some other
 131     important features. Your script runs inside the package "PLP::Script"
 132     and shouldn't leave it. This is because when your script ends, all
 133     global variables in the "PLP::Script" package are destroyed, which is
 134     very important if you run under mod_perl (they would retain their values
 135     if they weren't explicitly destroyed).
 136
 137     Until your first output, you are printing to a tied filehandle "PLPOUT".
 138     On first output, headers are sent to the browser and "STDOUT" is
 139     selected for efficiency. To set headers, you must assign to $header{
 140     $header_name} before any output. This means the opening "<:" have to be
 141     the first characters in your document, without any whitespace in front
 142     of them. If you start output and try to set headers later, an error
 143     message will appear telling you on which line your output started. An
 144     alternative way of setting headers is using Perl's BEGIN blocks. BEGIN
 145     blocks are executed as soon as possible, before anything else.
 146
 147     Because the interpreter that mod_perl uses never ends, "END { }" blocks
 148     won't work properly. You should use "PLP_END { };" instead. Note that
 149     this is a not a built-in construct, so it needs proper termination with
 150     a semi-colon (as do <eval> and <do>).
 151
 152     Under mod_perl, modules are loaded only once. A good modular design can
 153     improve performance because of this, but you will have to reload the
 154     modules yourself when there are newer versions.
 155
 156     The special hashes are tied hashes and do not always behave the way you
 157     expect, especially when mixed with modules that expect normal CGI
 158     environments, like CGI.pm. Read PLP::Fields for information more about
 159     this.
 160
 161 FAQ and HowTo
 162     A lot of questions are asked often, so before asking yours, please read
 163     the FAQ at PLP::FAQ. Some examples can be found at PLP::HowTo.
 164
 165 NO WARRANTY
 166     No warranty, no guarantees. Use PLP at your own risk, as I disclaim all
 167     responsibility.
 168
 169 AUTHORS
 170     Currently maintained by Mischa POSLAWSKY <perl@shiar.org>
 171
 172     Originally by Juerd Waalboer <juerd@cpan.org>
 173
 174 SEE ALSO
 175     PLP::Functions, PLP::Fields, PLP::FAQ, PLP::HowTo
 176