README

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