X-Git-Url: http://git.shiar.nl/gitweb.cgi/perl/plp/.git/blobdiff_plain/972d413021a3b834599c46ea8a05ae4c0e023029..32ae2f5b7adcaf002d10e60ac6ebad6b63adf23f:/PLP.pm diff --git a/PLP.pm b/PLP.pm index 0d30184..8826b28 100644 --- a/PLP.pm +++ b/PLP.pm @@ -1,4 +1,6 @@ -package PLP; +#--------------# + package PLP; +#--------------# use v5.6; @@ -8,9 +10,13 @@ use PLP::Tie::Headers; use PLP::Tie::Delay; use PLP::Tie::Print; +use File::Basename (); +use File::Spec; +use Cwd (); + use strict; -our $VERSION = '3.11'; +our $VERSION = '3.15'; # subs in this package: # sendheaders Send headers @@ -35,65 +41,113 @@ sub sendheaders () { # Given a filename and optional level (level should be 0 if the caller isn't # source() itself), and optional linespec (used by PLP::Functions::Include), # this function parses a PLP file and returns Perl code, ready to be eval'ed -sub source { - my ($path, $level, $linespec) = @_; - $level = 0 if not defined $level; - $linespec = '1' if not defined $linespec; - - our ($inA, $inB); - - (my $file = $path) =~ s[.*/][]; - - my $source = $level - ? qq/\cQ;\n#line 1 "$file"\nprint q\cQ/ - : qq/\n#line 1 "$file"\nprint q\cQ/; - my $linenr = 0; +{ + my %cached; # Conceal cached sources - local *SOURCE; - open SOURCE, '<', $path or return $level - ? qq{\cQ; die qq[Can't open "\Q$path\E" (\Q$!\E)]; print q\cQ} - : qq{\n#line $linespec\ndie qq[Can't open "\Q$path\E" (\Q$!\E)];}; + # %cached = ( + # $filename => [ + # [ dependency, dependency, dependency ], # <(...)> + # 'source', + # -M + # ] + # ); - LINE: - while (defined (my $line = )) { - $linenr++; - for (;;) { - $line =~ / - \G # Begin where left off - ( \z # End - | <:=? | :> # PLP tags <:= ... :> <: ... :> - | <\(.*?\)> # Include tags <(...)> - | <[^:(][^<:]* # Normal text - | :[^>][^<:]* # Normal text - | [^<:]* # Normal text - ) - /gxs; - next LINE unless length $1; - my $part = $1; - if ($part eq '<:=' and not $inA || $inB) { - $inA = 1; - $source .= "\cQ, "; - } elsif ($part eq '<:' and not $inA || $inB) { - $inB = 1; - $source .= "\cQ; "; - } elsif ($part eq ':>' and $inA) { - $inA = 0; - $source .= ", q\cQ"; - } elsif ($part eq ':>' and $inB) { - $inB = 0; - $source .= "; print q\cQ"; - } elsif ($part =~ /^<\((.*?)\)>\z/ and not $inA || $inB) { - $source .= source($1, $level + 1) . - qq/\cQ, \n#line $linenr "$file"\nq\cQ/; - } else { - $part =~ s/\\/\\\\/ if not $inA || $inB; - $source .= $part; + sub source { + my ($file, $level, $linespec, $path) = @_; + $level = 0 if not defined $level; + $linespec = '1' if not defined $linespec; + + if ($level > 128) { + %cached = (); + return $level + ? qq{\cQ; die qq[Include recursion detected]; print q\cQ} + : qq{\n#line $linespec\ndie qq[Include recursion detected];}; + } + + our ($inA, $inB, $use_cache); + $path ||= File::Spec->rel2abs($file); + + my $source_start = $level + ? qq/\cQ;\n#line 1 "$file"\nprint q\cQ/ + : qq/\n#line 1 "$file"\nprint q\cQ/; + + if ($use_cache and exists $cached{$path}) { + BREAKOUT: { + my @checkstack = ($path); + my $item; + my %checked; + while (defined(my $item = shift @checkstack)) { + next if $checked{$item}; + last BREAKOUT if $cached{$item}[2] > -M $item; + $checked{$item} = 1; + push @checkstack, @{ $cached{$item}[0] } + if @{ $cached{$item}[0] }; + } + return $level + ? $source_start . $cached{$path}[1] + : $source_start . $cached{$path}[1] . "\cQ"; } } - } - $source .= "\cQ" unless $level; - return $source; + $cached{$path} = [ [ ], undef, undef ] if $use_cache; + + my $linenr = 0; + my $source = ''; + + local *SOURCE; + open SOURCE, '<', $path or return $level + ? qq{\cQ; die qq[Can't open "\Q$path\E" (\Q$!\E)]; print q\cQ} + : qq{\n#line $linespec\ndie qq[Can't open "\Q$path\E" (\Q$!\E)];}; + + LINE: + while (defined (my $line = )) { + $linenr++; + for (;;) { + $line =~ / + \G # Begin where left off + ( \z # End + | <:=? | :> # PLP tags <:= ... :> <: ... :> + | <\(.*?\)> # Include tags <(...)> + | <[^:(][^<:]* # Normal text + | :[^>][^<:]* # Normal text + | [^<:]* # Normal text + ) + /gxs; + next LINE unless length $1; + my $part = $1; + if ($part eq '<:=' and not $inA || $inB) { + $inA = 1; + $source .= "\cQ, "; + } elsif ($part eq '<:' and not $inA || $inB) { + $inB = 1; + $source .= "\cQ; "; + } elsif ($part eq ':>' and $inA) { + $inA = 0; + $source .= ", q\cQ"; + } elsif ($part eq ':>' and $inB) { + $inB = 0; + $source .= "; print q\cQ"; + } elsif ($part =~ /^<\((.*?)\)>\z/ and not $inA || $inB) { + my $ipath = File::Spec->rel2abs($1); + $source .= source($1, $level + 1, undef, $ipath) . + qq/\cQ, \n#line $linenr "$file"\nq\cQ/; + push @{ $cached{$path}[0] }, $ipath; + } else { + $part =~ s/\\/\\\\/ if not $inA || $inB; + $source .= $part; + } + } + } + + if ($use_cache) { + $cached{$path}[1] = $source; + $cached{$path}[2] = -M $path; + } + + return $level + ? $source_start . $source + : $source_start . $source . "\cQ"; + } } # Handles errors, uses the sub reference $PLP::ERROR that gets two arguments: @@ -153,11 +207,11 @@ sub clean { # This sub is meant for CGI requests only, and takes apart PATH_TRANSLATED # to find the file. sub cgi_init { - my $file = defined $_[0] ? $_[0] : $ENV{PATH_TRANSLATED}; + my $path = $ENV{PATH_TRANSLATED}; $ENV{PLP_NAME} = $ENV{PATH_INFO}; my $path_info; - while (not -f $file) { - if (not $file =~ s/(\/+[^\/]*)$//) { + while (not -f $path) { + if (not $path =~ s/(\/+[^\/]*)$//) { print STDERR "PLP: Not found: $ENV{PATH_TRANSLATED} ($ENV{REQUEST_URI})\n"; PLP::error(undef, 404); exit; @@ -167,7 +221,7 @@ sub cgi_init { $path_info = $pi . $path_info; } - if (not -r $file) { + if (not -r $path) { print STDERR "PLP: Can't read: $ENV{PATH_TRANSLATED} ($ENV{REQUEST_URI})\n"; PLP::error(undef, 403); exit; @@ -179,11 +233,11 @@ sub cgi_init { }; $ENV{PATH_INFO} = $path_info if defined $path_info; - $ENV{PLP_FILENAME} = $file; - (my $dir = $file) =~ s{/[^/]+$}[]; + $ENV{PLP_FILENAME} = $path; + my ($file, $dir) = File::Basename::fileparse($path); chdir $dir; - $PLP::code = PLP::source($file, 0); + $PLP::code = PLP::source($file, 0, undef, $path); } # This is the mod_perl initializer. @@ -194,16 +248,20 @@ sub mod_perl_init { $ENV{PLP_FILENAME} = my $filename = $r->filename; unless (-f $filename) { - return Apache::Constants::NOT_FOUND; + return Apache::Constants::NOT_FOUND(); } unless (-r _) { - return Apache::Constants::FORBIDDEN; + return Apache::Constants::FORBIDDEN(); } - (my $dir) = $filename =~ m!(.*)/!s; - chdir $dir; $ENV{PLP_NAME} = $r->uri; - $PLP::code = PLP::source($r->filename); + + our $use_cache = $r->dir_config('PLPcache') !~ /^off$/i; + my $path = $r->filename(); + my ($file, $dir) = File::Basename::fileparse($path); + chdir $dir; + + $PLP::code = PLP::source($file, 0, undef, $path); return 0; # OK } @@ -219,6 +277,7 @@ sub start { PLP::Fields::doit(); { package PLP::Script; + use vars qw(%headers %header %cookies %cookie %get %post %fields); *headers = \%header; *cookies = \%cookie; PLP::Functions->import(); @@ -254,7 +313,8 @@ sub handler { return $ret; } start(); - return Apache::Constants::OK; + no strict 'subs'; + return Apache::Constants::OK(); } 1; @@ -275,6 +335,7 @@ PLP - Perl in HTML pages SetHandler perl-script PerlHandler PLP PerlSendHeader On + PerlSetVar PLPcache On # Who said CGI was easier to set up? :) @@ -320,10 +381,131 @@ 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. -=head1 WEBSITE +=head2 PLP Syntax + +=over 22 + +=item C<< <: perl_code(); :> >> + +With C<< <: >> and C<< :> >>, 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. + <: } :> + +C<< :> >> always stops a code block, even when it is found in a string literal. + +=item C<< <:= $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 C<< <: >> and the equal sign. + +C<< foo <:= $bar :> $baz >> is like C<< <: print 'foo ', $bar, ' baz'; :> >>. + +=item C<< <(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 C<< <( foo.txt)> >> +includes the file named C< foo.txt>, including the space in its name. A +compile-time alternative is include(), which is described in L. + +=back + +=head2 PLP Functions + +These are described in L. + +=head2 PLP Variables -For now, all documentation is on the website. Everything will be POD one day, -but until that day, you will need to visit http://plp.juerd.nl/ +=over 22 + +=item $ENV{PLP_NAME} + +The URI of the PLP document, without the query string. (Example: C) + +=item $ENV{PLP_FILENAME} + +The filename of the PLP document. (Example: C) + +=item $PLP::VERSION + +The version of PLP. + +=item $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. + +=item $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. + +=item %header, %cookie, %get, %post, %fields + +These are described in L. + +=back + +=head2 (mod_perl only) PerlSetVar configuration directives + +=over 22 + +=item PLPcache + +Sets caching B/B. 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. + +B is default, anything that isn't =~ /^off$/i is considered On. + +=back + +=head2 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 C and shouldn't +leave it. This is because when your script ends, all global variables in the +C 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 C. On +first output, headers are sent to the browser and C is selected for +efficiency. To set headers, you must assign to C<$header{ $header_name}> before +any output. This means the opening C<< <: >> 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. + +Because the interpreter that mod_perl uses never ends, C blocks won't +work properly. You should use C instead. Note that this is a not +a built-in construct, so it needs proper termination with a semi-colon (as do + and ). + +Under mod_perl, modules are loaded only once. A good modular design can improve +performance because of this, but you will have to B the modules +yourself when there are newer versions. + +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 L for information more about this. + +=head1 FAQ and HowTo + +A lot of questions are asked often, so before asking yours, please read the +FAQ at L. Some examples can be found at L. =head1 NO WARRANTY @@ -332,7 +514,11 @@ responsibility. =head1 AUTHOR -Juerd Waalboer +Juerd Waalboer + +=head1 SEE ALSO + +L, L, L, L =cut