.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Config 3pm"
.TH Config 3pm "2020-11-09" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Embperl::Config \- Embperl configuration and calling
.SH "Operating-Modes"
.IX Header "Operating-Modes"
Embperl can operate in one of four modes:
.IP "mod_perl" 4
.IX Item "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.
.IP "CGI/FastCGI" 4
.IX Item "CGI/FastCGI"
When you want to run Embperl on a machine that doesn't have mod_perl, you
can run Embperl also as normal \s-1CGI\s0 script. Due to the overhead of \s-1CGI,\s0
this mode is much slower. To get a better performance you should consider
using Embperl together with FastCGI. (http://www.fastcgi.com).
.IP "Offline" 4
.IX Item "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.
.IP "Call it from other Perl programs" 4
.IX Item "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.
.SS "mod_perl"
.IX Subsection "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 \fIhttpd.conf\fR to load Embperl and add \f(CW\*(C`Embperl\*(C'\fR
as the \f(CW\*(C`PerlHandler\*(C'\fR. The following directives will cause all file with extetion \fIepl\fR
to be handled by Embperl:
.PP
.Vb 1
\& PerlModule Embperl
\&
\& AddType text/html .epl
\&
\&
\& SetHandler perl\-script
\& PerlHandler Embperl
\& Options ExecCGI
\&
.Ve
.PP
Another possibility is to have all files under a special location processed by Embperl:
.PP
.Vb 1
\& PerlModule Embperl
\&
\& Alias /embperl /path/to/embperl/eg
\&
\&
\& SetHandler perl\-script
\& PerlHandler Embperl
\& Options ExecCGI
\&
.Ve
.PP
In this setup you should make sure that non Embperl files like images doesn't served
from this directory.
.PP
For \fBmod_perl 2.0\fR 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 \fIEmbperl.so\fR on Windows it is called \f(CW\*(C`Embperl.dll\*(C'\fR.
Now add the following line to your httpd.conf \fBbefore\fR any of the Embperl configuration
directives, but \fBafter\fR \fImod_perl.so\fR is loaded:
.PP
.Vb 1
\& LoadModule embperl_module /path/to/perl/site/lib/Embperl/Embperl.so
.Ve
.PP
To use \fIEmbperl::Object\fR you use the \f(CW\*(C`Embperl::Object\*(C'\fR as \f(CW\*(C`PerlHandler\*(C'\fR:
.PP
.Vb 8
\&
\& Embperl_AppName unique\-name
\& Embperl_Object_Base base.htm
\& Embperl_UriMatch "\e.htm.?|\e.epl$"
\& SetHandler perl\-script
\& PerlHandler Embperl::Object
\& Options ExecCGI
\&
.Ve
.PP
Addtionaly you can setup other parameters for \fIEmbperl::Object\fR. If you do so
inside a container (like \f(CW\*(C`, >) you need to
set \f(CW\*(C`Embperl_AppName\*(C'\fR to a unique-name (the actual value doesn't matter).
The \f(CW\*(C`Embperl_UriMatch\*(C'\fR makes sure that only files of the requested type are
served by \fIEmbperl::Object\fR, while all others are served by Apache as usual.
.PP
For more information see: \*(L"perldoc Embperl::Object\*(R".
.PP
Embperl accepts a lot of configuration directives to customize it's behaviour. See the next
section for a description.
.PP
\&\fB\s-1NOTE:\s0\fR If mod_perl is statically linked into Apache you can not use \fBClearModuleList\fR
in your httpd.conf
.PP
\fIPreloading pages\fR
.IX Subsection "Preloading pages"
.PP
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.
.PP
To let Embperl preload your files, you have to supply all the filename into the
key \fBpreloadfiles\fR of the hash \fB\f(CB%initparam\fB\fR, \fBbefore\fR you load Embperl.
.PP
Example:
.PP
.Vb 9
\& BEGIN
\& {
\& $Embperl::initparam{preloadfiles} =
\& [
\& \*(Aq/path/to/foo.epl\*(Aq,
\& \*(Aq/path/to/bar.epl\*(Aq,
\& { inputfile => "/path/to/other.epl", input_escmode => 7 },
\& ] ;
\& }
\&
\& use Embperl ;
.Ve
.PP
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).
.PP
\&\fB\s-1NOTE:\s0\fR Preloading is not supported under Apache 1.3, when mod_perl is
loaded as \s-1DSO.\s0 To use preloading under Apache 1.3 you need to compile
mod_perl statically into Apache.
.SS "CGI/FastCGI"
.IX Subsection "CGI/FastCGI"
To use this mode you must copy \fBembpcgi.pl\fR to your cgi-bin
directory. You can invoke it with the \s-1URL\s0
http://www.domain.xyz/cgi\-bin/embpcgi.pl/url/of/your/document.
.PP
The /url/of/your/document will be passed to Embperl by the web server.
Normal processing (aliasing, etc.) takes place before the \s-1URI\s0 makes it
to \s-1PATH_TRANSLATED.\s0
.PP
If you are running the Apache httpd, you can also define
\&\fBembpcgi.pl\fR as a handler for a specific file extension or
directory.
.PP
Example of Apache \f(CW\*(C`httpd.conf\*(C'\fR:
.PP
.Vb 3
\&
\& Action text/html /cgi\-bin/embperl/embpcgi.pl
\&
.Ve
.PP
\&\fB\s-1NOTE\s0\fR: Via \s-1CGI\s0 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.
.PP
For \fIEmbperl::Object\fR you have to use \fIepocgi.pl\fR instead of \fIembpcgi.pl\fR.
.PP
You can also run Embperl with \fBFastCGI\fR, in this case use embpfastcgi.pl
as cgi script. You must have \s-1FCGI\s0.pm installed.
.SS "Offline"
.IX Subsection "Offline"
Run Embperl from the comannd line use \fIembpexec.pl\fR on unix and \fIembpexec.bat\fR on windows:
.PP
\&\fBembpexec.pl [options] htmlfile [query_string]\fR
.PP
\&\fBembpexec.bat [options] htmlfile [query_string]\fR
.IP "\fBhtmlfile\fR" 4
.IX Item "htmlfile"
The full pathname of the source file which should be processed by
Embperl.
.IP "\fBquery_string\fR" 4
.IX Item "query_string"
Optional. Has the same meaning as the environment variable
\&\s-1QUERY_STRING\s0 when invoked as a \s-1CGI\s0 script. That is, \s-1QUERY_STRING\s0
contains everything following the first \*(L"?\*(R" in a \s-1URL.\s0
should be URL-encoded. The default is no query string.
.PP
Options:
.IP "\-o outputfile" 4
.IX Item "-o outputfile"
Optional. Gives the filename to which the output is written. The
default is stdout.
.IP "\-l logfile" 4
.IX Item "-l logfile"
Optional. Gives the filename of the logfile. The default is
\&\fI/tmp/embperl.log\fR on unix and \fI\eembperl.log\fR on windows.
.IP "\-d debugflags" 4
.IX Item "-d debugflags"
Optional. Specifies the level of debugging (what is written to the
log file). The default is nothing. See \*(L"\s-1EMBPERL_DEBUG\*(R"\s0 for exact values.
.IP "\-t options" 4
.IX Item "-t options"
See \*(L"\s-1EMBPERL_OPTIONS\*(R"\s0 for option values.
.IP "\-s syntax" 4
.IX Item "-s syntax"
Defines the syntax of the source. See See \*(L"\s-1EMBPERL_SYNTAX\*(R"\s0
.IP "\-p param" 4
.IX Item "-p param"
Gives a value which is passed in the \f(CW@param\fR array to the executed page.
Can be given multiple times.
.IP "\-f fdat value" 4
.IX Item "-f fdat value"
Gives a name/value pair which is passed in the \f(CW%fdat\fR hash to the executed page.
Can be given multiple times.
.SS "By calling Embperl::Execute (\e%param)"
.IX Subsection "By calling Embperl::Execute (%param)"
\&\f(CW\*(C`Execute\*(C'\fR can be used to call Embperl from your own modules/scripts (for example
from a Apache::Registry or \s-1CGI\s0 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).
.PP
(See \fBeg/x/Excute.pl\fR for more detailed examples)
.PP
When you want to use \fIEmbperl::Object\fR call \f(CW\*(C`Embperl::Object::Execute\*(C'\fR, when you
want \fIEmbperl::Mail\fR, call \f(CW\*(C`Embperl::Mail::Execute\*(C'\fR.
.PP
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.
.PP
.Vb 1
\& Execute($filename, $p1, $p2, $pn) ;
.Ve
.PP
This will cause Embperl to interpret the file with the name \f(CW$filename\fR and, if specified, pass
any additional parameters in the array \f(CW@param\fR (just like \f(CW@_\fR in a Perl subroutine).
The above example could also be written in the long form:
.PP
.Vb 2
\& Execute ({inputfile => $filename,
\& param => [$p1, $p2, $pn]}) ;
.Ve
.PP
The possible items for hash of the long form are are descriped in the
configuration section and parameter section.
.PP
\fI\s-1EXAMPLES\s0 for Execute:\fR
.IX Subsection "EXAMPLES for Execute:"
.PP
.Vb 2
\& # Get source from /path/to/your.html and
\& # write output to /path/to/output\*(Aq
\&
\& Embperl::Execute ({ inputfile => \*(Aq/path/to/your.html\*(Aq,
\& outputfile => \*(Aq/path/to/output\*(Aq}) ;
\&
\&
\& # Get source from scalar and write output to stdout
\& # Don\*(Aqt forget to modify mtime if $src changes
\&
\& $src = \*(AqPage [+ $no +]\*(Aq ;
\&
\& Embperl::Execute ({ inputfile => \*(Aqsome name\*(Aq,
\& input => \e$src,
\& mtime => 1 }) ;
\&
\& # Get source from scalar and write output to another scalar
\&
\& my $src = \*(AqPage [+ $no +]\*(Aq ;
\& my $out ;
\&
\& Embperl::Execute ({ inputfile => \*(Aqanother name\*(Aq,
\& input => \e$src,
\& mtime => 1,
\& output => \e$out }) ;
\&
\& print $out ;
\&
\&
\& # Include a common header in an Embperl page,
\& # which is stored in /path/to/head.html
\&
\& [\- Execute (\*(Aq/path/to/head.html\*(Aq) \-]
.Ve
.SS "Debugging"
.IX Subsection "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.
.PP
You can use the Perl interacive command line debugger via
.PP
.Vb 1
\& perl \-d embpexec.pl file.epl
.Ve
.PP
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:
.PP
.Vb 1
\& ddd \-\-debugger \*(Aqperl \-d embpexec.pl file.epl\*(Aq
.Ve
.PP
\&\s-1NOTE:\s0 embpexec.pl could be found in the Embperl source directory
.PP
If you want to debug your pages, while running under mod_perl, Apache::DB is the
right thing. Apache::DB is available from \s-1CPAN.\s0
.SH "Configuration"
.IX Header "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 \fIhttpd.conf\fR.
When you run Embperl as \s-1CGI\s0 it takes the configuration from environment variables.
For compatibility reason that
can also be turned on under mod_perl, by adding \f(CW\*(C`Embperl_UseEnv on\*(C'\fR in your
\&\fIhttpd.conf\fR. When you call Embperl from another Perl program, by calling
the \f(CW\*(C`Execute\*(C'\fR function, you can pass your configuration along with other parameters
as a hash reference. If you pass \f(CW\*(C`use_env =< 1\*(C'\fR 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.
.PP
You can not only pass configuration in different ways, there are also three different
contexts: \fIApplication\fR, \fIRequest\fR and \fIComponent\fR.
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.
.PP
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.
.PP
Configuration for components can be setup before the request, but can also be passed
as argument when you call the component via \f(CW\*(C`Execute\*(C'\fR.
.SS "Embperl_Useenv"
.IX Subsection "Embperl_Useenv"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_USEENV\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> use_env \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
off unless running as \s-1CGI\s0 script
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Tells Embperl to scan the enviromemt for configuration settings.
.SS "use_redirect_env"
.IX Subsection "use_redirect_env"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> use_redirect_env \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
off unless running as \s-1CGI\s0 script
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Tells Embperl to scan the enviromemt for configuration settings which has the
prefix \f(CW\*(C`REDIRECT_\*(C'\fR. This is normally the case when the request is not the main request,
but a subrequest.
.SS "Embperl_Appname"
.IX Subsection "Embperl_Appname"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_APPNAME\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> app_name \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
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.
.SS "Embperl_App_Handler_Class"
.IX Subsection "Embperl_App_Handler_Class"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_APP_HANDLER_CLASS\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> app_handler_class \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Embperl will call the \f(CW\*(C`init\*(C'\fR 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.
.SS "Embperl_Session_Handler_Class"
.IX Subsection "Embperl_Session_Handler_Class"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_SESSION_HANDLER_CLASS\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> session_handler_class \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
Apache::SessionX
.IP "Since:" 4
.IX Item "Since:"
1.3b3
.IP "See also:" 4
.IX Item "See also:"
Session Handling
.PP
Set the class that performs the Embperl session handling. This gives you
the possibility to implement your own session handling.
.PP
\&\s-1NOTE:\s0 Default until
1.3.3 was \f(CW\*(C`HTML::Embperl::Session\*(C'\fR, starting with 1.3.4 it is
\&\f(CW\*(C`Apache::SessionX\*(C'\fR. To get the old session behaviour set it to
\&\f(CW\*(C`HTML::Embperl::Session\*(C'\fR.
.SS "Embperl_Session_Args"
.IX Subsection "Embperl_Session_Args"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_SESSION_ARGS\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> session_args \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
1.3b3
.IP "See also:" 4
.IX Item "See also:"
Session Handling
.PP
List of arguments for Apache::Session classes
Arguments that contains spaces can be quoted.
Example:
.PP
.Vb 1
\& EMBPERL_SESSION_ARGS "DataSource=dbi:mysql:session UserName=www \*(AqPassword=secret word\*(Aq"
.Ve
.SS "Embperl_Session_Classes"
.IX Subsection "Embperl_Session_Classes"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_SESSION_CLASSES\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> session_classes \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
1.3b3
.IP "See also:" 4
.IX Item "See also:"
Session Handling
.PP
Space separated list of object store and lock manager
(and optionally the serialization and id generating class)
for Apache::Session (see \*(L"Session handling\*(R")
.SS "Embperl_Session_Config"
.IX Subsection "Embperl_Session_Config"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_SESSION_CONFIG\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> session_config \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
given when running Makefile.PL of Apache::SessionX
.IP "Since:" 4
.IX Item "Since:"
1.3.3
.IP "See also:" 4
.IX Item "See also:"
Session Handling
.PP
Selects a session configuration from the configurations you have defined when running
\&\fIApache::SessionX\fR's \f(CW\*(C`Makefile.PL\*(C'\fR.
.PP
\&\s-1NOTE:\s0 Use either \f(CW\*(C`EMBPERL_SESSION_CONFIG\*(C'\fR or \f(CW\*(C`EMBPERL_SESSION_ARGS\*(C'\fR and \f(CW\*(C`EMBPERL_SESSION_CLASSES\*(C'\fR
.SS "Embperl_Cookie_Name"
.IX Subsection "Embperl_Cookie_Name"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_COOKIE_NAME\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> cookie_name \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
\&\s-1EMBPERL_UID\s0
.IP "Since:" 4
.IX Item "Since:"
1.2b4
.IP "See also:" 4
.IX Item "See also:"
Session Handling
.PP
Set the name that Embperl uses when it sends the cookie with the session id.
.SS "Embperl_Cookie_Domain"
.IX Subsection "Embperl_Cookie_Domain"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_COOKIE_DOMAIN\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> cookie_domain \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
none
.IP "Since:" 4
.IX Item "Since:"
1.2b4
.IP "See also:" 4
.IX Item "See also:"
Session Handling
.PP
Set the domain that Embperl uses for the cookie with the session id.
.SS "Embperl_Cookie_Path"
.IX Subsection "Embperl_Cookie_Path"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_COOKIE_PATH\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> cookie_path \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
none
.IP "Since:" 4
.IX Item "Since:"
1.2b4
.IP "See also:" 4
.IX Item "See also:"
Session Handling
.PP
Set the path that Embperl uses for the cookie with the session id.
.SS "Embperl_Cookie_Expires"
.IX Subsection "Embperl_Cookie_Expires"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_COOKIE_EXPIRES\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> cookie_expires \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
at the end of the session
.IP "Since:" 4
.IX Item "Since:"
1.3b5
.IP "See also:" 4
.IX Item "See also:"
Session Handling
.PP
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:
.PP
.Vb 8
\& +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
.Ve
.SS "Embperl_Cookie_Secure"
.IX Subsection "Embperl_Cookie_Secure"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_COOKIE_SECURE\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> cookie_secure \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
at the end of the session
.IP "Since:" 4
.IX Item "Since:"
2.0b9
.IP "See also:" 4
.IX Item "See also:"
Session Handling
.PP
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.
.SS "Embperl_Log"
.IX Subsection "Embperl_Log"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_LOG\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> log \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
Unix: /tmp/embperl.log Windows: /embperl.log
.PP
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 \*(L"\s-1EMBPERL_DEBUG\*(R"\s0 below). The log output is intended to show what
your embedded Perl code is doing and to help debug it.
.SS "Embperl_Debug"
.IX Subsection "Embperl_Debug"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_DEBUG\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> debug
.PP
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 \fIEmbperl::Constant\fR.
The following values are defined:
.IP "dbgStd = 1 (0x1)" 4
.IX Item "dbgStd = 1 (0x1)"
Show minimum information.
.IP "dbgMem = 2 (0x2)" 4
.IX Item "dbgMem = 2 (0x2)"
Show memory and scalar value allocation.
.IP "dbgEval = 4 (0x4)" 4
.IX Item "dbgEval = 4 (0x4)"
Show arguments to and results of evals.
.IP "dbgEnv = 16 (0x10)" 4
.IX Item "dbgEnv = 16 (0x10)"
List every request's environment variables.
.IP "dbgForm = 32 (0x20)" 4
.IX Item "dbgForm = 32 (0x20)"
List posted form data.
.IP "dbgInput = 128 (0x80)" 4
.IX Item "dbgInput = 128 (0x80)"
Show processing of \s-1HTML\s0 input tags.
.IP "dbgFlushOutput = 256 (0x100)" 4
.IX Item "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.
.IP "dbgFlushLog = 512 (0x200)" 4
.IX Item "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.
.IP "dbgLogLink = 8192 (0x2000)" 4
.IX Item "dbgLogLink = 8192 (0x2000)"
This feature is not yet implemented in Embperl 2.0!
.Sp
Inserts a link at the top of each page which can be used to view the
log for the current \s-1HTML\s0 file. See also \*(L"\s-1EMBPERL_VIRTLOG\*(R"\s0.
.Sp
Example:
.Sp
.Vb 2
\& EMBPERL_DEBUG 10477
\& EMBPERL_VIRTLOG /embperl/log.htm
\&
\&
\& SetHandler perl\-script
\& PerlHandler Embperl
\& Options ExecCGI
\&
.Ve
.IP "dbgDefEval = 16384 (0x4000)" 4
.IX Item "dbgDefEval = 16384 (0x4000)"
Shows every time new Perl code is compiled.
.IP "dbgHeadersIn = 262144 (0x40000)" 4
.IX Item "dbgHeadersIn = 262144 (0x40000)"
Log all \s-1HTTP\s0 headers which are sent from and to the browser.
.IP "dbgShowCleanup = 524288 (0x80000)" 4
.IX Item "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.
.IP "dbgSession = 2097152 (0x200000)" 4
.IX Item "dbgSession = 2097152 (0x200000)"
Enables logging of session transactions.
.IP "dbgImport = 4194304 (0x400000)" 4
.IX Item "dbgImport = 4194304 (0x400000)"
Show how subroutines are imported in other namespaces.
.IP "dbgOutput = 0x08000" 4
.IX Item "dbgOutput = 0x08000"
Logs the process of converting the internal tree strcuture to plain text for output
.IP "dbgDOM = 0x10000" 4
.IX Item "dbgDOM = 0x10000"
Logs things related to processing the internal tree data structure of documents
.IP "dbgRun = 0x20000" 4
.IX Item "dbgRun = 0x20000"
Logs things related to execution of a document
.IP "dbgBuildToken = 0x800000" 4
.IX Item "dbgBuildToken = 0x800000"
Logs things related to creating the token tables for source parsing
.IP "dbgParse = 0x1000000" 4
.IX Item "dbgParse = 0x1000000"
Logs the parseing of the source
.IP "dbgObjectSearch = 0x2000000" 4
.IX Item "dbgObjectSearch = 0x2000000"
Shows how Embperl::Objects searches sourcefiles
.IP "dbgCache = 0x4000000" 4
.IX Item "dbgCache = 0x4000000"
Logs cache related things
.IP "dbgCompile = 0x8000000" 4
.IX Item "dbgCompile = 0x8000000"
Gives information about compiling the parsed source to Perl code
.IP "dbgXML = 0x10000000" 4
.IX Item "dbgXML = 0x10000000"
Logs things related to \s-1XML\s0 processing
.IP "dbgXSLT = 0x20000000" 4
.IX Item "dbgXSLT = 0x20000000"
Logs things related to \s-1XSLT\s0 processing
.IP "dbgCheckpoint = 0x40000000" 4
.IX Item "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.
.SS "Embperl_Maildebug"
.IX Subsection "Embperl_Maildebug"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_MAILDEBUG\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> maildebug
.IP "Since:" 4
.IX Item "Since:"
1.2.1
.PP
Debug value pass to Net::SMTP.
.SS "Embperl_Mailhost"
.IX Subsection "Embperl_Mailhost"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_MAILHOST\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> mailhost
.IP "Default:" 4
.IX Item "Default:"
localhost
.PP
Specifies which host the mail related functions of Embperl uses as \s-1SMTP\s0 server.
.SS "Embperl_Mailhelo"
.IX Subsection "Embperl_Mailhelo"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_MAILHELO\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> mailhelo
.IP "Default:" 4
.IX Item "Default:"
chosen by Net::SMTP
.IP "Since:" 4
.IX Item "Since:"
1.3b4
.PP
Specifies which host/domain all mailrealted function uses
in the \s-1HELO/EHLO\s0 command.
A reasonable default is normally chosen by \fINet::SMTP\fR, but
depending on your installation it may necessary to set it
manualy.
.SS "Embperl_Mailfrom"
.IX Subsection "Embperl_Mailfrom"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_MAILFROM\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> mailfrom
.IP "Default:" 4
.IX Item "Default:"
www\-server@
.IP "Since:" 4
.IX Item "Since:"
1.2.1
.PP
Specifies the email address that is used as sender all mailrelted function.
.SS "Embperl_Mail_Errors_To"
.IX Subsection "Embperl_Mail_Errors_To"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_MAIL_ERRORS_TO\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> mail_errors_to
.PP
If set all errors will be send to the email address given.
.SS "Embperl_Mail_Errors_Limit"
.IX Subsection "Embperl_Mail_Errors_Limit"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_MAIL_ERRORS_LIMIT\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> mail_errors_limit \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Do not mail more then errors. Set to 0 for no limit.
.SS "Embperl_Mail_Errors_Reset_Time"
.IX Subsection "Embperl_Mail_Errors_Reset_Time"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_MAIL_ERRORS_RESET_TIME\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> mail_errors_reset_time \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Reset error counter if for seconds no error has occurred.
.SS "Embperl_Mail_Errors_Resend_Time"
.IX Subsection "Embperl_Mail_Errors_Resend_Time"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_MAIL_ERRORS_RESEND_TIME\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> mail_errors_resend_time \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Mail errors of seconds regardless of the error counter.
.SS "Embperl_Object_Base"
.IX Subsection "Embperl_Object_Base"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_OBJECT_BASE\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> object_base \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
_base.epl
.IP "Since:" 4
.IX Item "Since:"
1.3b1
.PP
Name of the base page that Embperl::Objects searches for.
.SS "Embperl_Object_App"
.IX Subsection "Embperl_Object_App"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_OBJECT_APP\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> object_app
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
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 \f(CW@ISA\fR 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.
.SS "Embperl_Object_Addpath"
.IX Subsection "Embperl_Object_Addpath"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_OBJECT_ADDPATH\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> object_addpath
.IP "Since:" 4
.IX Item "Since:"
1.3b1
.PP
Additional directories where Embperl::Object searches for pages.
.PP
This search through the searchpath is always performed if in a call to
Execute no path for the file is given.
.PP
In \fIhttpd.conf\fR or as environment variable directories are
separated by \f(CW\*(C`;\*(C'\fR (on Unix \f(CW\*(C`:\*(C'\fR works also). The parameter for \f(CW\*(C`Execute\*(C'\fR and
the application object method expects/returns an array reference.
This path is
\&\fBalways\fR appended to the searchpath.
.SS "Embperl_Object_Reqpath"
.IX Subsection "Embperl_Object_Reqpath"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_OBJECT_REQPATH\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> object_reqpath
.IP "Since:" 4
.IX Item "Since:"
2.0b12
.PP
Additional directories where Embperl::Object searches for files for the initial request.
.PP
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 \fBnot\fR to files called via
Execute.
.PP
In \fIhttpd.conf\fR or as environment variable directories are
separated by \f(CW\*(C`;\*(C'\fR (on Unix \f(CW\*(C`:\*(C'\fR works also). The parameter for \f(CW\*(C`Execute\*(C'\fR and
the application object method expects/returns an array reference.
.PP
Example:
.PP
if you say
.PP
.Vb 1
\& Embperl_Object_Reqpath /a:/b:/c
.Ve
.PP
and you request
.PP
.Vb 1
\& /x/index.epl
.Ve
.PP
it will try
.PP
.Vb 4
\& /x/index.epl
\& /a/index.epl
\& /b/index.epl
\& /c/index.epl
.Ve
.PP
and take the first one that is found.
.SS "Embperl_Object_Stopdir"
.IX Subsection "Embperl_Object_Stopdir"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_OBJECT_STOPDIR\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> object_stopdir
.IP "Since:" 4
.IX Item "Since:"
1.3b1
.PP
Directory where Embperl::Object stops searching for the base page.
.SS "Embperl_Object_Fallback"
.IX Subsection "Embperl_Object_Fallback"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_OBJECT_FALLBACK\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> object_fallback
.IP "Since:" 4
.IX Item "Since:"
1.3b1
.PP
If the requested file is not found by Embperl::Object, the file given by \f(CW\*(C`EMBPERL_OBJECT_FALLBACK\*(C'\fR
is displayed instead. If \f(CW\*(C`EMBPERL_OBJECT_FALLBACK\*(C'\fR isn't set a
staus 404, \s-1NOT_FOUND\s0 is returned as usual. If the fileame given in
\&\f(CW\*(C`EMBPERL_OBJECT_FALLBACK\*(C'\fR doesn't contain a path, it is searched thru the same
directories as \f(CW\*(C`EMBPERL_OBJECT_BASE\*(C'\fR.
.SS "Embperl_Object_Handler_Class"
.IX Subsection "Embperl_Object_Handler_Class"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_OBJECT_HANDLER_CLASS\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \-> object_handler_class
.IP "Since:" 4
.IX Item "Since:"
1.3b1
.PP
If you specify this, the template base and the requested page inherit all
methods from this class. This class must contain \f(CW\*(C`Embperl::Req\*(C'\fR in his
\&\f(CW@ISA\fR array.
.SS "Embperl_Useenv"
.IX Subsection "Embperl_Useenv"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_USEENV\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> config \-> use_env \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
off unless running as \s-1CGI\s0 script
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Tells Embperl to scan the enviromemt for configuration settings.
.SS "use_redirect_env"
.IX Subsection "use_redirect_env"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> config \-> use_redirect_env \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
off unless running as \s-1CGI\s0 script
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Tells Embperl to scan the enviromemt for configuration settings which has the
prefix \f(CW\*(C`REDIRECT_\*(C'\fR. This is normally the case when the request is not the main request,
but a subrequest.
.SS "Embperl_Allow"
.IX Subsection "Embperl_Allow"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_ALLOW\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> config \-> allow \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
no restrictions
.IP "Since:" 4
.IX Item "Since:"
1.2b10
.PP
If specified, only files which match the given \fBperl regular expression\fR will be
processed by Embperl. All other files will return \s-1FORBIDDEN.\s0
This is especially useful in a \s-1CGI\s0 environment by making the server more secure.
.SS "Embperl_Urimatch"
.IX Subsection "Embperl_Urimatch"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_URIMATCH\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> config \-> urimatch \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
process all files
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
If specified, only files which match the given \fBperl regular expression\fR 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.
.PP
.Vb 3
\& Example:
\& # Only files which end with .htm will processed by Embperl
\& EMBPERL_URIMATCH \e.htm$
.Ve
.SS "Embperl_Multfieldsep"
.IX Subsection "Embperl_Multfieldsep"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_MULTFIELDSEP\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> config \-> mult_field_sep \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
\&\et
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Specifies the character that is used to separate multiple form values with the
same name.
.SS "Embperl_Path"
.IX Subsection "Embperl_Path"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_PATH\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> config \-> path \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
1.3b6
.PP
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 .\e under windows), \fIEmbperl\fR searches all
the specified directories for that file.
.PP
A special handling is done if the filename starts with any number
of \f(CW\*(C`../\*(C'\fR i.e. refers to an upper directory. Then \fIEmbperl\fR strips
the same number of entries at the start of the searchpath as the filename
contains \f(CW\*(C`../\*(C'\fR.
\&\f(CW\*(C`Execute\*(C'\fR and the method of the request object expects/returns a array ref.
.SS "Embperl_Debug"
.IX Subsection "Embperl_Debug"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_DEBUG\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> config \-> debug
.PP
See application configuration for an describtion of possible values
.SS "Embperl_Options"
.IX Subsection "Embperl_Options"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_OPTIONS\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> config \-> options
.PP
This bitmask specifies some options for the execution of Embperl.
To specify multiple options, simply add the values together.
.IP "optDisableVarCleanup = 1" 4
.IX Item "optDisableVarCleanup = 1"
Disables the automatic cleanup of variables at the end of each
request.
.IP "optDisableEmbperlErrorPage = 2" 4
.IX Item "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.
.IP "optReturnError = 262144" 4
.IX Item "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 \fIErrorDocument\fR
directive to show a custom error-document. Inside the ErrorDocument
you can retrieve the error messages with
.Sp
.Vb 1
\& $errors = $req_rec \-> prev \-> pnotes(\*(AqEMBPERL_ERRORS\*(Aq) ;
.Ve
.Sp
where \f(CW$errors\fR is a array reference. (1.3b5+)
.IP "optShowBacktrace = 0x8000000" 4
.IX Item "optShowBacktrace = 0x8000000"
When set every error message not only show the sourcefiles, but all files
from which this file was called by Execute.
.SS "Embperl_Output_Mode"
.IX Subsection "Embperl_Output_Mode"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_OUTPUT_MODE\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> config \-> output_mode
.IP "Default:" 4
.IX Item "Default:"
\&\s-1HTML\s0
.IP "Since:" 4
.IX Item "Since:"
2.0b9
.PP
Set the desired output format. 0 for \s-1HTML\s0 and 1 \s-1XML.\s0 If set to \s-1XML\s0 all tags
that are generated by Embperl will contain a closing slash to conform to \s-1XML\s0
specs. e.g.
.PP
.Vb 1
\&
.Ve
.PP
\&\fB\s-1NOTE:\s0\fR If you set output_mode to \s-1XML\s0 you should also change escmode to \s-1XML\s0 escaping.
.SS "Embperl_Output_Esc_Charset"
.IX Subsection "Embperl_Output_Esc_Charset"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_OUTPUT_ESC_CHARSET\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> config \-> output_esc_charset \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
ocharsetLatin1 = 1
.IP "Since:" 4
.IX Item "Since:"
2.0.2
.PP
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.
.IP "ocharsetUtf8 = 0" 4
.IX Item "ocharsetUtf8 = 0"
\&\s-1UTF\-8\s0 or any non known charset. Characters with codes above 128 will not be escaped
at all
.IP "ocharsetLatin1 = 1" 4
.IX Item "ocharsetLatin1 = 1"
\&\s-1ISO\-8859\-1,\s0 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.
.IP "ocharsetLatin2 = 2" 4
.IX Item "ocharsetLatin2 = 2"
\&\s-1ISO\-8859\-2.\s0 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.
.SS "Embperl_Session_Mode"
.IX Subsection "Embperl_Session_Mode"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_SESSION_MODE\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> config \-> session_mode \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
smodeUDatCookie = 1
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Specifies how the id for the session data is passed between requests.
Possible values are:
.IP "smodeNone = 0" 4
.IX Item "smodeNone = 0"
No session id will be passed
.IP "smodeUDatCookie = 1" 4
.IX Item "smodeUDatCookie = 1"
The session id for the user session will be passed via cookie
.IP "smodeUDatParam = 2" 4
.IX Item "smodeUDatParam = 2"
The session id for the user session will append as parameter to any \s-1URL\s0
and inserted as a hidden field in any form.
.IP "smodeUDatUrl = 4" 4
.IX Item "smodeUDatUrl = 4"
The session id for the user session will passed as a part of the \s-1URL.
NOT YET IMPLEMENTED\s0!!
.IP "smodeSDatParam = 0x20" 4
.IX Item "smodeSDatParam = 0x20"
The session id for the state session will append as parameter to any \s-1URL\s0
and inserted as a hidden field in any form.
.PP
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.
.SS "Embperl_Useenv"
.IX Subsection "Embperl_Useenv"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_USEENV\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> config \-> use_env \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
off unless running as \s-1CGI\s0 script
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Tells Embperl to scan the enviromemt for configuration settings.
.SS "use_redirect_env"
.IX Subsection "use_redirect_env"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> config \-> use_redirect_env \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
off unless running as \s-1CGI\s0 script
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Tells Embperl to scan the enviromemt for configuration settings which has the
prefix \f(CW\*(C`REDIRECT_\*(C'\fR. This is normally the case when the request is not the main request,
but a subrequest.
.SS "Embperl_Package"
.IX Subsection "Embperl_Package"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_PACKAGE\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> config \-> package
.PP
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.)
.SS "Embperl_Debug"
.IX Subsection "Embperl_Debug"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_DEBUG\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> config \-> debug
.PP
See application configuration for an describtion of possible values
.SS "Embperl_Options"
.IX Subsection "Embperl_Options"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_OPTIONS\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> config \-> options
.PP
This bitmask specifies some options for the execution of Embperl.
To specify multiple options, simply add the values together.
.IP "optDisableVarCleanup = 1" 4
.IX Item "optDisableVarCleanup = 1"
Disables the automatic cleanup of variables at the end of each
request.
.IP "optDisableEmbperlErrorPage = 2" 4
.IX Item "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.
.IP "optReturnError = 262144" 4
.IX Item "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 \fIErrorDocument\fR
directive to show a custom error-document. Inside the ErrorDocument
you can retrieve the error messages with
.Sp
.Vb 1
\& $errors = $req_rec \-> prev \-> pnotes(\*(AqEMBPERL_ERRORS\*(Aq) ;
.Ve
.Sp
where \f(CW$errors\fR is a array reference. (1.3b5+)
.IP "optShowBacktrace = 0x8000000" 4
.IX Item "optShowBacktrace = 0x8000000"
When set every error message not only show the sourcefiles, but all files
from which this file was called by Execute.
.IP "optSafeNamespace = 4" 4
.IX 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\*(R" below for more details.)
.IP "optOpcodeMask = 8" 4
.IX 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\*(R"
below for more details.)
.IP "optDisableFormData = 256" 4
.IX Item "optDisableFormData = 256"
This option disables the setup of \f(CW%fdat\fR and \f(CW@ffld\fR. 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. \s-1CGI\s0.pm).
.IP "optFormDataNoUtf8 = 0x2000000" 4
.IX Item "optFormDataNoUtf8 = 0x2000000"
By default Embperl checks all formfields in \f(CW%fdat\fR
if they contain valid \s-1UTF\-8\s0 strings and if yes sets Perl's
internals \s-1UTF\-8\s0 flag.
.Sp
If this option is set Embperl will never set the \s-1UTF\-8\s0 on any
data in \f(CW%fdat\fR.
.IP "optAllFormData = 8192" 4
.IX Item "optAllFormData = 8192"
This option will cause Embperl to insert all formfields in \f(CW%fdat\fR and \f(CW@ffld\fR, even if they
are empty. Empty formfields will be inserted with an empty string. Without this option,
empty formfields will be absent from \f(CW%fdat\fR and \f(CW@ffld\fR.
.IP "optRedirectStdout = 16384" 4
.IX Item "optRedirectStdout = 16384"
Redirects \s-1STDOUT\s0 to the Embperl output stream before every request and resets it afterwards.
If set, you can use a normal Perl \fBprint\fR 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 \fB\s-1OUT\s0\fR.
.IP "optNoHiddenEmptyValue = 65536 (only 1.2b2 and above)" 4
.IX Item "optNoHiddenEmptyValue = 65536 (only 1.2b2 and above)"
Normally, if there is a value defined in \f(CW%fdat\fR for a specific input field, Embperl
will output a hidden input element for it when you use \fBhidden\fR. When this option
is set, Embperl will not output a hidden input element for this field when the
value is a blank string.
.IP "optKeepSpaces = 1048576 (only 1.2b5 and above) = 0x100000," 4
.IX Item "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 \s-1HTML.\s0
.IP "optChdirToSource = 0x10000000 (only 2.5 and above)" 4
.IX Item "optChdirToSource = 0x10000000 (only 2.5 and above)"
Change current working directory to the directory of the sourcefile,
before executing the source.
.SS "Embperl_Escmode"
.IX Subsection "Embperl_Escmode"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_ESCMODE\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> config \-> escmode
.IP "Default:" 4
.IX Item "Default:"
7
.PP
Turn \s-1HTML\s0 and \s-1URL\s0 escaping on and off.
.PP
\&\s-1NOTE:\s0 If you want to output binary data, you must set the escmode
to zero.
.PP
For convenience you can change the escmode inside a page by setting
the variable \f(CW$escmode\fR.
.IP "escXML = 8 (or 15) (2.0b4 and above)" 4
.IX Item "escXML = 8 (or 15) (2.0b4 and above)"
The result of a Perl expression is always XML-escaped (e.g., `>'
becomes `>' and ' become ').
.IP "escUrl + escHtml = 3 (or 7)" 4
.IX Item "escUrl + escHtml = 3 (or 7)"
The result of a Perl expression is HTML-escaped (e.g., `>' becomes
`>') in normal text and URL-escaped (e.g., `&' becomes `%26')
within of \f(CW\*(C`A\*(C'\fR, \f(CW\*(C`EMBED\*(C'\fR, \f(CW\*(C`IMG\*(C'\fR, \f(CW\*(C`IFRAME\*(C'\fR, \f(CW\*(C`FRAME\*(C'\fR and \f(CW\*(C`LAYER\*(C'\fR tags.
.IP "escUrl = 2 (or 6)" 4
.IX Item "escUrl = 2 (or 6)"
The result of a Perl expression is always URL-escaped (e.g., `&'
becomes `%26').
.IP "escHtml = 1 (or 5)" 4
.IX Item "escHtml = 1 (or 5)"
The result of a Perl expression is always HTML-escaped (e.g., `>'
becomes `>').
.IP "escNode = 0" 4
.IX Item "escNode = 0"
No escaping takes place.
.IP "escEscape = 4" 4
.IX Item "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 \s-1HTML\s0 and precede them
with a backslash to avoid correct escaping when their input is redisplayed
again.
.PP
\&\s-1NOTE:\s0 You can localize \f(CW$escmode\fR inside a [+ +] block, e.g. to turn escaping
temporary off and output \f(CW$data\fR write
.PP
.Vb 1
\& [+ do { local $escmode = 0 ; $data } +]
.Ve
.SS "Embperl_Input_Escmode"
.IX Subsection "Embperl_Input_Escmode"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_INPUT_ESCMODE\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> config \-> input_escmode \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
0
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Tells Embperl how to handle escape sequences that are found in the source.
.ie n .IP "0" 4
.el .IP "\f(CW0\fR" 4
.IX Item "0"
don't interpret input (default)
.ie n .IP "1" 4
.el .IP "\f(CW1\fR" 4
.IX Item "1"
unescape html escapes to their characters (i.e. < becomes < )
inside of Perl code
.ie n .IP "2" 4
.el .IP "\f(CW2\fR" 4
.IX Item "2"
unescape url escapes to their characters (i.e. \f(CW%26\fR; becomes & )
inside of Perl code
.ie n .IP "3" 4
.el .IP "\f(CW3\fR" 4
.IX Item "3"
unescape html and url escapes, depending on the context
.PP
Add 4 to remove html tags inside of Perl code. This is helpful when
an html editor insert html tags like inside your Perl code.
.PP
Set \s-1EMBPERL_INPUT_ESCMODE\s0 to 7 to get the old default of Embperl < 2.0b6
.PP
Set \s-1EMBPERL_INPUT_ESCMODE\s0 to 0 to get the old behaviour when optRawInput was set.
.SS "Embperl_Input_Charset"
.IX Subsection "Embperl_Input_Charset"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_INPUT_CHARSET\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> config \-> input_charset
.PP
If set to the value \*(L"utf8\*(R" the source is interpreted as utf8 encoded so
you can use utf8 literals. It has the same effect as adding \*(L"use utf8\*(R"
to a normal Perl script.
.SS "Embperl_Top_Include"
.IX Subsection "Embperl_Top_Include"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_TOP_INCLUDE\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> config \-> top_include
.IP "Since:" 4
.IX Item "Since:"
2.0b10
.PP
Give a pieces of code that is include at the very top of every file.
.PP
Example:
.PP
.Vb 1
\& Embperl_Top_Include "use MY::Module;"
.Ve
.PP
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.
.PP
\&\fB\s-1NOTE:\s0\fR If you pass top_include as parameter to Execute it is
only used in case the code is compiled (or recompiled) and not cached.
.SS "Embperl_Cache_Key"
.IX Subsection "Embperl_Cache_Key"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_CACHE_KEY\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> config \-> cache_key \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b1
.PP
literal string that is appended to the cache key
.SS "Embperl_Cache_Key_Options"
.IX Subsection "Embperl_Cache_Key_Options"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_CACHE_KEY_OPTIONS\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> config \-> cache_key_options \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
all options set
.IP "Since:" 4
.IX Item "Since:"
2.0b1
.PP
Tells Embperl how to create a key for caching of the output
.IP "ckoptPathInfo = 2" 4
.IX Item "ckoptPathInfo = 2"
include the PathInfo into CacheKey
.IP "ckoptQueryInfo = 4" 4
.IX Item "ckoptQueryInfo = 4"
include the QueryInfo into CacheKey
.IP "ckoptDontCachePost = 8" 4
.IX Item "ckoptDontCachePost = 8"
don't cache \s-1POST\s0 requests (not yet implemented)
.SS "Embperl_Expires_Func"
.IX Subsection "Embperl_Expires_Func"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_EXPIRES_FUNC\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> config \-> expires_func \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b1
.PP
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.
.PP
Function could be either a coderef (when passed to Execute), a name of a
subroutine or a string starting with \*(L"sub \*(R" in which case it is compiled
as anonymous subroutine.
.PP
\&\s-1NOTE:\s0 If \f(CW&EXPIRES\fR is defined inside the page, it get evaluated before
the excecution of the page
.SS "Embperl_Cache_Key_Func"
.IX Subsection "Embperl_Cache_Key_Func"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_CACHE_KEY_FUNC\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> config \-> cache_key_func
.IP "Since:" 4
.IX Item "Since:"
2.0b1
.PP
function that should be called when build a cache key. The result is
appended to the cache key.
.SS "Embperl_Expires_In"
.IX Subsection "Embperl_Expires_In"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_EXPIRES_IN\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> config \-> expires_in \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b1
.PP
Time in seconds that the output should be cached. (0 = never, \-1 = forever)
.PP
\&\s-1NOTE:\s0 If \f(CW$EXPIRES\fR is set inside the page, it get evaluated before
the excecution of the page
.SS "Embperl_Expires_Filename"
.IX Subsection "Embperl_Expires_Filename"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_EXPIRES_FILENAME\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> config \-> expires_filename \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b8
.PP
Cache should be expired when the given file is modified.
.SS "Embperl_Syntax"
.IX Subsection "Embperl_Syntax"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_SYNTAX\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> config \-> syntax
.IP "Default:" 4
.IX Item "Default:"
Embperl
.IP "Since:" 4
.IX Item "Since:"
2.0b1
.PP
Used to tell Embperl which syntax to use inside a page. Embperl comes with
the following syntaxes:
.IP "EmbperlHTML" 4
.IX Item "EmbperlHTML"
all the \s-1HTML\s0 tags that Embperl recognizes by default
.IP "EmbperlBlocks" 4
.IX Item "EmbperlBlocks"
all the [ ] blocks that Embperl supports
.IP "Embperl" 4
.IX Item "Embperl"
(default; contains EmbperlHtml and EmbperlBlocks)
.IP "\s-1ASP\s0" 4
.IX Item "ASP"
<% %> and <%= %>, see perldoc Embperl::Syntax::ASP
.IP "\s-1SSI\s0" 4
.IX Item "SSI"
Server Side Includes, see perldoc Embperl::Syntax::SSI
.IP "Perl" 4
.IX Item "Perl"
File contains pure Perl (similar to Apache::Registry), but
can be used inside EmbperlObject
.IP "Text" 4
.IX Item "Text"
File contains only Text, no actions are taken on the Text
.IP "Mail" 4
.IX Item "Mail"
Defines the 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
.IP "\s-1POD\s0" 4
.IX Item "POD"
translates pod files to \s-1XML,\s0 which can be converted to
the desired output format by an \s-1XSLT\s0 transformation
.IP "\s-1RTF\s0" 4
.IX Item "RTF"
Can be used to process word processing documents in \s-1RTF\s0 format
.PP
You can get a description for each syntax if you type
.PP
.Vb 1
\& perldoc Embperl::Syntax::xxx
.Ve
.PP
where 'xxx' is the name of the syntax.
.PP
You can also specify multiple syntaxes e.g.
.PP
.Vb 1
\& EMBPERL_SYNTAX "Embperl SSI"
\&
\& Execute ({inputfile => \*(Aq*\*(Aq, syntax => \*(AqEmbperl ASP\*(Aq}) ;
.Ve
.PP
The 'syntax' metacommand allows you to switch the syntax or to
add or subtract syntaxes e.g.
.PP
.Vb 1
\& [$ syntax + Mail $]
.Ve
.PP
will add the Mail taglib so the tag is available after
this line.
.PP
.Vb 1
\& [$ syntax \- Mail $]
.Ve
.PP
now the tag is unknown again
.PP
.Vb 1
\& [$ syntax SSI $]
.Ve
.PP
now you can only use \s-1SSI\s0 commands inside your page.
.SS "Embperl_Recipe"
.IX Subsection "Embperl_Recipe"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_RECIPE\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> config \-> recipe \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b4
.PP
Tells Embperl which recipe to use to process this component
.SS "Embperl_Xsltstylesheet"
.IX Subsection "Embperl_Xsltstylesheet"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_XSLTSTYLESHEET\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> config \-> xsltstylesheet \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b5
.PP
Tell the xslt processor which stylsheet to use.
.SS "Embperl_Xsltproc"
.IX Subsection "Embperl_Xsltproc"
.IP "Env:" 4
.IX Item "Env:"
\&\s-1EMBPERL_XSLTPROC\s0
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> config \-> xsltproc \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
depends on compiltime options
.IP "Since:" 4
.IX Item "Since:"
2.0b5
.PP
Tells Embperl which xslt processor to use. Current \f(CW\*(C`libxslt\*(C'\fR and \f(CW\*(C`xalan\*(C'\fR
are supported by Embperl, but they must be compiled in to be available.
.SH "Parameters"
.IX Header "Parameters"
Parameters gives addtionaly information about the current request
or the execution of the current component. So we have two sorts of
parameters \fIRequest\fR and \fIComponent\fR parameters. Request
parameters are automatically setup by Embperl with information
Embperl takes from the current running environment. When
Embperl is invoked via the \f(CW\*(C`Execute\*(C'\fR function, you can pass any of
the parameters to Execute. Component parameters mainly reflect
the parameters given to \f(CW\*(C`Execute\*(C'\fR.
.SS "filename"
.IX Subsection "filename"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> param \-> filename
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Gives the filename of the file that was actualy requested.
Inside of the applications \f(CW\*(C`init\*(C'\fR function it can be changed
to force Embperl to serve a different file.
.SS "unparsed_uri"
.IX Subsection "unparsed_uri"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> param \-> unparsed_uri
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
The full unparsed_uri, includeing the query_string and the path_info.
.SS "uri"
.IX Subsection "uri"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> param \-> uri
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
The decoded path of the unparsed_uri.
.SS "server_addr"
.IX Subsection "server_addr"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> param \-> server_addr
.IP "Since:" 4
.IX Item "Since:"
2.0b9
.PP
\&\s-1URL\s0 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)
.SS "path_info"
.IX Subsection "path_info"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> param \-> path_info
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
The path_info, that is anything in the path after the file the is currently served.
.SS "query_info"
.IX Subsection "query_info"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> param \-> query_info
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Any parameters passed in a \s-1GET\s0 request after the question mark. The hash
\&\f(CW%fdat\fR will contain these values in a already decoded and easy to use way.
So it's normly more convenient to use \f(CW%fdat\fR instead.
.SS "language"
.IX Subsection "language"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> param \-> language
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
The primary langange found in the browser \f(CW\*(C`Accept\-Language\*(C'\fR \s-1HTTP\s0 header.
This value is used for all language-dependent functions inside Embperl.
You can set it change the selection of message returned by \f(CW\*(C`$request \-> gettext\*(C'\fR
and \f(CW\*(C`[= =]\*(C'\fR.
.SS "cookies"
.IX Subsection "cookies"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> param \-> cookies
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
A hashref that contains all cookies send by the browser to the server.
.SS "cgi"
.IX Subsection "cgi"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> param \-> cgi \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b12
.PP
Holds the \s-1CGI\s0.pm object, which is used for file upload. If no file uploaded data
is send to the request, this member is undefined.
.SS "inputfile"
.IX Subsection "inputfile"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> param \-> inputfile \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
1.0.0
.PP
Give the name of the file that should be processed, e.g.
.PP
.Vb 1
\& Execute({inputfile => \*(Aqmysource.epl\*(Aq}) ;
.Ve
.PP
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:
.PP
.Vb 1
\& Execute(\*(Aqmysource.epl\*(Aq) ;
.Ve
.SS "outputfile"
.IX Subsection "outputfile"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> param \-> outputfile \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
\&\s-1STDOUT\s0
.IP "Since:" 4
.IX Item "Since:"
1.0.0
.PP
Specify a file to which the output should be written. Example:
.PP
.Vb 2
\& Execute({inputfile => \*(Aqmysource.epl\*(Aq,
\& outputfile => \*(Aqmyoutput.htm\*(Aq}) ;
.Ve
.SS "input"
.IX Subsection "input"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> param \-> input \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
1.0.0
.PP
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 \f(CW\*(C`mtime\*(C'\fR
if \f(CW\*(C`undef\*(C'\fR or of a different value as it was during the last
call, the source is considered to be changed and everything
is recompiled. Example:
.PP
.Vb 2
\& # Get source from scalar
\& # Don\*(Aqt forget to modify mtime if $src changes
\&
\& $src = \*(AqPage [+ $no +]\*(Aq ;
\&
\& Embperl::Execute ({ inputfile => \*(Aqsome name\*(Aq,
\& input => \e$src,
\& mtime => 1 }) ;
.Ve
.SS "output"
.IX Subsection "output"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> param \-> output \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
1.0.0
.PP
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:
.PP
.Vb 2
\& Execute({inputfile => \*(Aqmysource.epl\*(Aq,
\& output => \e$out}) ;
.Ve
.SS "sub"
.IX Subsection "sub"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> param \-> sub \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
1.2.0
.PP
Call the given Embperl subroutine defined with \f(CW\*(C`[$sub$]\*(C'\fR 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:
.PP
.Vb 1
\& Execute(\*(Aqmysource.epl#mysub\*(Aq) ;
\&
\& Execute({inputfile => \*(Aqmysource.epl\*(Aq,
\& sub => \*(Aqmysub\*(Aq}) ;
.Ve
.PP
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.
.SS "subreq"
.IX Subsection "subreq"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> param \-> subreq
.IP "Since:" 4
.IX Item "Since:"
2.0b8, Apache 2.x
.PP
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:
.PP
.Vb 1
\& [\- Execute ({subreq => \*(Aq/cgi\-bin/script.cgi\*(Aq}) \-]
.Ve
.PP
\&\fB\s-1NOTE:\s0\fR You have to specify a \s-1URI\s0 and not a filename!
.SS "import"
.IX Subsection "import"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> param \-> import \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
1.3.0
.PP
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.
.PP
See \fB[$ sub $]\fR metacommand and section about subroutines for more info.
.PP
A value of zero tells Embperl to simply precompile all code found in the page.
(With 2.0 it is \fBnot\fR necessary anymore to do it before using the \f(CW\*(C`sub\*(C'\fR parameter
on a different file).
.SS "firstline"
.IX Subsection "firstline"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> param \-> firstline \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
1
.IP "Since:" 4
.IX Item "Since:"
1.2.0
.PP
Specifies the first linenumber of the sourcefile.
.SS "mtime"
.IX Subsection "mtime"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> param \-> mtime \fI[read only]\fR
.IP "Default:" 4
.IX Item "Default:"
undef
.IP "Since:" 4
.IX Item "Since:"
1.0.0
.PP
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.
.SS "param"
.IX Subsection "param"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> param \-> param \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
1.0.0
.PP
Can be used to pass parameters to the Embperl document and back. Must contain
a reference to an array. Example:
.PP
.Vb 4
\& Execute({inputfile => \*(Aqmysource.epl\*(Aq,
\& param => [1, 2, 3]}) ;
\& Execute({inputfile => \*(Aqmysource.epl\*(Aq,
\& param => \e@parameters}) ;
.Ve
.PP
There is a shortcut, so the following code the aquivalent (\s-1NOTE:\s0 Don't use a
array ref here):
.PP
.Vb 2
\& Execute(\*(Aqmysource.epl\*(Aq, 1, 2, 3) ;
\& Execute(\*(Aqmysource.epl\*(Aq, @parameters) ;
.Ve
.PP
The array \f(CW@param\fR in the Embperl document is setup as an alias to the array.
See \fIeg/x/Excute.pl\fR for a more detailed example.
.SS "fdat"
.IX Subsection "fdat"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> param \-> fdat \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
1.0.0
.PP
Pass a hash reference to customly set \f(CW%fdat\fR. If \f(CW\*(C`ffld\*(C'\fR is not given, \f(CW\*(C`ffld\*(C'\fR will
be set to \f(CW\*(C`keys %fdat\*(C'\fR.
.SS "ffld"
.IX Subsection "ffld"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> param \-> ffld \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
1.0.0
.PP
Pass a array reference to customly set \f(CW@fdat\fR. Does not affect \f(CW%fdat\fR.
.SS "object"
.IX Subsection "object"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> param \-> object \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
1.3.2
.PP
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 \f(CW\*(C`isa\*(C'\fR 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:
.PP
.Vb 3
\& [# the file eposubs.htm defines two subs: txt1 and txt2 #]
\& [# first we create a new object #]
\& [\- $subs = Execute ({\*(Aqobject\*(Aq => \*(Aqeposubs.htm\*(Aq}) \-]
\&
\& [# then we call methods inside the object #]
\& txt1: [+ $subs \-> txt1 +]
\&
\& txt2: [+ $subs \-> txt2 +]
.Ve
.SS "isa"
.IX Subsection "isa"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> param \-> isa \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
1.3.2
.PP
Takes a name of a file and pushes the package of that file into the \f(CW@ISA\fR
array of the current file. By using this you can setup an inherence tree
between Embperl documents. Is is also useful within \fIEmbperl::Object\fR.
Example:
.PP
.Vb 1
\& [! Execute ({\*(Aqisa\*(Aq => \*(Aq../eposubs.htm\*(Aq}) !]
.Ve
.SS "errors"
.IX Subsection "errors"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> param \-> errors \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
1.3.0
.PP
Takes a reference to an array. Upon return, the array will contain a copy of
all errormessages, if any.
.SS "xsltparam"
.IX Subsection "xsltparam"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> param \-> xsltparam
.IP "Default:" 4
.IX Item "Default:"
\&\f(CW%fdat\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Takes a reference to hash which contains key/value pair that are accessible inside
the stylesheet via .
.SH "Embperl's Objects"
.IX Header "Embperl's Objects"
There are three major objects in Embperl: \fIapplication\fR, \fIrequest\fR and \fIcomponent\fR.
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 \f(CW\*(C`config\*(C'\fR
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 \f(CW\*(C`param\*(C'\fR 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.
.SS "thread"
.IX Subsection "thread"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> thread \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Returns a reference to a object which hold per threads information. There is only one
such object per thread.
.SS "curr_req"
.IX Subsection "curr_req"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> curr_req \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Returns a reference to the current request object i.e. the object of the
request currently running.
.SS "config"
.IX Subsection "config"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> config \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Returns a reference to the configuration object of the application. See section Configuration.
.SS "user_session"
.IX Subsection "user_session"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> user_session \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Returns a reference to the user session object.
.SS "state_session"
.IX Subsection "state_session"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> state_session \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Returns a reference to the state session object.
.SS "app_session"
.IX Subsection "app_session"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> app_session \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Returns a reference to the application session object.
.SS "udat"
.IX Subsection "udat"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> udat \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
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 \f(CW%udat\fR.
.SS "sdat"
.IX Subsection "sdat"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> sdat \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
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 \f(CW%sdat\fR.
.SS "mdat"
.IX Subsection "mdat"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> mdat \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
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 \f(CW%mdat\fR.
.SS "errors_count"
.IX Subsection "errors_count"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> errors_count
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Contains the number of errors since last time send per mail. See also mail_errors_to.
.SS "errors_last_time"
.IX Subsection "errors_last_time"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> errors_last_time
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Time when the last error has occurred. See also mail_errors_to.
.SS "errors_last_send_time"
.IX Subsection "errors_last_send_time"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$application\fR \-> errors_last_send_time
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Time when the last mail with error messages was sent. See also mail_errors_to.
.SS "apache_req"
.IX Subsection "apache_req"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> apache_req \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Returns a reference to mod_perls Apache request object. In mod_perl 1 this is of
type \f(CW\*(C`Apache::\*(C'\fR in mod_perl 2 it's a \f(CW\*(C`Apache2::RequestRec\*(C'\fR.
.SS "config"
.IX Subsection "config"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> config \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Returns a reference to the configuration object of the request. See section Configuration.
.SS "param"
.IX Subsection "param"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> param \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Returns a reference to the parameter object of the request. See section Parameters.
.SS "component"
.IX Subsection "component"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> component \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Returns a reference to the object of component currently running. See component methods below.
.SS "app"
.IX Subsection "app"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> app \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Returns a reference to the object of application to which the current request belongs.
See application methods above.
.SS "thread"
.IX Subsection "thread"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> thread \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Returns a reference to a object which hold per threads information. There is only one
such object per thread.
.SS "request_count"
.IX Subsection "request_count"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> request_count \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Returns the number of request handled so far by this child process.
.SS "request_time"
.IX Subsection "request_time"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> request_time \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Start time of the current request.
.SS "session_mgnt"
.IX Subsection "session_mgnt"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> session_mgnt \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Set to true if session management is available.
.SS "session_id"
.IX Subsection "session_id"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> session_id \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Combined id of current user and state session.
.SS "session_state_id"
.IX Subsection "session_state_id"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> session_state_id \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Id of the current state session as received by the browser, this
means this method returns \f(CW\*(C`undef\*(C'\fR for a new session.
.SS "session_user_id"
.IX Subsection "session_user_id"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> session_user_id \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Id of the current user session as received by the browser, this
means this method returns \f(CW\*(C`undef\*(C'\fR for a new session.
.SS "cookie_expires"
.IX Subsection "cookie_expires"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> cookie_expires
.IP "Since:" 4
.IX Item "Since:"
2.1.1
.PP
Can be used to retrieve the actual expiration date that Embperl uses for the cookie with the session id.
.SS "had_exit"
.IX Subsection "had_exit"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> had_exit \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
True if exit was called in one of the components processed so far.
.SS "log_file_start_pos"
.IX Subsection "log_file_start_pos"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> log_file_start_pos \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
File possition of the log file at the time when the request has started.
.SS "error"
.IX Subsection "error"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> error
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
True if there were any error during the request.
.SS "errors"
.IX Subsection "errors"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> errors
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Reference to an array which holds all error messages occurred so far.
.SS "errdat1"
.IX Subsection "errdat1"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> errdat1
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Additional information passed to the error handler when an error is reported.
.SS "errdat2"
.IX Subsection "errdat2"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> errdat2
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Additional information passed to the error handler when an error is reported.
.SS "lastwarn"
.IX Subsection "lastwarn"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> lastwarn
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Last warning message.
.SS "errobj"
.IX Subsection "errobj"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> errobj
.IP "Since:" 4
.IX Item "Since:"
2.0rc3
.PP
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 \f(CW$epreq\fR \-> errobj, to get the object. The object is also push to the array
passed to the errors parameter of Execute.
.SS "cleanup_vars"
.IX Subsection "cleanup_vars"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> cleanup_vars
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
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.
.SS "cleanup_packages"
.IX Subsection "cleanup_packages"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> cleanup_packages
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Reference to a hash which contains all packages that must be cleaned up after the request.
.SS "initial_cwd"
.IX Subsection "initial_cwd"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> initial_cwd \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Working directory when the request started.
.SS "messages"
.IX Subsection "messages"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> messages
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Reference to an array of hashs of messages. This is used by Embperl to translate
message into different languages. When a \f(CW\*(C`[= =]\*(C'\fR block is processed or
\&\f(CW$request\fR \-> 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:
.PP
.Vb 10
\& %messages =
\& (
\& \*(Aqde\*(Aq =>
\& {
\& \*(Aqaddsel1\*(Aq => \*(AqKlicken Sie auf die Kategorie zu der Sie etwas hinzufügen möchten:\*(Aq,
\& \*(Aqaddsel2\*(Aq => \*(Aqoder fügen Sie eine neue Kategorie hinzu. Bitte geben Sie die Beschreibung in so vielen Sprachen wie Ihnen möglich ein.\*(Aq,
\& \*(Aqaddsel3\*(Aq => \*(AqFalls Sie die Übersetzung nicht wissen, lassen Sie das entsprechende Eingabefeld leer.\*(Aq,
\& \*(Aqaddsel4\*(Aq => \*(AqKategorie hinzufügen\*(Aq,
\& },
\& \*(Aqen\*(Aq =>
\& {
\& \*(Aqaddsel1\*(Aq => \*(AqClick on the category for which you want to add a new item:\*(Aq,
\& \*(Aqaddsel2\*(Aq => \*(Aqor add new category. Please enter the description in as much languages as possible.\*(Aq,
\& \*(Aqaddsel3\*(Aq => \*(AqIf you don\e\*(Aqt know the translation leave the corresponding input field empty.\*(Aq,
\& \*(Aqaddsel4\*(Aq => \*(AqAdd category\*(Aq,
\& }
\& ) ;
\&
\&
\& $lang = $request \-> param \-> language ;
\& push @{$request \-> messages}, $messages{$lang} ;
\& push @{$request \-> default_messages}, $messages{\*(Aqen\*(Aq} if ($lang ne \*(Aqen\*(Aq) ;
.Ve
.PP
\&\f(CW\*(C`$request \-\*(C'\fR 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.
.SS "default_messages"
.IX Subsection "default_messages"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$request\fR \-> default_messages
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Reference to an array with default messages. Messages will be taken from this array
if nothing can be found in the messages array.
.SS "config"
.IX Subsection "config"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> config \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Returns an reference to the configuration object of the component.
.SS "param"
.IX Subsection "param"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> param \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Returns an reference to the parameter object of the component.
.SS "req_running"
.IX Subsection "req_running"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> req_running \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
True if Embperl is inside of the execution of the request.
.SS "sub_req"
.IX Subsection "sub_req"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> sub_req \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
True is this is not the outermost Embperl component, i.e. this component is
called from within another component.
.SS "inside_sub"
.IX Subsection "inside_sub"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> inside_sub \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
True is we are inside a Embperl subroutine ([$ sub $] ... [$ endsub $])
.SS "had_exit"
.IX Subsection "had_exit"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> had_exit \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
True if the exit was called during the excution of the component.
.SS "path_ndx"
.IX Subsection "path_ndx"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> path_ndx \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Tells Embperl how much parts of the path should be ignored when searching
through the path.
.SS "cwd"
.IX Subsection "cwd"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> cwd \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Directory of the source file of the component.
.SS "sourcefile"
.IX Subsection "sourcefile"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> sourcefile \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Source file of the component.
.SS "syntax"
.IX Subsection "syntax"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> syntax
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Syntax of the component
.SS "prev"
.IX Subsection "prev"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> prev \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Previous component, e.g. the component which called this component.
.SS "import_stash"
.IX Subsection "import_stash"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> import_stash \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
While importing a component this is set to the stash to which symbols are imported.
\&\f(CW\*(C`undef\*(C'\fR during normal execution.
.SS "exports"
.IX Subsection "exports"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> exports
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Symbols that should be exported by this component.
.SS "curr_package"
.IX Subsection "curr_package"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> curr_package \fI[read only]\fR
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
Name of the package the component is executed in.
.SS "code"
.IX Subsection "code"
.IP "Method:" 4
.IX Item "Method:"
\&\f(CW$component\fR \-> code
.IP "Since:" 4
.IX Item "Since:"
2.0b6
.PP
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.