Home : Documentation : 1.3.6 documentation : HTML::Embperl
Google Web perl.apache.org

1.3.6 documentation
Tips & Tricks
More infos
Add info about Embperl

    Stable 2.4.0
    Beta 2.5.0_3
Support the development of Embperl! More...
[ << Prev: DESCRIPTION ] [ Content ] [ Next: Runtime configuration >> ]

Embperl can operate in one of four modes:


Converts an HTML file with embedded Perl statements into a standard HTML file.

embpexec.pl [-o outputfile] [-l logfile] [-d debugflags] htmlfile [query_string]

embpexec.bat [-o outputfile] [-l logfile] [-d debugflags] htmlfile [query_string]

Use embpexec.pl on Unix systems and embpexec.bat on Win32 systems.




The full pathname of the HTML file which should be processed by Embperl.




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. <query_string> should be URL-encoded. The default is no query string.


-o outputfile


Optional. Gives the filename to which the output is written. The default is stdout.


-l logfile


Optional. Gives the filename of the logfile. The default is /tmp/embperl.log.


-d debugflags


Optional. Specifies the level of debugging (what is written to the log file). The default is nothing. See EMBPERL_DEBUG for exact values.

As a CGI scripttop

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.



Use embpcgi.pl on Unix systems and embpcgi.bat on Win32 systems. You can also run Embperl with FastCGI, in this case use embpfastcgi.pl as cgi script. You must have FCGI.pm installed.

If embpcgi.pl/embpcgi.bat is invoked without any parameters and the environment variable PATH_TRANSLATED is set, it runs itself as a CGI script. This means that form data is taken either from the environment variable QUERY_STRING or from stdin, depending on whether or not CONTENT_LENGTH 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 PATH_TRANSLATED and the output is send to stdout. The logfile is generated at its default location, which is configurable via the environment variable EMBPERL_LOG.

To use this mode you must copy embpcgi.pl 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 embpcgi.pl as a handler for a specific file extension or directory.

Example of Apache srm.conf:

    <Directory /path/to/your/html/docs>
    Action text/html /cgi-bin/embperl/embpcgi.pl

NOTE 1: For security reasons, embpexec.pl must not be used as a CGI script anymore!

NOTE 2: CGI Scripts are not so secure. You should consider using EMBPERL_ALLOW to restrict access.

From mod_perl (Apache httpd)top

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 Apache httpd with mod_perl and add HTML::Embperl as the PerlHandler.

Example of Apache srm.conf or httpd.conf:

    SetEnv EMBPERL_DEBUG 2285

    Alias /embperl /path/to/embperl/eg

    <Location /embperl/x>
    SetHandler  perl-script
    PerlHandler HTML::Embperl
    Options     ExecCGI

Another possible setup is

    SetEnv EMBPERL_DEBUG 2285

    <Files *.epl>
    SetHandler  perl-script
    PerlHandler HTML::Embperl
    Options     ExecCGI

    AddType text/html .epl

Don't forget the AddType. In this setup, all files ending with .epl are processed by Embperl.

See the section EMBPERL_DEBUG (dbgLogLink and EMBPERL_VIRTLOG) to find out how you can configure Embperl so you can view the log file with your browser!

NOTE: When mod_perl is compiled as loadable module (i.e. with USE_DSO) you must not load Embperl at server startup time!

See also: perldoc EmbperlObject to see how to setup Embperl so as to create your site out of small overwriteable objects.

By calling HTML::Embperl::Execute (\%param)top

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 a different file).

There are two forms you can use for calling Execute. A short form which only takes a 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 eg/x/Excute.pl for more detailed examples)

See also: perldoc EmbperlObject to see how to setup Embperl so as to create your site out of small overwriteable objects and perldoc HTML::Embperl::Mail on how to use Embperl to send email.

  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:




The file which should be used as source. If input is also specified, this parameter should be given a unique name to identify the source. Every time Embperl sees the same text in inputfile, 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 mtime has changed or is undefined.




