=pod =head1 NAME HTML::Embperl - Perl extension for embedding Perl code in HTML documents =head1 SYNOPSIS Embperl is a Perl extension module which gives you the power to embed Perl code directly in your HTML documents (like server-side includes for shell commands). =head1 DESCRIPTION =head1 Operating-Modes Embperl can operate in one of four modes: =head2 Offline Converts an HTML file with embedded Perl statements into a standard HTML file. B B Use embpexec.pl on Unix systems and embpexec.bat on Win32 systems. =over 4 =item B The full pathname of the HTML file which should be processed by Embperl. =item B Optional. Has the same meaning as the environment variable QUERY_STRING when invoked as a CGI script. That is, QUERY_STRING contains everything following the first "?" in a URL. should be URL-encoded. The default is no query string. =item B<-o outputfile> Optional. Gives the filename to which the output is written. The default is stdout. =item B<-l logfile> Optional. Gives the filename of the logfile. The default is /tmp/embperl.log. =item B<-d debugflags> Optional. Specifies the level of debugging (what is written to the log file). The default is nothing. See L<"EMBPERL_DEBUG"> for exact values. =back =head2 As a CGI script Instead of a file being sent directly by the web server, the document is processed by the CGI script and the result is sent to the client. B B Use embpcgi.pl on Unix systems and embpcgi.bat on Win32 systems. If C is invoked without any parameters and the environment variable B is set, it runs itself as a CGI script. This means that form data is taken either from the environment variable B or from stdin, depending on whether or not B is set. (This will be set by the web server depending on whether the request method is GET or POST). Input is taken from the file pointed to by B and the output is send to stdout. The logfile is generated at its default location, which is configurable via the environment variable B. To use this mode you must copy B to your cgi-bin directory. You can invoke it with the URL http://www.domain.xyz/cgi-bin/embpcgi.pl/url/of/your/document. The /url/of/your/document will be passed to Embperl by the web server. Normal processing (aliasing, etc.) takes place before the URI makes it to PATH_TRANSLATED. If you are running the Apache httpd, you can also define B as a handler for a specific file extention or directory. Example of Apache C: Action text/html /cgi-bin/embperl/embpcgi.pl B: Out of security reasons, embpexec.pl must not be used anymore as CGI script! B: CGI Scripts are not so secure. You should consider using L to restrict the access to the rights documents. =head2 From mod_perl (Apache httpd) This works like the CGI-Script, but with the advantage that the script is compiled only once at server startup, where other one-time actions (such as opening files and databases) can take place. This will drastically reduce response times for the request. To use this you must compile C with C and add C as the C. Example of Apache C: SetEnv EMBPERL_DEBUG 2285 Alias /embperl /path/to/embperl/eg SetHandler perl-script PerlHandler HTML::Embperl Options ExecCGI Another possible setup (for Apache 1.3bX see below) is SetEnv EMBPERL_DEBUG 2285 SetHandler perl-script PerlHandler HTML::Embperl Options ExecCGI AddType text/html .epl Don't forget the B. In this setup, all files ending with .epl are processed by Embperl. C Since does not work the same in Apache 1.3bX as it does in Apache 1.2.x, you need to use instead. SetHandler perl-script PerlHandler HTML::Embperl Options ExecCGI See the section L<"EMBPERL_DEBUG"> (dbgLogLink and EMBPERL_VIRTLOG) to find out how you can configure Embperl so you can view the log file with your browser! B: When mod_perl is compiled as loadable module (i.e. with USE_DSO) you B load Embperl at server startup time! =head2 By calling HTML::Embperl::Execute (\%param) Execute can be used to call Embperl from your own modules/scripts (for example from a Apache::Registry or CGI script) or from within another Embperl page (only 1.2b1 or higher) to nest multiple Embperl pages (for example to store a common header or footer in an different file). There are two forms you can use for calling Execute. A short form which only takes an filename and optional additional parameters or a long form which takes a hash reference as its argument. This gives it the chance to vary the parameters according to the job that should be done. (See B for more detailed examples) Execute($filename, $p1, $p2, $pn) ; This will cause Embperl to interpret the file with the name $filename and, if specified, pass any additional parameters in the array @Z<>param (just like @_ in a perl subroutine). The above example could also be written in the long form: Execute ({inputfile => $filename, param => [$p1, $p2, $pn]}) ; The possible items for hash of the long form are: =over 4 =item B The file which should be used as source. If B is also specified, this parameter should be given a unique name to identify the source. Every time Embperl sees the same text in B, it assumes that you compiled the same source - that means that Embperl uses the same package name as in your last call, and only recompiles the code if B has changed or is undefined. =item B Call the Embperl subroutine named by this parameter(see also B<"[$ sub $]">). Currently the subroutine must be in the same file or if it's in another file, the other file has to be imported first. =item B Reference to a string which contains the source. B must also be specified to give a name for the source. The name can be any text. =item B Last modification time of member B. If undef the code passed by input is always recompiled, else the code is only recompiled if mtime changes. =item B File to which the output should be written. If neither outputfile nor output is specified, ouput is written to stdout. =item B Reference to a scalar where the output should be written to. =item B A value of zero tell's Embperl not to execute the page, but define all subrountines found inside. This is neccessary before calling them with Execute by the B parameter or for an later import. A value of one tell's Embperl to define to subrountines inside the file (if not already done) and to import them as perl subroutines into the current namespace. See B<[$ sub $]> metacommand and section about subroutines for more infos. =item B NOTE: The req_rec parameter isn't necessary anymore in versions >= 1.2b2 If used under mod_perl, you should set the req_rec parameter to the Apache request record object provided by mod_perl. =item B This value specifies if and when the cleanup of the package should be executed. (See L<"Variable scope and cleanup"> below for more information on cleanup) =over 4 =item B Never cleanup the variables =item B or not specified If running under mod_perl, cleanup is delayed until the connection to the client is closed, so it does not lengthen the response time to the client. If the Execute function is called more the once before the end of the request, all cleanups take place after the end of the request and not between calls to Execute. If running as a CGI or offline, cleanup takes place immediately. =item B Immediate cleanup =back =item B Can be used to pass parameters to the Embperl document and back. Must contain a reference to an array. Example: HTML::Embperl::Execute(..., param => [1, 2, 3]) ; HTML::Embperl::Execute(..., param => \@parameters) ; The array @Z<>param in the Embperl document is setup as an alias to the array. See eg/x/Excute.pl for a more detailed example. =item B Could be used to setup the two Embperl predefined variables. =item B Specifies the first linenumber of the sourcefile (Default: 1) =item B Same as L<"EMBPERL_OPTIONS"> (see below), except for cleanup. B You should set the B if you have already read the form data from stdin while in a POST request. Otherwise Execute will hang and try to read the data a second time. =item B Same as L<"EMBPERL_DEBUG"> (see below). =item B Same as L<"EMBPERL_ESCMODE"> (see below). =item B Same as L<"EMBPERL_PACKAGE"> (see below). =item B Same as L<"EMBPERL_VIRTLOG"> (see below). If B is equal to B the logfile is sent. =item B The URI of the request. Only needed for the virtlog feature. =item B Same as L<"EMBPERL_COMPARTMENT"> (see below). =item B Same as L<"EMBPERL_INPUT_FUNC"> (see below). Additionaly you can specify an code reference to an perl function, which is used as input function or an array reference, where the first element contains the code reference and further elements contains additional arguments passed to the function. =item B Same as L<"EMBPERL_OUTPUT_FUNC"> (see below). Additionaly you can specify an code reference to an perl function, which is used as output function or an array reference, where the first element contains the code reference and further elements contains additional arguments passed to the function. =item B Same as L<"EMBPERL_COOKIE_NAME"> (see below). =item B Same as L<"EMBPERL_COOKIE_PATH"> (see below). =item B Same as L<"EMBPERL_COOKIE_DOMAIN"> (see below). =item B Same as L<"EMBPERL_COOKIE_EXPIRES"> (see below). =item B Takes a reference to an array. Upon return the array will contain a copy of all errormessages, as long as there are any. =back =head2 Helper functions for Execute =over 4 =item B This function can be used to setup the logfile path and (optional) a default value for the debugflags, which will be used in further calls to Execute. There will always be only one logfile, but you can use B to change it at any time. B You do not need to call Init in version >= 0.27. The initialization of Embperl takes place automatically when it is loaded. =item B Scans the B<%ENV> and setups B<%params> for use by B. All Embperl runtime configuration options are recognized, except EMBPERL_LOG. =back =head2 EXAMPLES for Execute: # Get source from /path/to/your.html and # write output to /path/to/output' HTML::Embperl::Execute ({ inputfile => '/path/to/your.html', outputfile => '/path/to/output'}) ; # Get source from scalar and write output to stdout # Don't forget to modify mtime if $src changes $src = 'Page [+ $no +]' ; HTML::Embperl::Execute ({ inputfile => 'some name', input => \$src, mtime => 1 }) ; # Get source from scalar and write output to another scalar my $src = 'Page [+ $no +]' ; my $out ; HTML::Embperl::Execute ({ inputfile => 'another name', input => \$src, mtime => 1, output => \$out }) ; print $out ; # Include a common header in an Embperl page, # which is stored in /path/to/head.html [- Execute ('/path/to/head.html') -] =head1 Runtime configuration The runtime configuration is done by setting environment variables, either on the command line (when working offline) or in your web server's configuration file. Most HTTP servers understand SetEnv If you are using Apache and mod_perl you can use PerlSetEnv The advantage of PerlSetEnv over SetEnv is that it can be used on a per directory/virtual host basis. =head2 EMBPERL_FILESMATCH If specified, only files which match the given B will be processed by Embperl, all other files will be handled by the standard Apache handler. This can be useful if you have Embperl documents and non Embperl documents (e.g. gifs) cohabitating in the same directory. EMBPERL_FILESMATCH works only under mod_perl. Example: # Only files which end with .htm will processed by Embperl PerlSetEnv EMBPERL_FILESMATCH \.htm$ =head2 EMBPERL_ALLOW (only 1.2b10 and above) If specified, only files which match the given B will be processed by Embperl, all other files will return FORBIDDEN. Especialy in a CGI environenemt this can be usefull to make a server more secure. =head2 EMBPERL_COMPARTMENT Gives the name of the compartment from which to take the opcode mask. (See the chapter about L<"(Safe-)Namespaces and opcode restrictions"> for more details.) =head2 EMBPERL_ESCMODE Specifies the initial value for L<"$escmode"> (see below). =head2 EMBPERL_LOG Gives the location of the log file. This will contain information about what Embperl is doing. How much information depends on the debug settings (see L<"EMBPERL_DEBUG"> below). The log output is intended to show what your embedded Perl code is doing and to help debug it. The default is B. B When running under mod_perl you need to use B for setting the logfile path, and mod_perl >= 1.07_03 if you load Embperl at server startup (with PerlScript or PerlModule). =head2 EMBPERL_PACKAGE The name of the package where your code will be executed. By default, Embperl generates a unique package name for every file. This ensures that variables and functions from one file can not affect those from another file. (Any package's variables will still be accessible with explicit package names.) =head2 EMBPERL_VIRTLOG Gives a virtual location where you can access the Embperl logfile with a browser. This feature is disabled (default) if EMBPERL_VIRTLOG is not specified. See also L<"EMBPERL_DEBUG"> and dbgLogLink for an Example how to set it up in your srm.conf. =head2 EMBPERL_OPTIONS This bitmask specifies some options for the execution of Embperl. To specify multiple options, simply add the values together. =over 4 =item optDisableVarCleanup = 1 Disables the automatic cleanup of variables at the end of each request. =item optDisableEmbperlErrorPage = 2 Tells Embperl to not send its own errorpage in case of failure, instead shows as much of the page as possible. Errors are only logged to the log file. Without this option, Embperl sends its own error page, showing all the errors which have occurred. If you have dbgLogLink enabled, every error will be a link to the corresponding location in the log file. This option has no effect if optReturnError is set. =item optReturnError = 262144 With this option set Embperl sends no output in case of an error, instead it returns the error back to Apache or the calling programm. When running under mod_perl this gives you the chance to use the Apache I directive to show a custom error-document. =item optSafeNamespace = 4 Tells Embperl to execute the embedded code in a safe namespace so the code cannot access data or code in any other package. (See the chapter about L<"(Safe-)Namespaces and opcode restrictions"> below for more details.) =item optOpcodeMask = 8 Tells Embperl to apply an operator mask. This gives you the chance to disallow special (unsafe) opcodes. (See the Chapter about L<"(Safe-)Namespaces and opcode restrictions"> below for more details.) =item optRawInput = 16 Causes Embperl not to pre-process the source for a Perl expression. (The only exception is that carriage returns will be removed, as Perl does not like them.) This option should be set when you are writing your code with an ASCII editor. If you are using a WYSIWYG editor which inserts unwanted HTML tags in your Perl expressions and escapes special charcaters automatically (e.g., `<' appears as `<' in the source), you should not set this option. Embperl will automatically convert the HTML input back to the Perl expressions as you wrote them. =item optEarlyHttpHeader = 64 Normally, HTTP headers are sent after a request is finished without error. This gives you the chance to set arbitrary HTTP headers within the page, and gives Embperl the chance to calculate the content length. Also Embperl watches out for errors and sends an errorpage instead of the document if something goes wrong. To do this, all the output is kept in memory until the whole request is processed, then the HTTP headers are sent, and then the document. This flag will cause the HTTP headers to be sent before the script is processed, and the script's output will be sent directly. =item optDisableChdir = 128 Without this option, Embperl changes the currect directory to the one where the script resides. This gives you the chance to use relative pathnames. Since directory-changing takes up some millisecs, you can disable it with this option if you don't need it. =item optDisableFormData = 256 This option disables the setup of %fdat and @Z<>ffld. Embperl will not do anything with the posted form data. =item optDisableHtmlScan = 512 When set, this option disables the scanning of B html-tags. Embperl will only look for [+/-/!/$ ... $/!/-/+]. This will disable dynamic tables, processing of the input data and so on. =item optDisableInputScan = 1024 Disables processing of all input-related tags. ( The C