Embperl - Building dynamic Websites with Perl Copyright (c) 1997-2005 Gerald Richter / ecos gmbh www.ecos.de You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. $Id$ Hints for using Embperl 2.x --------------------------- Embperl 2 is totaly rewritten. Most of the Perl code is moved into C to speed up processing. The core is totaly redesigned to give a lot of new possibilities. The Embperl core now works in a totaly different way. The processing of the source towards the output is done by providers. Every provider takes a small step. Which providers are used is defined by a recipe. The standard Embperl recipe contains the following providers: 1 reading the source 2 parsing 3 compiling 4 executing 5 outputing The providers works in a similar way as Unix shell programm which are processing a single source in a pipeline towards the output. In Embperl is is not only a smimple pipeline, but a tree structure, so multiple sources can be incorpoarted in one result. Recipes descripes how providers are executed. Rearrangeing the provideres or writing and useing new ones gives flexibility and power. Addtional to the standard Embperl providers Embperl ships with XML parser and XSLT processor providers. The new execution scheme is also faster, because html tags and metacommands are parsed only once (Perl code was also (and is still) cached in 1.x) My first benchmarks show 50%-100% faster execution under mod_perl compared to Embperl 1.x. Another new feature is that the syntax of the Embperl parser is defined within the module Embperl::Syntax and can be modified as nessecary. Embperl comes with a set of syntax definitons which can be modified by the user. So far there are syntax definitions for SSI, Text only, Perl only, ASP, POD, RTF and a Mail taglib. You can tell Embperl which syntax to use either in the configuration via EMBPERL_SYNTAX, or with the syntax parameter of Execute, or you can change the syntax dynamically inside the page via the [$syntax $] command. You also could specify more then one syntax at the same time, e.g. [$syntax Embperl SSI $] to mix Embperl tags and SSI tags in the same page. If you'd like to create your own syntax read: perldoc Embperl::Syntax and look at the files under Embperl/Syntax/ for examples on how to do it. Also new is the ability to cache (parts of) the output. See the new configuration directives below. Starting with 2.0b6 Embperl provides a set of new object, which allows to access Embperl internals and manipulate the processing. Basicly there are three major objects: - Application - Request - Component The application object is responsible for a set of pages that forms an application. It is used to configure things like session handling and logging which should be unique across these pages. More important it can be overriden and the overriden object can contain the application logic, to create a proper separation of logic and presentation. The request object holds everything which spans a whole (HTTP-)request. The component object is responsible for a single component, inside the desired output. It holds things like sourcefile etc. All three objects have a subobject which holds the configuration and a subobject for it's current parameters. Debugging --------- Starting with 2.0b2 Embperl files can debugged via the interactive debugger. The debugger shows the Embperl page source along with the correct linenumbers. You can do anything you can do inside a normal Perl programm via the debugger, e.g. show variables, modify variables, single step, set breakpoints etc. You can use the Perl interacive command line debugger via perl -d embpexec.pl file.epl or if you prefer a graphical debugger, try ddd (http://www.gnu.org/software/ddd/) it's a great tool, also for debugging any other perl script: ddd --debugger 'perl -d embpexec.pl file.epl' NOTE: embpexec.pl could be found in the Embperl source directory If you want to debug your pages, while running under mod_perl, Apache::DB is the right thing. Apache::DB is available from CPAN. The following differences to Embperl 1.x apply: ------------------------------------------------------ - When running under mod_perl you _must_ load Embperl at server startup time. Either with a PerlModule Embperl in your httpd.conf or a use Embperl ; inside of a startup script. You can use the Embperl configuration directives now directly, (without PerlSetEnv/SetEnv). If you still want to use enviroment varibales to configure Embperl, write Embperl_UseEnv on - Embperl now supports Apache 2 / mod_perl 2, but you need a additional configuration line in your httpd.conf: LoadModule embperl_module /path/to/perl/site/lib/Embperl/Embperl.so - For every container in your httpd.conf (e.g. VirtualHost,Directory,Location) where you want to define any application level configuration directives (see below under tAppConfig for a list), you need to set a unique value for EMBPERL_APPNAME. This is for example necessary for all Embperl::Object parameters. Example: EMBPERL_APPNAME my_embperl_app EMBPERL_OBJECT_BASE base.epl - The following options can currently only be set from httpd.conf: optKeepSpaces - The option optRawInput is replaced by EMBPERL_INPUT_ESCMODE, which is off by default (same as when optRawInput was set in 1.x) - The following options are currently not supported: optRedirectStdout optDisableHtmlScan, optDisableTableScan, optDisableInputScan, optDisableMetaScan optDisableHtmlScan can be replaced by switching the syntax, e.g. [$syntax EmbperlBlocks $] # same as [- $optDisableHtmlScan = 1 -] (here goes your code - Embperl will not interpret any html tags here) [$syntax Embperl $] # same as [- $optDisableHtmlScan = 0 -] - Nesting must be done properly. I.e. you cannot put a tag (for a dynamic table) inside an 'if' and the
inside another 'if'. (That still works for static tables) - optUndefToEmptyValue is always set and cannot be disabled. - [$ foreach $x (@x) $] now requires the brackets around the array (like Perl) - [+ +] blocks must now contain a valid Perl expression. Embperl 1.x allows you to put multiple statements into such a block. For performance reasons this is not possible anymore. Also the expression must _not_ be terminated with a semicolon. To let old code work, just wrap it into a 'do' e.g. [+ do { my $a = $b + 5 ; $a } +] - EMBPERL_INPUT_FUNC and EMBPERL_OUTPUT_FUNC are not supported anymore You can the same result and much more by writing custom provider. - Embperl doesn't change the current working directory anymore to the directory of the source file. This is done for performance reasons and because it won't reliable work with threads under mod_perl 2.0. You can use $req -> component -> cwd to get the directory of the sourcefile (where $req is Embperl request object, which is the first paramter passed to the page i.e. $_[0]) - safe namespaces are not supported anymore, since are are not really safe anyway - errors can be mailed to an administrator - Parameters of SetupSession, CleanupSession and SetSessionCookie have changed. Embperl 1.x compatibility flag ------------------------------ The compatibility flag isn't available anymore in 2.0b6. Since now Embperl 2.0 lives in his own namespace, you can install Embperl 1.x and 2.x on the same machine without conflicts. exit ---- B will override the normal Perl exit in every Embperl document. Calling exit will immediately stop any further processing of that file and send the already-done work to the output/browser. B If you are inside of an Execute, Embperl will only exit this Execute, but the file which called the file containing the exit with Execute will continue. If you want to exit the whole request, call exit with an argument e.g. exit (200) B If you write a module which should work with Embperl under mod_perl, you must use Embperl::exit instead of the normal Perl exit. (In 1.3.x it was Apache::Exit) ------------------- Enjoy Gerald