X-Git-Url: http://git.shiar.net/perl/plp/.git/blobdiff_plain/2f378f2720eee237f7dbe20643d6c2626c038580..da455137a47490d44e10258c1b875c63e0b34b2d:/README diff --git a/README b/README index deb8daf..17e11ff 100644 --- a/README +++ b/README @@ -1,176 +1,35 @@ -NAME - PLP - Perl in HTML pages +PLP - PERL IN HTML PAGES -MODULE INSTALLATION +PLP is yet another Perl embedder, primarily for HTML documents. Unlike +with other Perl embedders, there is no need to learn a meta-syntax or +object model: one can just use the normal Perl constructs. PLP runs +under mod_perl for speeds comparable to those of PHP, but can also be +run as a CGI script. + +INSTALLATION + +To install this module, run the following commands: perl Makefile.PL make make test make install -SYNOPSIS - mod_perl installation - * httpd.conf (for mod_perl setup) - - SetHandler perl-script - PerlHandler PLP - PerlSendHeader On - PerlSetVar PLPcache On - - - # Who said CGI was easier to set up? :) - - CGI installation - * /foo/bar/plp.cgi (local filesystem address) - #!/usr/bin/perl - use PLP; - PLP::everything(); - - * httpd.conf (for CGI setup) - ScriptAlias /foo/bar/ /PLP_COMMON/ - - AllowOverride None - Options +ExecCGI - Order allow,deny - Allow from all - - AddHandler plp-document plp - Action plp-document /PLP_COMMON/plp.cgi - - Test script (test.plp) - - <: - print "Hurrah, it works!
" for 1..10; - :> - - -DESCRIPTION - PLP is yet another Perl embedder, primarily for HTML documents. Unlike - with other Perl embedders, there is no need to learn a meta-syntax or - object model: one can just use the normal Perl constructs. PLP runs - under mod_perl for speeds comparable to those of PHP, but can also be - run as a CGI script. - - PLP Syntax - "<: perl_code(); :>" With "<:" and ":>", you can add Perl code to your - document. This is what PLP is all about. All code - outside of these tags is printed. It is possible - to mix perl language constructs with normal HTML - parts of the document: - - <: unless ($ENV{REMOTE_USER}) { :> - You are not logged in. - <: } :> - - ":>" always stops a code block, even when it is - found in a string literal. - - "<:= $expression :>" Includes a dynamic expression in your document. - The expression is evaluated in list context. - Please note that the expression should not end a - statement: avoid semi-colons. No whitespace may be - between "<:" and the equal sign. - - "foo <:= $bar :> $baz" is like "<: print 'foo ', - $bar, ' baz'; :>". - - "<(filename)>" Includes another file before the PLP code is - executed. The file is included literally, so it - shares lexical variables. Because this is a - compile-time tag, it's fast, but you can't use a - variable as the filename. You can create recursive - includes, so beware! (PLP will catch simple - recursion: the maximum depth is 128.) Whitespace - in the filename is not ignored so "<( foo.txt)>" - includes the file named " foo.txt", including the - space in its name. A compile-time alternative is - include(), which is described in PLP::Functions. - - PLP Functions - These are described in PLP::Functions. - - PLP Variables - $ENV{PLP_NAME} The URI of the PLP document, without the query - string. (Example: "/foo.plp") - - $ENV{PLP_FILENAME} The filename of the PLP document. (Example: - "/var/www/index.plp") - - $PLP::VERSION The version of PLP. - - $PLP::DEBUG Controls debugging output, and should be treated - as a bitmask. The least significant bit (1) - controls if run-time error messages are reported - to the browser, the second bit (2) controls if - headers are sent twice, so they get displayed in - the browser. A value of 3 means both features are - enabled. The default value is 1. - - $PLP::ERROR Contains a reference to the code that is used to - report run-time errors. You can override this to - have it in your own design, and you could even - make it report errors by e-mail. The sub reference - gets two arguments: the error message as plain - text and the error message with special characters - encoded with HTML entities. - - %header, %cookie, %get, %post, %fields - These are described in PLP::Fields. - - (mod_perl only) PerlSetVar configuration directives - PLPcache Sets caching On/Off. When caching, PLP saves your - script in memory and doesn't re-read and re-parse - it if it hasn't changed. PLP will use more memory, - but will also run 50% faster. - - On is default, anything that isn't =~ /^off$/i is - considered On. - - Things that you should know about - Not only syntax is important, you should also be aware of some other - important features. Your script runs inside the package "PLP::Script" - and shouldn't leave it. This is because when your script ends, all - global variables in the "PLP::Script" package are destroyed, which is - very important if you run under mod_perl (they would retain their values - if they weren't explicitly destroyed). - - Until your first output, you are printing to a tied filehandle "PLPOUT". - On first output, headers are sent to the browser and "STDOUT" is - selected for efficiency. To set headers, you must assign to $header{ - $header_name} before any output. This means the opening "<:" have to be - the first characters in your document, without any whitespace in front - of them. If you start output and try to set headers later, an error - message will appear telling you on which line your output started. An - alternative way of setting headers is using Perl's BEGIN blocks. BEGIN - blocks are executed as soon as possible, before anything else. - - Because the interpreter that mod_perl uses never ends, "END { }" blocks - won't work properly. You should use "PLP_END { };" instead. Note that - this is a not a built-in construct, so it needs proper termination with - a semi-colon (as do and ). +SUPPORT AND DOCUMENTATION - Under mod_perl, modules are loaded only once. A good modular design can - improve performance because of this, but you will have to reload the - modules yourself when there are newer versions. +After installing, documentation will be installed as manual pages: - The special hashes are tied hashes and do not always behave the way you - expect, especially when mixed with modules that expect normal CGI - environments, like CGI.pm. Read PLP::Fields for information more about - this. + man PLP -FAQ and HowTo - A lot of questions are asked often, so before asking yours, please read - the FAQ at PLP::FAQ. Some examples can be found at PLP::HowTo. +It can also be found at CPAN: -NO WARRANTY - No warranty, no guarantees. Use PLP at your own risk, as I disclaim all - responsibility. + http://search.cpan.org/dist/PLP -AUTHORS - Currently maintained by Mischa POSLAWSKY +COPYRIGHT - Originally by Juerd Waalboer +Copyright (c) 2000-2002 Juerd Waalboer, 2005-2008 Mischa POSLAWSKY. +All rights reserved. -SEE ALSO - PLP::Functions, PLP::Fields, PLP::FAQ, PLP::HowTo +This software is free software; you can redistribute and/or modify it +under the terms of the MIT/X11 license (see COPYING).