Provided by: libembperl-perl_2.5.0-12build1_amd64 bug

NAME

       Embperl::Config - Embperl configuration and calling

Operating-Modes

       Embperl can operate in one of four modes:

       mod_perl
           The mostly used way is to use Embperl together with mod_perl and Apache.  This gives
           the best performance and the most possibilities.

       CGI/FastCGI
           When you want to run Embperl on a machine that doesn't have mod_perl, you can run
           Embperl also as normal CGI script. Due to the overhead of CGI, this mode is much
           slower. To get a better performance you should consider using Embperl together with
           FastCGI. (http://www.fastcgi.com).

       Offline
           You can use Embperl also on the command line. This is useful for generating static
           content out of dynamic pages and can sometime be helpful for testing.

       Call it from other Perl programs
           If you have your own application and want to use Embperl's capbilities you can do so
           by calling Embperl::Execute. This allows you to build your own application logic and
           use Embperl possibilities for rendering content.

   mod_perl
       To use Embperl under mod_perl you must have installed Apache and mod_perl on your system.
       Then you add some directives to your httpd.conf to load Embperl and add "Embperl" as the
       "PerlHandler". The following directives will cause all file with extetion epl to be
       handled by Embperl:

           PerlModule Embperl

           AddType text/html .epl

           <Files *.epl>
           SetHandler  perl-script
           PerlHandler Embperl
           Options     ExecCGI
           </files>

       Another possibility is to have all files under a special location processed by Embperl:

           PerlModule Embperl

           Alias /embperl /path/to/embperl/eg

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

       In this setup you should make sure that non Embperl files like images doesn't served from
       this directory.

       For mod_perl 2.0 you need addtionaly to load the dynamic object library of Embperl. This
       is necessary so Embperl is loaded early enough to register the configuration directives
       with Apache. After installing, search underneath your Perl site directory for the library.
       On Unix it is mostly called Embperl.so on Windows it is called "Embperl.dll".  Now add the
       following line to your httpd.conf before any of the Embperl configuration directives, but
       after mod_perl.so is loaded:

           LoadModule  embperl_module  /path/to/perl/site/lib/Embperl/Embperl.so

       To use Embperl::Object you use the "Embperl::Object" as "PerlHandler":

           <Location /foo>
               Embperl_AppName     unique-name
               Embperl_Object_Base base.htm
               Embperl_UriMatch    "\.htm.?|\.epl$"
               SetHandler          perl-script
               PerlHandler         Embperl::Object
               Options             ExecCGI
           </Location>

       Addtionaly you can setup other parameters for Embperl::Object. If you do so inside a
       container (like "<Location", <Directory>, <Files>>) you need to set "Embperl_AppName" to a
       unique-name (the actual value doesn't matter).  The "Embperl_UriMatch" makes sure that
       only files of the requested type are served by Embperl::Object, while all others are
       served by Apache as usual.

       For more information see: "perldoc Embperl::Object".

       Embperl accepts a lot of configuration directives to customize it's behaviour. See the
       next section for a description.

       NOTE: If mod_perl is statically linked into Apache you can not use ClearModuleList in your
       httpd.conf

       Preloading pages

       To optimize memory usage you can preload your pages during the initialization. If you do
       so they will get loaded into the parent process and the memory will be shared by all child
       processes.

       To let Embperl preload your files, you have to supply all the filename into the key
       preloadfiles of the hash %initparam, before you load Embperl.

       Example:

         BEGIN
           {
           $Embperl::initparam{preloadfiles} =
               [
               '/path/to/foo.epl',
               '/path/to/bar.epl',
               { inputfile  => "/path/to/other.epl", input_escmode => 7 },
               ] ;
           }

         use Embperl ;

       As you see for the third file, it is also possible to give a hashref and supply the same
       parameter like Execute accpets (see below).

       NOTE: Preloading is not supported under Apache 1.3, when mod_perl is loaded as DSO. To use
       preloading under Apache 1.3 you need to compile mod_perl statically into Apache.

   CGI/FastCGI
       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 "httpd.conf":

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

       NOTE: Via CGI Scripts it maybe possible to bypass some of the Apache setup. To avoid this
       use Embperl_Allow to restrict access to the files, which should be processed by Embperl.

       For Embperl::Object you have to use epocgi.pl instead of embpcgi.pl.

       You can also run Embperl with FastCGI, in this case use embpfastcgi.pl as cgi script. You
       must have FCGI.pm installed.

   Offline
       Run Embperl from the comannd line use embpexec.pl on unix and embpexec.bat on windows:

       embpexec.pl [options] htmlfile [query_string]

       embpexec.bat [options] htmlfile [query_string]

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

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

       Options:

       -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 on unix
           and \embperl.log on windows.

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

       -t options
           See "EMBPERL_OPTIONS" for option values.

       -s syntax
           Defines the syntax of the source. See See "EMBPERL_SYNTAX"

       -p param
           Gives a value which is passed in the @param array to the executed page.  Can be given
           multiple times.

       -f fdat value
           Gives a name/value pair which is passed in the %fdat hash to the executed page.  Can
           be given multiple times.

   By calling 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 to nest multiple
       Embperl pages (for example to store a common header or footer in a different file).

       (See eg/x/Excute.pl for more detailed examples)

       When you want to use Embperl::Object call "Embperl::Object::Execute", when you want
       Embperl::Mail, call "Embperl::Mail::Execute".

       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.

         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 @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 are descriped in the configuration
       section and parameter section.

       EXAMPLES for Execute:

        # Get source from /path/to/your.html and
        # write output to /path/to/output'

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

        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 ;

        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') -]

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

Configuration

       Configuration can be setup in different ways, depending how you run Embperl.  When you run
       under mod_perl, Embperl add a set of new configuration directives to the Apache
       configuration, so you can set them in your httpd.conf.  When you run Embperl as CGI it
       takes the configuration from environment variables.  For compatibility reason that can
       also be turned on under mod_perl, by adding "Embperl_UseEnv on" in your httpd.conf. When
       you call Embperl from another Perl program, by calling the "Execute" function, you can
       pass your configuration along with other parameters as a hash reference. If you pass
       "use_env =&lt; 1" als parameter Embperl will also scan the environment for configuration
       information. Last but not least you can pass configuration information as options when you
       run Embperl via embpexec.pl from the command line. Some of the configuration options are
       also setable inside the page via the Empberl objects and you can read the current
       configuration from these objects.

       You can not only pass configuration in different ways, there are also three different
       contexts: Application, Request and Component.  A application describes a set of
       pages/files that belongs together and form the application. Application level
       configuration are the same for all files that belongs to an application. These
       configuration information need to be known before any request processing takes place, so
       they can't be modified during a request. Every application has it's own name.  You can
       refer the configuration of an application, by simply setting the name of the application
       to use.

       Request level configuration information applies to one request, some of them must be known
       before the request starts, some of them can still be modified during the request.

       Configuration for components can be setup before the request, but can also be passed as
       argument when you call the component via "Execute".

   Embperl_Useenv
       Env:
           EMBPERL_USEENV

       Method:
           $application -> config -> use_env [read only]

       Default:
           off unless running as CGI script

       Since:
           2.0b6

       Tells Embperl to scan the enviromemt for configuration settings.

   use_redirect_env
       Method:
           $application -> config -> use_redirect_env [read only]

       Default:
           off unless running as CGI script

       Since:
           2.0b6

       Tells Embperl to scan the enviromemt for configuration settings which has the prefix
       "REDIRECT_". This is normally the case when the request is not the main request, but a
       subrequest.

   Embperl_Appname
       Env:
           EMBPERL_APPNAME

       Method:
           $application -> config -> app_name [read only]

       Since:
           2.0b6

       Specifies the name for an application. The name is basically used to refer to this
       application elsewhere in httpd.conf without the need to setup the parameters for the
       apllication again.

   Embperl_App_Handler_Class
       Env:
           EMBPERL_APP_HANDLER_CLASS

       Method:
           $application -> config -> app_handler_class [read only]

       Since:
           2.0b6

       Embperl will call the "init" method of the given class at the start of the request, but
       after all request parameters are setup. This give the class a chance to do any necessary
       computation and modify the request parameters, before the request is actualy executed. See
       internationalization for an example.

   Embperl_Session_Handler_Class
       Env:
           EMBPERL_SESSION_HANDLER_CLASS

       Method:
           $application -> config -> session_handler_class [read only]

       Default:
           Apache::SessionX

       Since:
           1.3b3

       See also:
           Session Handling

       Set the class that performs the Embperl session handling. This gives you the possibility
       to implement your own session handling.

       NOTE: Default until 1.3.3 was "HTML::Embperl::Session", starting with 1.3.4 it is
       "Apache::SessionX". To get the old session behaviour set it to "HTML::Embperl::Session".

   Embperl_Session_Args
       Env:
           EMBPERL_SESSION_ARGS

       Method:
           $application -> config -> session_args [read only]

       Since:
           1.3b3

       See also:
           Session Handling

       List of arguments for Apache::Session classes Arguments that contains spaces can be
       quoted.  Example:

         EMBPERL_SESSION_ARGS "DataSource=dbi:mysql:session UserName=www 'Password=secret word'"

   Embperl_Session_Classes
       Env:
           EMBPERL_SESSION_CLASSES

       Method:
           $application -> config -> session_classes [read only]

       Since:
           1.3b3

       See also:
           Session Handling

       Space separated list of object store and lock manager (and optionally the serialization
       and id generating class) for Apache::Session (see "Session handling")

   Embperl_Session_Config
       Env:
           EMBPERL_SESSION_CONFIG

       Method:
           $application -> config -> session_config [read only]

       Default:
           given when running Makefile.PL of Apache::SessionX

       Since:
           1.3.3

       See also:
           Session Handling

       Selects a session configuration from the configurations you have defined when running
       Apache::SessionX's "Makefile.PL".

       NOTE: Use either "EMBPERL_SESSION_CONFIG" or "EMBPERL_SESSION_ARGS" and
       "EMBPERL_SESSION_CLASSES"

   Embperl_Cookie_Name
       Env:
           EMBPERL_COOKIE_NAME

       Method:
           $application -> config -> cookie_name [read only]

       Default:
           EMBPERL_UID

       Since:
           1.2b4

       See also:
           Session Handling

       Set the name that Embperl uses when it sends the cookie with the session id.

   Embperl_Cookie_Domain
       Env:
           EMBPERL_COOKIE_DOMAIN

       Method:
           $application -> config -> cookie_domain [read only]

       Default:
           none

       Since:
           1.2b4

       See also:
           Session Handling

       Set the domain that Embperl uses for the cookie with the session id.

   Embperl_Cookie_Path
       Env:
           EMBPERL_COOKIE_PATH

       Method:
           $application -> config -> cookie_path [read only]

       Default:
           none

       Since:
           1.2b4

       See also:
           Session Handling

       Set the path that Embperl uses for the cookie with the session id.

   Embperl_Cookie_Expires
       Env:
           EMBPERL_COOKIE_EXPIRES

       Method:
           $application -> config -> cookie_expires [read only]

       Default:
           at the end of the session

       Since:
           1.3b5

       See also:
           Session Handling

       Set the expiration date that Embperl uses for the cookie with the session id.  You can
       specify the full date or relativ values.  The following forms are all valid times:

               +30s                              30 seconds from now
               +10m                              ten minutes from now
               +1h                               one hour from now
               -1d                               yesterday (i.e. "ASAP!")
               now                               immediately
               +3M                               in three months
               +10y                              in ten years time
               Thu, 25-Apr-1999 00:40:33 GMT     at the indicated time & date

   Embperl_Cookie_Secure
       Env:
           EMBPERL_COOKIE_SECURE

       Method:
           $application -> config -> cookie_secure [read only]

       Default:
           at the end of the session

       Since:
           2.0b9

       See also:
           Session Handling

       Set the secure flag of cookie that Embperl uses for the session id. If set the cookie will
       only be transferred over a secured connection.

   Embperl_Log
       Env:
           EMBPERL_LOG

       Method:
           $application -> config -> log [read only]

       Default:
           Unix: /tmp/embperl.log  Windows: /embperl.log

       Gives the location of the log file.  This will contain information about what Embperl is
       doing.  The amount of information depends on the debug settings (see "EMBPERL_DEBUG"
       below).  The log output is intended to show what your embedded Perl code is doing and to
       help debug it.

   Embperl_Debug
       Env:
           EMBPERL_DEBUG

       Method:
           $application -> config -> debug

       This is a bitmask which specifies what should be written to the log.  To specify multiple
       debugflags, simply add the values together.  You can give the value a decimal, octal
       (prefix 0) or hexadecimal (prefix 0x) value.  You can also use the constants defined in
       Embperl::Constant.  The following values are defined:

       dbgStd = 1 (0x1)
           Show minimum information.

       dbgMem = 2 (0x2)
           Show memory and scalar value allocation.

       dbgEval = 4 (0x4)
           Show arguments to and results of evals.

       dbgEnv = 16 (0x10)
           List every request's environment variables.

       dbgForm = 32 (0x20)
           List posted form data.

       dbgInput = 128 (0x80)
           Show processing of HTML input tags.

       dbgFlushOutput = 256 (0x100)
           Flush Embperl's output after every write.  This should only be set to help debug
           Embperl crashes, as it drastically slows down Embperl's operation.

       dbgFlushLog = 512 (0x200)
           Flush Embperl's logfile output after every write.  This should only be set to help
           debug Embperl crashes, as it drastically slows down Embperl's operation.

       dbgLogLink = 8192 (0x2000)
           This feature is not yet implemented in Embperl 2.0!

           Inserts a link at the top of each page which can be used to view the log for the
           current HTML file.  See also "EMBPERL_VIRTLOG".

           Example:

               EMBPERL_DEBUG 10477
               EMBPERL_VIRTLOG /embperl/log.htm

               <Location /embperl/log.htm>
               SetHandler perl-script
               PerlHandler Embperl
               Options ExecCGI
               </Location>

       dbgDefEval = 16384 (0x4000)
           Shows every time new Perl code is compiled.

       dbgHeadersIn = 262144 (0x40000)
           Log all HTTP headers which are sent from and to the browser.

       dbgShowCleanup = 524288 (0x80000)
           Show every variable which is undef'd at the end of the request.  For scalar variables,
           the value before undef'ing is logged.

       dbgSession = 2097152 (0x200000)
           Enables logging of session transactions.

       dbgImport =  4194304 (0x400000)
           Show how subroutines are imported in other namespaces.

       dbgOutput = 0x08000
           Logs the process of converting the internal tree strcuture to plain text for output

       dbgDOM = 0x10000
           Logs things related to processing the internal tree data structure of documents

       dbgRun = 0x20000
           Logs things related to execution of a document

       dbgBuildToken = 0x800000
           Logs things related to creating the token tables for source parsing

       dbgParse = 0x1000000
           Logs the parseing of the source

       dbgObjectSearch = 0x2000000
           Shows how Embperl::Objects searches sourcefiles

       dbgCache = 0x4000000
           Logs cache related things

       dbgCompile = 0x8000000
           Gives information about compiling the parsed source to Perl code

       dbgXML = 0x10000000
           Logs things related to XML processing

       dbgXSLT = 0x20000000
           Logs things related to XSLT processing

       dbgCheckpoint = 0x40000000
           Logs things related to checkpoints which are internaly used during execution.  This
           information is only useful if you have a deep knowledge of Embperl internals.

   Embperl_Maildebug
       Env:
           EMBPERL_MAILDEBUG

       Method:
           $application -> config -> maildebug

       Since:
           1.2.1

       Debug value pass to Net::SMTP.

   Embperl_Mailhost
       Env:
           EMBPERL_MAILHOST

       Method:
           $application -> config -> mailhost

       Default:
           localhost

       Specifies which host the mail related functions of Embperl uses as SMTP server.

   Embperl_Mailhelo
       Env:
           EMBPERL_MAILHELO

       Method:
           $application -> config -> mailhelo

       Default:
           chosen by Net::SMTP

       Since:
           1.3b4

       Specifies which host/domain all mailrealted function uses in the HELO/EHLO command.  A
       reasonable default is normally chosen by Net::SMTP, but depending on your installation it
       may necessary to set it manualy.

   Embperl_Mailfrom
       Env:
           EMBPERL_MAILFROM

       Method:
           $application -> config -> mailfrom

       Default:
           www-server@<server_name>

       Since:
           1.2.1

       Specifies the email address that is used as sender all mailrelted function.

   Embperl_Mail_Errors_To
       Env:
           EMBPERL_MAIL_ERRORS_TO

       Method:
           $application -> config -> mail_errors_to

       If set all errors will be send to the email address given.

   Embperl_Mail_Errors_Limit
       Env:
           EMBPERL_MAIL_ERRORS_LIMIT

       Method:
           $application -> config -> mail_errors_limit [read only]

       Since:
           2.0b6

       Do not mail more then <num> errors. Set to 0 for no limit.

   Embperl_Mail_Errors_Reset_Time
       Env:
           EMBPERL_MAIL_ERRORS_RESET_TIME

       Method:
           $application -> config -> mail_errors_reset_time [read only]

       Since:
           2.0b6

       Reset error counter if for <sec> seconds no error has occurred.

   Embperl_Mail_Errors_Resend_Time
       Env:
           EMBPERL_MAIL_ERRORS_RESEND_TIME

       Method:
           $application -> config -> mail_errors_resend_time [read only]

       Since:
           2.0b6

       Mail errors of <sec> seconds regardless of the error counter.

   Embperl_Object_Base
       Env:
           EMBPERL_OBJECT_BASE

       Method:
           $application -> config -> object_base [read only]

       Default:
           _base.epl

       Since:
           1.3b1

       Name of the base page that Embperl::Objects searches for.

   Embperl_Object_App
       Env:
           EMBPERL_OBJECT_APP

       Method:
           $application -> config -> object_app

       Since:
           2.0b6

       Filename of the application object that Embperl::Object searches for.  The file should
       contain the Perl code for the application object. There must be no package name given (as
       the package is set by Embperl::Object) inside the file, but the @ISA should point to
       Embperl::App.  If set this file is searched through the same search path as any content
       file.  After a successful load the init method is called with the Embperl request object
       as parameter. The init method can change the parameters inside the request object to
       influence the current request.

   Embperl_Object_Addpath
       Env:
           EMBPERL_OBJECT_ADDPATH

       Method:
           $application -> config -> object_addpath

       Since:
           1.3b1

       Additional directories where Embperl::Object searches for pages.

       This search through the searchpath is always performed if in a call to Execute no path for
       the file is given.

       In httpd.conf or as environment variable directories are separated by ";" (on Unix ":"
       works also). The parameter for "Execute" and the application object method expects/returns
       an array reference.  This path is always appended to the searchpath.

   Embperl_Object_Reqpath
       Env:
           EMBPERL_OBJECT_REQPATH

       Method:
           $application -> config -> object_reqpath

       Since:
           2.0b12

       Additional directories where Embperl::Object searches for files for the initial request.

       If a file is requested, but cannot be found at the given location, the directories given
       in the this path are additionally searched for the file. This applies only to the initial
       filename given to Embperl::Object and not to files called via Execute.

       In httpd.conf or as environment variable directories are separated by ";" (on Unix ":"
       works also). The parameter for "Execute" and the application object method expects/returns
       an array reference.

       Example:

       if you say

           Embperl_Object_Reqpath  /a:/b:/c

       and you request

           /x/index.epl

       it will try

           /x/index.epl
           /a/index.epl
           /b/index.epl
           /c/index.epl

       and take the first one that is found.

   Embperl_Object_Stopdir
       Env:
           EMBPERL_OBJECT_STOPDIR

       Method:
           $application -> config -> object_stopdir

       Since:
           1.3b1

       Directory where Embperl::Object stops searching for the base page.

   Embperl_Object_Fallback
       Env:
           EMBPERL_OBJECT_FALLBACK

       Method:
           $application -> config -> object_fallback

       Since:
           1.3b1

       If the requested file is not found by Embperl::Object, the file given by
       "EMBPERL_OBJECT_FALLBACK" is displayed instead. If "EMBPERL_OBJECT_FALLBACK" isn't set a
       staus 404, NOT_FOUND is returned as usual. If the fileame given in
       "EMBPERL_OBJECT_FALLBACK" doesn't contain a path, it is searched thru the same directories
       as "EMBPERL_OBJECT_BASE".

   Embperl_Object_Handler_Class
       Env:
           EMBPERL_OBJECT_HANDLER_CLASS

       Method:
           $application -> config -> object_handler_class

       Since:
           1.3b1

       If you specify this, the template base and the requested page inherit all methods from
       this class. This class must contain "Embperl::Req" in his @ISA array.

   Embperl_Useenv
       Env:
           EMBPERL_USEENV

       Method:
           $request -> config -> use_env [read only]

       Default:
           off unless running as CGI script

       Since:
           2.0b6

       Tells Embperl to scan the enviromemt for configuration settings.

   use_redirect_env
       Method:
           $request -> config -> use_redirect_env [read only]

       Default:
           off unless running as CGI script

       Since:
           2.0b6

       Tells Embperl to scan the enviromemt for configuration settings which has the prefix
       "REDIRECT_". This is normally the case when the request is not the main request, but a
       subrequest.

   Embperl_Allow
       Env:
           EMBPERL_ALLOW

       Method:
           $request -> config -> allow [read only]

       Default:
           no restrictions

       Since:
           1.2b10

       If specified, only files which match the given perl regular expression will be processed
       by Embperl. All other files will return FORBIDDEN.  This is especially useful in a CGI
       environment by making the server more secure.

   Embperl_Urimatch
       Env:
           EMBPERL_URIMATCH

       Method:
           $request -> config -> urimatch [read only]

       Default:
           process all files

       Since:
           2.0b6

       If specified, only files which match the given perl regular expression 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) residing in the
       same directory.

        Example:
        # Only files which end with .htm will processed by Embperl
        EMBPERL_URIMATCH \.htm$

   Embperl_Multfieldsep
       Env:
           EMBPERL_MULTFIELDSEP

       Method:
           $request -> config -> mult_field_sep [read only]

       Default:
           \t

       Since:
           2.0b6

       Specifies the character that is used to separate multiple form values with the same name.

   Embperl_Path
       Env:
           EMBPERL_PATH

       Method:
           $request -> config -> path [read only]

       Since:
           1.3b6

       Can contain a semicolon (also colon under Unix) separated file search path.  When a file
       is processed and the filename isn't an absolute path or does not start with ./ (or .\
       under windows), Embperl searches all the specified directories for that file.

       A special handling is done if the filename starts with any number of "../" i.e. refers to
       an upper directory. Then Embperl strips the same number of entries at the start of the
       searchpath as the filename contains "../".  "Execute" and the method of the request object
       expects/returns a array ref.

   Embperl_Debug
       Env:
           EMBPERL_DEBUG

       Method:
           $request -> config -> debug

       See application configuration for an describtion of possible values

   Embperl_Options
       Env:
           EMBPERL_OPTIONS

       Method:
           $request -> config -> options

       This bitmask specifies some options for the execution of Embperl.  To specify multiple
       options, simply add the values together.

       optDisableVarCleanup = 1
           Disables the automatic cleanup of variables at the end of each request.

       optDisableEmbperlErrorPage = 2
           Tells Embperl not to send its own errorpage in case of failure, but instead show 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.

       optReturnError = 262144
           With this option set, Embperl sends no output in case of an error.  It returns the
           error back to Apache or the calling program. When running under mod_perl this gives
           you the chance to use the Apache ErrorDocument directive to show a custom error-
           document. Inside the ErrorDocument you can retrieve the error messages with

             $errors = $req_rec -> prev -> pnotes('EMBPERL_ERRORS') ;

           where $errors is a array reference. (1.3b5+)

       optShowBacktrace = 0x8000000
           When set every error message not only show the sourcefiles, but all files from which
           this file was called by Execute.

   Embperl_Output_Mode
       Env:
           EMBPERL_OUTPUT_MODE

       Method:
           $request -> config -> output_mode

       Default:
           HTML

       Since:
           2.0b9

       Set the desired output format. 0 for HTML and 1 XML. If set to XML all tags that are
       generated by Embperl will contain a closing slash to conform to XML specs. e.g.

           <input type="text" name="foo" />

       NOTE: If you set output_mode to XML you should also change escmode to XML escaping.

   Embperl_Output_Esc_Charset
       Env:
           EMBPERL_OUTPUT_ESC_CHARSET

       Method:
           $request -> config -> output_esc_charset [read only]

       Default:
           ocharsetLatin1 = 1

       Since:
           2.0.2

       Set the charset which to assume when escaping. This can only be set before the request
       starts (e.g. httpd.conf or top of the page).  Setting it inside the page has undefined
       results.

       ocharsetUtf8 = 0
           UTF-8 or any non known charset. Characters with codes above 128 will not be escaped at
           all

       ocharsetLatin1 = 1
           ISO-8859-1, the default. When a Perl string has it's utf-8 bit set, this mode will
           behave the same as mode 0, i.e. will not escape anything above 128.

       ocharsetLatin2 = 2
           ISO-8859-2. When a Perl string has it's utf-8 bit set, this mode will behave the same
           as mode 0, i.e. will not escape anything above 128.

   Embperl_Session_Mode
       Env:
           EMBPERL_SESSION_MODE

       Method:
           $request -> config -> session_mode [read only]

       Default:
           smodeUDatCookie = 1

       Since:
           2.0b6

       Specifies how the id for the session data is passed between requests.  Possible values
       are:

       smodeNone = 0
           No session id will be passed

       smodeUDatCookie = 1
           The session id for the user session will be passed via cookie

       smodeUDatParam = 2
           The session id for the user session will append as parameter to any URL and inserted
           as a hidden field in any form.

       smodeUDatUrl = 4
           The session id for the user session will passed as a part of the URL.  NOT YET
           IMPLEMENTED!!

       smodeSDatParam = 0x20
           The session id for the state session will append as parameter to any URL and inserted
           as a hidden field in any form.

       You may add the UDat and SDat values together to get both sorts of sessions, for example
       the value 0x21 will pass the id for the user session inside a cookie and the id for the
       state session as parameters.

   Embperl_Useenv
       Env:
           EMBPERL_USEENV

       Method:
           $component -> config -> use_env [read only]

       Default:
           off unless running as CGI script

       Since:
           2.0b6

       Tells Embperl to scan the enviromemt for configuration settings.

   use_redirect_env
       Method:
           $component -> config -> use_redirect_env [read only]

       Default:
           off unless running as CGI script

       Since:
           2.0b6

       Tells Embperl to scan the enviromemt for configuration settings which has the prefix
       "REDIRECT_". This is normally the case when the request is not the main request, but a
       subrequest.

   Embperl_Package
       Env:
           EMBPERL_PACKAGE

       Method:
           $component -> config -> 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 do not conflict with those of another file.  (Any package's variables will still be
       accessible with explicit package names.)

   Embperl_Debug
       Env:
           EMBPERL_DEBUG

       Method:
           $component -> config -> debug

       See application configuration for an describtion of possible values

   Embperl_Options
       Env:
           EMBPERL_OPTIONS

       Method:
           $component -> config -> options

       This bitmask specifies some options for the execution of Embperl.  To specify multiple
       options, simply add the values together.

       optDisableVarCleanup = 1
           Disables the automatic cleanup of variables at the end of each request.

       optDisableEmbperlErrorPage = 2
           Tells Embperl not to send its own errorpage in case of failure, but instead show 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.

       optReturnError = 262144
           With this option set, Embperl sends no output in case of an error.  It returns the
           error back to Apache or the calling program. When running under mod_perl this gives
           you the chance to use the Apache ErrorDocument directive to show a custom error-
           document. Inside the ErrorDocument you can retrieve the error messages with

             $errors = $req_rec -> prev -> pnotes('EMBPERL_ERRORS') ;

           where $errors is a array reference. (1.3b5+)

       optShowBacktrace = 0x8000000
           When set every error message not only show the sourcefiles, but all files from which
           this file was called by Execute.

       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 "(Safe-)Namespaces
           and opcode restrictions" below for more details.)

       optOpcodeMask = 8
           Tells Embperl to apply an operator mask.  This gives you the chance to disallow
           special (unsafe) opcodes.  (See the Chapter about "(Safe-)Namespaces and opcode
           restrictions" below for more details.)

       optDisableFormData = 256
           This option disables the setup of %fdat and @ffld. Embperl will not do anything with
           the posted form data.  Set this when using Execute from your perl script and you have
           already read the Form Data (via eg. CGI.pm).

       optFormDataNoUtf8 = 0x2000000
           By default Embperl checks all formfields in %fdat if they contain valid UTF-8 strings
           and if yes sets Perl's internals UTF-8 flag.

           If this option is set Embperl will never set the UTF-8 on any data in %fdat.

       optAllFormData = 8192
           This option will cause Embperl to insert all formfields in %fdat and @ffld, even if
           they are empty. Empty formfields will be inserted with an empty string. Without this
           option, empty formfields will be absent from %fdat and @ffld.

       optRedirectStdout = 16384
           Redirects STDOUT to the Embperl output stream before every request and resets it
           afterwards.  If set, you can use a normal Perl print inside any Perl block to output
           data.  Without this option you can only use output data by using the [+ ... +] block,
           or printing to the filehandle OUT.

       optNoHiddenEmptyValue = 65536 (only 1.2b2 and above)
           Normally, if there is a value defined in %fdat for a specific input field, Embperl
           will output a hidden input element for it when you use hidden. When this option is
           set, Embperl will not output a hidden input element for this field when the value is a
           blank string.

       optKeepSpaces = 1048576 (only 1.2b5 and above)           = 0x100000,
           Disable the removal of spaces and empty lines from the output. This is useful for
           sources other than HTML.

       optChdirToSource = 0x10000000 (only 2.5 and above)
           Change current working directory to the directory of the sourcefile, before executing
           the source.

   Embperl_Escmode
       Env:
           EMBPERL_ESCMODE

       Method:
           $component -> config -> escmode

       Default:
           7

       Turn HTML and URL escaping on and off.

       NOTE: If you want to output binary data, you must set the escmode to zero.

       For convenience you can change the escmode inside a page by setting the variable $escmode.

       escXML = 8 (or 15) (2.0b4 and above)
           The result of a Perl expression is always XML-escaped (e.g., `>' becomes `&gt;' and '
           become &apos;).

       escUrl + escHtml = 3 (or 7)
           The result of a Perl expression is HTML-escaped (e.g., `>' becomes `&gt;') in normal
           text and URL-escaped (e.g., `&' becomes `%26') within of "A", "EMBED", "IMG",
           "IFRAME", "FRAME" and "LAYER" tags.

       escUrl = 2 (or 6)
           The result of a Perl expression is always URL-escaped (e.g., `&' becomes `%26').

       escHtml = 1 (or 5)
           The result of a Perl expression is always HTML-escaped (e.g., `>' becomes `&gt;').

       escNode = 0
           No escaping takes place.

       escEscape = 4
           If you add this value to the above Embperl will always perform the escaping. Without
           it is possible to disable escaping by preceding the item that normally is escaped with
           a backslash. While this is a handy thing, it could be very dangerous in situations,
           where content that is inserted by some user is redisplayed, because they can enter
           arbitrary HTML and precede them with a backslash to avoid correct escaping when their
           input is redisplayed again.

       NOTE: You can localize $escmode inside a [+ +] block, e.g. to turn escaping temporary off
       and output $data write

           [+ do { local $escmode = 0 ; $data } +]

   Embperl_Input_Escmode
       Env:
           EMBPERL_INPUT_ESCMODE

       Method:
           $component -> config -> input_escmode [read only]

       Default:
           0

       Since:
           2.0b6

       Tells Embperl how to handle escape sequences that are found in the source.

       0   don't interpret input (default)

       1   unescape html escapes to their characters (i.e. &lt; becomes < ) inside of Perl code

       2   unescape url escapes to their characters (i.e. %26; becomes & ) inside of Perl code

       3   unescape html and url escapes, depending on the context

       Add 4 to remove html tags inside of Perl code. This is helpful when an html editor insert
       html tags like <br> inside your Perl code.

       Set EMBPERL_INPUT_ESCMODE to 7 to get the old default of Embperl < 2.0b6

       Set EMBPERL_INPUT_ESCMODE to 0 to get the old behaviour when optRawInput was set.

   Embperl_Input_Charset
       Env:
           EMBPERL_INPUT_CHARSET

       Method:
           $component -> config -> input_charset

       If set to the value "utf8" the source is interpreted as utf8 encoded so you can use utf8
       literals. It has the same effect as adding "use utf8" to a normal Perl script.

   Embperl_Top_Include
       Env:
           EMBPERL_TOP_INCLUDE

       Method:
           $component -> config -> top_include

       Since:
           2.0b10

       Give a pieces of code that is include at the very top of every file.

       Example:

           Embperl_Top_Include "use MY::Module;"

       This will cause MY::Module to be used in every page. Note that Embperl_Top_Include must
       contain valid Perl code and must be ended with a semicolon.

       NOTE: If you pass top_include as parameter to Execute it is only used in case the code is
       compiled (or recompiled) and not cached.

   Embperl_Cache_Key
       Env:
           EMBPERL_CACHE_KEY

       Method:
           $component -> config -> cache_key [read only]

       Since:
           2.0b1

       literal string that is appended to the cache key

   Embperl_Cache_Key_Options
       Env:
           EMBPERL_CACHE_KEY_OPTIONS

       Method:
           $component -> config -> cache_key_options [read only]

       Default:
           all options set

       Since:
           2.0b1

       Tells Embperl how to create a key for caching of the output

       ckoptPathInfo  = 2
           include the PathInfo into CacheKey

       ckoptQueryInfo = 4
           include the QueryInfo into CacheKey

       ckoptDontCachePost = 8
           don't cache POST requests  (not yet implemented)

   Embperl_Expires_Func
       Env:
           EMBPERL_EXPIRES_FUNC

       Method:
           $component -> config -> expires_func [read only]

       Since:
           2.0b1

       Function that is called every time before data is taken from the cache.  If this function
       returns true, the data from the cache isn't used anymore, but rebuilt.

       Function could be either a coderef (when passed to Execute), a name of a subroutine or a
       string starting with "sub " in which case it is compiled as anonymous subroutine.

       NOTE: If &EXPIRES is defined inside the page, it get evaluated before the excecution of
       the page

   Embperl_Cache_Key_Func
       Env:
           EMBPERL_CACHE_KEY_FUNC

       Method:
           $component -> config -> cache_key_func

       Since:
           2.0b1

       function that should be called when build a cache key. The result is appended to the cache
       key.

   Embperl_Expires_In
       Env:
           EMBPERL_EXPIRES_IN

       Method:
           $component -> config -> expires_in [read only]

       Since:
           2.0b1

       Time in seconds that the output should be cached. (0 = never, -1 = forever)

       NOTE: If $EXPIRES is set inside the page, it get evaluated before the excecution of the
       page

   Embperl_Expires_Filename
       Env:
           EMBPERL_EXPIRES_FILENAME

       Method:
           $component -> config -> expires_filename [read only]

       Since:
           2.0b8

       Cache should be expired when the given file is modified.

   Embperl_Syntax
       Env:
           EMBPERL_SYNTAX

       Method:
           $component -> config -> syntax

       Default:
           Embperl

       Since:
           2.0b1

       Used to tell Embperl which syntax to use inside a page. Embperl comes with the following
       syntaxes:

       EmbperlHTML
           all the HTML tags that Embperl recognizes by default

       EmbperlBlocks
           all the [ ] blocks that Embperl supports

       Embperl
           (default; contains EmbperlHtml and EmbperlBlocks)

       ASP <%  %> and <%=  %>, see perldoc Embperl::Syntax::ASP

       SSI Server Side Includes, see perldoc Embperl::Syntax::SSI

       Perl
           File contains pure Perl (similar to Apache::Registry), but can be used inside
           EmbperlObject

       Text
           File contains only Text, no actions are taken on the Text

       Mail
           Defines the <mail:send> tag, for sending mail. This is an example for a taglib, which
           could be a base for writing your own taglib to extent the number of available tags

       POD translates pod files to XML, which can be converted to the desired output format by an
           XSLT transformation

       RTF Can be used to process word processing documents in RTF format

       You can get a description for each syntax if you type

           perldoc Embperl::Syntax::xxx

       where 'xxx' is the name of the syntax.

       You can also specify multiple syntaxes e.g.

           EMBPERL_SYNTAX "Embperl SSI"

           Execute ({inputfile => '*', syntax => 'Embperl ASP'}) ;

       The 'syntax' metacommand allows you to switch the syntax or to add or subtract syntaxes
       e.g.

           [$ syntax + Mail $]

       will add the Mail taglib so the <mail:send> tag is available after this line.

           [$ syntax - Mail $]

       now the <mail:send> tag is unknown again

           [$ syntax SSI $]

       now you can only use SSI commands inside your page.

   Embperl_Recipe
       Env:
           EMBPERL_RECIPE

       Method:
           $component -> config -> recipe [read only]

       Since:
           2.0b4

       Tells Embperl which recipe to use to process this component

   Embperl_Xsltstylesheet
       Env:
           EMBPERL_XSLTSTYLESHEET

       Method:
           $component -> config -> xsltstylesheet [read only]

       Since:
           2.0b5

       Tell the xslt processor which stylsheet to use.

   Embperl_Xsltproc
       Env:
           EMBPERL_XSLTPROC

       Method:
           $component -> config -> xsltproc [read only]

       Default:
           depends on compiltime options

       Since:
           2.0b5

       Tells Embperl which xslt processor to use. Current "libxslt" and "xalan" are supported by
       Embperl, but they must be compiled in to be available.

Parameters

       Parameters gives addtionaly information about the current request or the execution of the
       current component. So we have two sorts of parameters Request and Component parameters.
       Request parameters are automatically setup by Embperl with information Embperl takes from
       the current running environment. When Embperl is invoked via the "Execute" function, you
       can pass any of the parameters to Execute. Component parameters mainly reflect the
       parameters given to "Execute".

   filename
       Method:
           $request -> param -> filename

       Since:
           2.0b6

       Gives the filename of the file that was actualy requested.  Inside of the applications
       "init" function it can be changed to force Embperl to serve a different file.

   unparsed_uri
       Method:
           $request -> param -> unparsed_uri

       Since:
           2.0b6

       The full unparsed_uri, includeing the query_string and the path_info.

   uri
       Method:
           $request -> param -> uri

       Since:
           2.0b6

       The decoded path of the unparsed_uri.

   server_addr
       Method:
           $request -> param -> server_addr

       Since:
           2.0b9

       URL of the server of the current request in the form schema://addr:port/ e.g.
       http://perl.apache.org/ (port is omitted if it is an default port)

   path_info
       Method:
           $request -> param -> path_info

       Since:
           2.0b6

       The path_info, that is anything in the path after the file the is currently served.

   query_info
       Method:
           $request -> param -> query_info

       Since:
           2.0b6

       Any parameters passed in a GET request after the question mark. The hash %fdat will
       contain these values in a already decoded and easy to use way.  So it's normly more
       convenient to use %fdat instead.

   language
       Method:
           $request -> param -> language

       Since:
           2.0b6

       The primary langange found in the browser "Accept-Language" HTTP header.  This value is
       used for all language-dependent functions inside Embperl.  You can set it change the
       selection of message returned by "$request -&gt; gettext" and "[= =]".

   cookies
       Method:
           $request -> param -> cookies

       Since:
           2.0b6

       A hashref that contains all cookies send by the browser to the server.

   cgi
       Method:
           $request -> param -> cgi [read only]

       Since:
           2.0b12

       Holds the CGI.pm object, which is used for file upload. If no file uploaded data is send
       to the request, this member is undefined.

   inputfile
       Method:
           $component -> param -> inputfile [read only]

       Since:
           1.0.0

       Give the name of the file that should be processed, e.g.

           Execute({inputfile => 'mysource.epl'}) ;

       There is a shortcut when you only need to give the input file and no other parameters. The
       above is will do the same as:

           Execute('mysource.epl') ;

   outputfile
       Method:
           $component -> param -> outputfile [read only]

       Default:
           STDOUT

       Since:
           1.0.0

       Specify a file to which the output should be written. Example:

           Execute({inputfile  => 'mysource.epl',
                    outputfile => 'myoutput.htm'}) ;

   input
       Method:
           $component -> param -> input [read only]

       Since:
           1.0.0

       This parameter is used, when you have the source already in memory.  You should pass a
       reference to a scalar that contains the source.  Addtionaly you should give the inputfile
       parameter, to allow Embperl caching to keep track of different in memory sources.  The
       mtime parameter is used to tell Embperl's cache if the source has change since the last
       call or not. If "mtime" if "undef" or of a different value as it was during the last call,
       the source is considered to be changed and everything is recompiled. Example:

           # Get source from scalar
           # Don't forget to modify mtime if $src changes

           $src = '<html><head><title>Page [+ $no +]</title></head>' ;

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

   output
       Method:
           $component -> param -> output [read only]

       Since:
           1.0.0

       Gives the possibility to write the output into a scalar instead of sending it to stdout or
       a file. You should give a reference to a scalar. Example:

           Execute({inputfile  => 'mysource.epl',
                    output     => \$out}) ;

   sub
       Method:
           $component -> param -> sub [read only]

       Since:
           1.2.0

       Call the given Embperl subroutine defined with "[$sub$]" inside the page.  A shortcut for
       this is to append the name of the subroutine after the filename with a hash sign, so the
       following calls are doing the same thing:

           Execute('mysource.epl#mysub') ;

           Execute({inputfile  => 'mysource.epl',
                    sub        => 'mysub'}) ;

       If you leave out the filename, the sub is called in the current file, so this can only be
       used inside a file that is already processed by Embperl.

   subreq
       Method:
           $component -> param -> subreq

       Since:
           2.0b8, Apache 2.x

       This utilizies Apache 2.0 filters to retrieve the output of a sub-request and uses it as
       input for the current component. For example if you have a CGI-Script and you need to post
       process it via Embperl or simply want to include it's output in another
       Embperl/Embperl::Object document you can write:

           [- Execute ({subreq => '/cgi-bin/script.cgi'}) -]

       NOTE: You have to specify a URI and not a filename!

   import
       Method:
           $component -> param -> import [read only]

       Since:
           1.3.0

       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.

       A value of zero tells Embperl to simply precompile all code found in the page.  (With 2.0
       it is not necessary anymore to do it before using the "sub" parameter on a different
       file).

   firstline
       Method:
           $component -> param -> firstline [read only]

       Default:
           1

       Since:
           1.2.0

       Specifies the first linenumber of the sourcefile.

   mtime
       Method:
           $component -> param -> mtime [read only]

       Default:
           undef

       Since:
           1.0.0

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

   param
       Method:
           $component -> param -> param [read only]

       Since:
           1.0.0

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

           Execute({inputfile  => 'mysource.epl',
                    param      => [1, 2, 3]}) ;
           Execute({inputfile  => 'mysource.epl',
                    param      => \@parameters}) ;

       There is a shortcut, so the following code the aquivalent (NOTE: Don't use a array ref
       here):

           Execute('mysource.epl', 1, 2, 3) ;
           Execute('mysource.epl', @parameters) ;

       The array @param in the Embperl document is setup as an alias to the array.  See
       eg/x/Excute.pl for a more detailed example.

   fdat
       Method:
           $component -> param -> fdat [read only]

       Since:
           1.0.0

       Pass a hash reference to customly set %fdat. If "ffld" is not given, "ffld" will be set to
       "keys %fdat".

   ffld
       Method:
           $component -> param -> ffld [read only]

       Since:
           1.0.0

       Pass a array reference to customly set @fdat. Does not affect %fdat.

   object
       Method:
           $component -> param -> object [read only]

       Since:
           1.3.2

       Takes a filename and returns an hashref that is blessed into the package of the given
       file. That's useful, 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.
       Additionally you can use the returned hashref to store data for that object. Example:

         [# 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
       Method:
           $component -> param -> isa [read only]

       Since:
           1.3.2

       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 useful within Embperl::Object.  Example:

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

   errors
       Method:
           $component -> param -> errors [read only]

       Since:
           1.3.0

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

   xsltparam
       Method:
           $component -> param -> xsltparam

       Default:
           %fdat

       Since:
           2.0b6

       Takes a reference to hash which contains key/value pair that are accessible inside the
       stylesheet via <xsl:param>.

Embperl's Objects

       There are three major objects in Embperl: application, request and component.  Each of
       these objects can be used to get information about the processing and control the
       execution. Each of these objects has a config sub-object, which makes the configuration
       accessible and, where possible, changeable at runtime. The "config" method of these three
       objects returns a reference to the configuration object. The methods of these
       configurations objects are described in the section Configuration.  The request and the
       component object have addtionaly a parameter sub-object, which holds parameters passed to
       the current request/component. The "param" method of these two objects returns the
       parameter sub-object. The methods of these parameter objects can be found in the section
       Parameters.  Addtionaly each of the three major objects has a set of own methods, which
       are described here.

   thread
       Method:
           $application -> thread [read only]

       Since:
           2.0b6

       Returns a reference to a object which hold per threads information. There is only one such
       object per thread.

   curr_req
       Method:
           $application -> curr_req [read only]

       Since:
           2.0b6

       Returns a reference to the current request object i.e. the object of the request currently
       running.

   config
       Method:
           $application -> config [read only]

       Since:
           2.0b6

       Returns a reference to the configuration object of the application. See section
       Configuration.

   user_session
       Method:
           $application -> user_session [read only]

       Since:
           2.0b6

       Returns a reference to the user session object.

   state_session
       Method:
           $application -> state_session [read only]

       Since:
           2.0b6

       Returns a reference to the state session object.

   app_session
       Method:
           $application -> app_session [read only]

       Since:
           2.0b6

       Returns a reference to the application session object.

   udat
       Method:
           $application -> udat [read only]

       Since:
           2.0b6

       Returns a reference to a hash which contains the data of the user session.  This has can
       be used to access and modify user session data. It's the same as accessing the global
       %udat.

   sdat
       Method:
           $application -> sdat [read only]

       Since:
           2.0b6

       Returns a reference to a hash which contains the data of the state session.  This has can
       be used to access and modify state session data. It's the same as accessing the global
       %sdat.

   mdat
       Method:
           $application -> mdat [read only]

       Since:
           2.0b6

       Returns a reference to a hash which contains the data of the application session.  This
       has can be used to access and modify application session data. It's the same as accessing
       the global %mdat.

   errors_count
       Method:
           $application -> errors_count

       Since:
           2.0b6

       Contains the number of errors since last time send per mail. See also mail_errors_to.

   errors_last_time
       Method:
           $application -> errors_last_time

       Since:
           2.0b6

       Time when the last error has occurred.  See also mail_errors_to.

   errors_last_send_time
       Method:
           $application -> errors_last_send_time

       Since:
           2.0b6

       Time when the last mail with error messages was sent.  See also mail_errors_to.

   apache_req
       Method:
           $request -> apache_req [read only]

       Since:
           2.0b6

       Returns a reference to mod_perls Apache request object. In mod_perl 1 this is of type
       "Apache::" in mod_perl 2 it's a "Apache2::RequestRec".

   config
       Method:
           $request -> config [read only]

       Since:
           2.0b6

       Returns a reference to the configuration object of the request. See section Configuration.

   param
       Method:
           $request -> param [read only]

       Since:
           2.0b6

       Returns a reference to the parameter object of the request. See section Parameters.

   component
       Method:
           $request -> component [read only]

       Since:
           2.0b6

       Returns a reference to the object of component currently running. See component methods
       below.

   app
       Method:
           $request -> app [read only]

       Since:
           2.0b6

       Returns a reference to the object of application to which the current request belongs.
       See application methods above.

   thread
       Method:
           $request -> thread [read only]

       Since:
           2.0b6

       Returns a reference to a object which hold per threads information. There is only one such
       object per thread.

   request_count
       Method:
           $request -> request_count [read only]

       Since:
           2.0b6

       Returns the number of request handled so far by this child process.

   request_time
       Method:
           $request -> request_time [read only]

       Since:
           2.0b6

       Start time of the current request.

   session_mgnt
       Method:
           $request -> session_mgnt [read only]

       Since:
           2.0b6

       Set to true if session management is available.

   session_id
       Method:
           $request -> session_id [read only]

       Since:
           2.0b6

       Combined id of current user and state session.

   session_state_id
       Method:
           $request -> session_state_id [read only]

       Since:
           2.0b6

       Id of the current state session as received by the browser, this means this method returns
       "undef" for a new session.

   session_user_id
       Method:
           $request -> session_user_id [read only]

       Since:
           2.0b6

       Id of the current user session as received by the browser, this means this method returns
       "undef" for a new session.

   cookie_expires
       Method:
           $request -> cookie_expires

       Since:
           2.1.1

       Can be used to retrieve the actual expiration date that Embperl uses for the cookie with
       the session id.

   had_exit
       Method:
           $request -> had_exit [read only]

       Since:
           2.0b6

       True if exit was called in one of the components processed so far.

   log_file_start_pos
       Method:
           $request -> log_file_start_pos [read only]

       Since:
           2.0b6

       File possition of the log file at the time when the request has started.

   error
       Method:
           $request -> error

       Since:
           2.0b6

       True if there were any error during the request.

   errors
       Method:
           $request -> errors

       Since:
           2.0b6

       Reference to an array which holds all error messages occurred so far.

   errdat1
       Method:
           $request -> errdat1

       Since:
           2.0b6

       Additional information passed to the error handler when an error is reported.

   errdat2
       Method:
           $request -> errdat2

       Since:
           2.0b6

       Additional information passed to the error handler when an error is reported.

   lastwarn
       Method:
           $request -> lastwarn

       Since:
           2.0b6

       Last warning message.

   errobj
       Method:
           $request -> errobj

       Since:
           2.0rc3

       The object passed to the last die, if any.  This is useful when you pass an object to die
       inside an Execute. After the Execute you can check $epreq -> errobj, to get the object.
       The object is also push to the array passed to the errors parameter of Execute.

   cleanup_vars
       Method:
           $request -> cleanup_vars

       Since:
           2.0b6

       Reference to an array which is filled with references to variables that should be cleaned
       up after the request. You can add your own variables that needs cleanup here, but you
       should never remove any variables from this array.

   cleanup_packages
       Method:
           $request -> cleanup_packages

       Since:
           2.0b6

       Reference to a hash which contains all packages that must be cleaned up after the request.

   initial_cwd
       Method:
           $request -> initial_cwd [read only]

       Since:
           2.0b6

       Working directory when the request started.

   messages
       Method:
           $request -> messages

       Since:
           2.0b6

       Reference to an array of hashs of messages. This is used by Embperl to translate message
       into different languages. When a "[= =]" block is processed or $request -> gettext is
       called, Embperl searches this array. It starts from the first element in the array (each
       element in the array must be a hashref) and tries to lookup the text for the given symbol
       in hash. When it fails it goes to the next array element. This way you can setup multiple
       translation tables that are search for the symbol. Example:

           %messages =
               (
               'de' =>
                   {
                   'addsel1' => 'Klicken Sie auf die Kategorie zu der Sie etwas hinzufügen möchten:',
                   'addsel2' => 'oder fügen Sie eine neue Kategorie hinzu. Bitte geben Sie die Beschreibung in so vielen Sprachen wie Ihnen möglich ein.',
                   'addsel3' => 'Falls Sie die Übersetzung nicht wissen, lassen Sie das entsprechende Eingabefeld leer.',
                   'addsel4' => 'Kategorie hinzufügen',
                   },
                'en' =>
                   {
                   'addsel1' => 'Click on the category for which you want to add a new item:',
                   'addsel2' => 'or add new category. Please enter the description in as much languages as possible.',
                   'addsel3' => 'If you don\'t know the translation leave the corresponding input field empty.',
                   'addsel4' => 'Add category',
                   }
               ) ;

           $lang = $request -> param -> language ;
           push @{$request -> messages}, $messages{$lang} ;
           push @{$request -> default_messages}, $messages{'en'} if ($lang ne 'en') ;

       "$request -" param -> language> retrieves the language as given by the browser language-
       accept header (or set before in your program). Then it pushes the german or english
       messages hash onto the message array. Addtionaly it pushes the english messages on the
       default_messages array. Messages will be taken from this array if nothing can be found in
       the messages array.

   default_messages
       Method:
           $request -> default_messages

       Since:
           2.0b6

       Reference to an array with default messages. Messages will be taken from this array if
       nothing can be found in the messages array.

   config
       Method:
           $component -> config [read only]

       Since:
           2.0b6

       Returns an reference to the configuration object of the component.

   param
       Method:
           $component -> param [read only]

       Since:
           2.0b6

       Returns an reference to the parameter object of the component.

   req_running
       Method:
           $component -> req_running [read only]

       Since:
           2.0b6

       True if Embperl is inside of the execution of the request.

   sub_req
       Method:
           $component -> sub_req [read only]

       Since:
           2.0b6

       True is this is not the outermost Embperl component, i.e. this component is called from
       within another component.

   inside_sub
       Method:
           $component -> inside_sub [read only]

       Since:
           2.0b6

       True is we are inside a Embperl subroutine ([$ sub $] ... [$ endsub $])

   had_exit
       Method:
           $component -> had_exit [read only]

       Since:
           2.0b6

       True if the exit was called during the excution of the component.

   path_ndx
       Method:
           $component -> path_ndx [read only]

       Since:
           2.0b6

       Tells Embperl how much parts of the path should be ignored when searching through the
       path.

   cwd
       Method:
           $component -> cwd [read only]

       Since:
           2.0b6

       Directory of the source file of the component.

   sourcefile
       Method:
           $component -> sourcefile [read only]

       Since:
           2.0b6

       Source file of the component.

   syntax
       Method:
           $component -> syntax

       Since:
           2.0b6

       Syntax of the component

   prev
       Method:
           $component -> prev [read only]

       Since:
           2.0b6

       Previous component, e.g. the component which called this component.

   import_stash
       Method:
           $component -> import_stash [read only]

       Since:
           2.0b6

       While importing a component this is set to the stash to which symbols are imported.
       "undef" during normal execution.

   exports
       Method:
           $component -> exports

       Since:
           2.0b6

       Symbols that should be exported by this component.

   curr_package
       Method:
           $component -> curr_package [read only]

       Since:
           2.0b6

       Name of the package the component is executed in.

   code
       Method:
           $component -> code

       Since:
           2.0b6

       Only valid during compile phase. Can used to retrieve and modify the code Embperl is
       generating. See Embperl::Syntax for more details and Embperl::Syntax::RTF for an example.