Call the Embperl subroutine named by this parameter(see also "[$ 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.




Reference to a string which contains the source. inputfile must also be specified to give a name for the source. The name can be any text.




Last modification time of member input. If undef the code passed by input is always recompiled, else the code is only recompiled if mtime changes.




File to which the output should be written. If neither outputfile nor output is specified, ouput is written to stdout.




Reference to a scalar where the output should be written to.




A value of zero tells Embperl not to execute the page, but define all subrountines found inside. This is neccessary before calling them with Execute by the sub parameter or for a later import.

A value of one tells Embperl to define the subrountines inside the file (if not already done) and to import them as perl subroutines into the current namespace.

See [$ sub $] metacommand and section about subroutines for more info.




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.




This value specifies if and when the cleanup of the package should be executed. (See Variable scope and cleanup below for more information on cleanup)


cleanup = -1


Never cleanup the variables


cleanup = 0 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.


cleanup = 1


Immediate cleanup




Can be used to pass parameters to the Embperl document and back. Must contain a reference to an array.


    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.


ffld and fdat


Could be used to setup the two Embperl predefined variables.




Specifies the first linenumber of the sourcefile (Default: 1)




Same as EMBPERL_OPTIONS (see below), except for cleanup.

NOTE: You should set the optDisableFormData 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.




Same as EMBPERL_DEBUG (see below).




Same as EMBPERL_ESCMODE (see below).




Same as EMBPERL_PACKAGE (see below).




Same as EMBPERL_VIRTLOG (see below). If virtlog is equal to uri the logfile is sent.


allow (1.2b10 and above)


Same as EMBPERL_ALLOW (see below)


path (1.3b1 and above)


Same as EMBPERL_PATH (see below)




The URI of the request. Only needed for the virtlog feature.




Same as EMBPERL_COMPARTMENT (see below).




Same as EMBPERL_INPUT_FUNC (see below). Additionaly you can specify a code reference to a perl subroutine, which is used as input function; or an array reference, where the first element contains the code reference and further elements contain additional arguments passed to the function.




Same as EMBPERL_OUTPUT_FUNC (see below). Additionaly you can specify a code reference to a perl subroutine, which is used as output function; or an array reference, where the first element contains the code reference and further elements contain additional arguments passed to the function.




Same as EMBPERL_COOKIE_NAME (see below).




Same as EMBPERL_COOKIE_PATH (see below).




Same as EMBPERL_COOKIE_DOMAIN (see below).




Same as EMBPERL_COOKIE_EXPIRES (see below).




Takes a reference to an array. Upon return, the array will contain a copy of all errormessages, if any.


object (1.3.1b1 and above)


Takes a filename and returns an hashref that is blessed into the package of the given file. That's usefull, if you want to call the subs inside the given file, as methods. By using the isa parameter (see below) you are able to provide an inherence tree. Additionaly you can use the returned hashref to store data for that obeject.


  [# the file eposubs.htm defines two subs: txt1 and txt2 #]
  [# first we create a new object #]
  [- $subs = Execute ({'object' => 'eposubs.htm'}) -]

  [# then we call methods inside the object #]
  txt1: [+ $subs -> txt1 +] <br>

  txt2: [+ $subs -> txt2 +] <br>

isa (1.3.1b1 and above)


Takes a name of a file and pushes the package of that file into the @ISA array of the current file. By using this you can setup an inherence tree between Embperl documents. Is is also usefull within EmbperlObject.


    [! Execute ({'isa' => '../eposubs.htm'}) !]

syntax (1.3.2 and above)


In 1.3.x the only value that is accepted is 'Text', this emulates the Embperl 2.0 behaviour of simply passing the whole text thru, without doing any processing.

Helper functions for Executetop

HTML::Embperl::Init ($Logfile, $DebugDefault)


This function can be used to setup the logfile path and (optionally) 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 Init to change it at any time.

NOTE: You do not need to call Init in version >= 0.27. The initialization of Embperl takes place automatically when it is loaded.


HTML::Embperl::ScanEnvironment (\%params)


Scans %ENV, setting up %params for use by Execute. All Embperl runtime configuration options are recognized, except EMBPERL_LOG.

EXAMPLES for Execute:top
 # 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 = '<html><head><title>Page [+ $no +]</title></head>' ;

 HTML::Embperl::Execute ({ inputfile  => 'some name',
                           input      => \$src,
                           mtime      => 1 }) ;

 # Get source from scalar and write output to another scalar

 my $src = '<html><head><title>Page [+ $no +]</title></head>' ;
 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') -]

[ << Prev: DESCRIPTION ] [ Content ] [ Next: Runtime configuration >> ]

© 1997-2012 Gerald Richter / ecos gmbh