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


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






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



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


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


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


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.


$Log:,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

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 - 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








 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

 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


Greg Williams <> Doug Weimer <>


Chris Nandor <> for his help on the regex core.