NAME

XPP (XPML Page Parser) - An embedded perl language designed to co-exist with HTML

SYNOPSIS

 use Apache::XPP;
 my $xpp = Apache::XPP->new( Apache->request );
 $xpml->run;

REQUIRES

 Apache
 Apache::Constants
 File::stat
 FileHandle
 HTTP::Request
 LWP::UserAgent

EXPORTS

Nothing

DESCRIPTION

Apache::XPP is an HTML parser which on run time compiles and runs embedded perl code.

CLASS VARIABLES

$Apache::XPP::main_class

XPP sub-classes must set $Apache::XPP::main_class to the name of the sub-class. This will allow xinclude/include to work properly.

$debug

Activates debugging output. All debugging output is sent to STDERR.

At present there are only 4 levels of debugging : 0 - no debugging (default) 1 - some debugging 2 - verbose debugging 3 - adds some Data::Dumper calls

$debuglines

Optionally, you can activate the $debuglines, which will cause all debugging output to include the line numbers (in this file) of the debugging.

METHODS

handler ( $r )

The Apache handler hook. This is the entry point for the Apache module. It takes the Apache request object ($r) as its parameter and builds a new XPP object to handle the request. In order to support the procedural nature of include() and xinclude() a global is defined. If you subclass Apache::XPP replace the value of the global "$Apache::XPP::main_class" with your class name.

new ( \%params | $filename )

Creates a new XPP object. Valid parameter keys are:

• source - A block of xpp code to be parsed
• filename - A filename/url specifying a code block

All other parameters will be stashed in the xpp object.

preparse ( )

Pre-Parses the object's code, converting TAGS to text and xpp code. This method passes a reference to the xpp source to each preparser returned by the preparse class's parses method. (The preparse class is returned by the preparseclass method).

parse ( )

Parses the object's xpp source code, populating the object's code attribute with a subroutine reference which when run (with the run method), will result in the printing of the xpp page.

run ( @arguments )

Runs the XPP code (set by the parse method), passing any arguments supplied to the code. This should have the effect of printing the xpp page to STDOUT.

returnrun ( @arguments )

Calls run with @arguments as specified, catching all output destined for STDOUT, and returning the results as a string.

load ( $filename )

Returns the code specified by $filename. If $filename begins with a url specifier (e.g. http://), LWP::UserAgent will be used to retrieve the file. If $filename begins with a '/', it will be treated as a rooted filename. Otherwise the filename will be as a file relative to XPPIncludeDir

qualify ( $filename )

Qualifies the passed name to a fully rooted filename by using either incdir or docroot.

incdir ( )

Returns the include directory from which include and xinclude will retrieve source from by default. See include, xinclude, and load for more documentation on this process.

docroot ( )

Returns the document root directory from which all rooted filenames will be retrieved in include, and xinclude.

r ( )

Returns the Apache request object

include ( $filename )

Static, unbuffered, unparsed content include. It can be used within an xpml script by simply saying

  include $filename;

See the load method for more information

xinclude ( $filename, @options )

Dynamic, parsed, buffered content include. It can be used within an xpml script by simply saying

  xinclude $filename;

debug ( $debuglevel [, $debuglines ] )

Manipulates debug level. See $debug above.

N.B. -- at present these flags are global, not per object. Method works as static or dynamic.

include( $inc_location )

Returns the plaintext of the include file $inc_location.

xinclude( $inc_location, @ARGS )

Returns the XPP parsed text of the include file $inc_location, passing @ARGS to the page as arguments.

REVISION HISTORY

$Log: XPP.pm,v $ Revision 1.32 2002/02/15 05:00:01 kasei - fixed bugs introduced by adding Apache::XPP::Inline

Revision 1.31 2002/02/15 02:39:31 kasei - merged 1.30 and 1.28 conflicts

Revision 1.30 2002/02/15 02:17:06 kasei - Fixed quoting bug with $r->content_type - Changed use constant to use subs for Apache constants when in a non m_p environment

Revision 1.29 2002/02/01 08:22:12 kasei Reduced dependance on Apache (still waiting on testing to confirm nothing broke)

Revision 1.28 2002/01/16 22:06:46 kasei - Updated README to mention version 2.01 - POD typo fix in XPP.pm

Revision 1.27 2002/01/16 21:06:01 kasei Updated VERSION variables to 2.01

Revision 1.26 2002/01/16 21:00:02 kasei - Added PREREQ_PM arguments to Makefile.PL - XPP.pm now only uses Data::Dumper if $debug >= 3 (not listed as a prereq)

Revision 1.25 2000/09/23 01:22:06 dweimer Fixed VHostIncludeDir's, thanks david.

Revision 1.24 2000/09/20 00:33:18 zhobson Fixed a warning in docroot(), misplaced "-" made it look like an invalid range

Revision 1.23 2000/09/08 22:26:44 david added, changed, revised, and otherwise cleaned up a lot of POD cleaned up new() - removed dependence on MD5 (uses conventional checksum) - folded nearly duplicate header and footer code into a loop incdir() - now uses Apache->server_root_relative() instead of $ENV{SERVER_ROOT} debug() - new method to manipulate $debug and $debuglines globals Apache::XPP::Tie class now uses $debug settings of Apache::XPP class

        "This would go great with gwack-a-mole!" - Z.B.

Revision 1.22 2000/09/08 00:42:45 dougw Took out rscope stuff.

Revision 1.21 2000/09/07 23:42:23 greg fixed POD

Revision 1.20 2000/09/07 23:30:40 dougw Fixed over.

Revision 1.19 2000/09/07 20:15:54 david new(), r() - makes previous bug fix less agressive, yet more thorough.

Revision 1.18 2000/09/07 19:49:01 david r() - fixed peculiar (and elusive) bug where DirectoryIndex accessed pages (and potentially any page using a subrequest) caused a segmentation fault with cached pages.

Revision 1.17 2000/09/07 18:48:11 dougw Small update

Revision 1.16 2000/09/07 18:45:14 dougw Version update

Revision 1.15 2000/09/06 23:42:50 dougw Modified POD to be consistent with BingoX

SEE ALSO

perl(1).

KNOWN BUGS

None

TODO

precompile

COPYRIGHT

 Copyright (c) 2000, Cnation Inc. All Rights Reserved. This module is free
 software. It may be used, redistributed and/or modified under the terms
 of the GNU Lesser General Public License as published by the Free Software
 Foundation.

 You should have received a copy of the GNU Lesser General Public License
 along with this library; if not, write to the Free Software Foundation, Inc.,
 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

AUTHORS

Greg Williams <greg@cnation.com> Doug Weimer <dougw@cnation.com>

THANKS TO

Chris Nandor <pudge@pobox.com> for his help on the regex core.