Config(3pm)

📦

version 2.5.0 · 2 versions

2.5.0 · ubuntu jammy (latest)
2.5.0 · debian bookworm

✨ NAME ✨

okay bestie, welcome to Config(3pm) — User Contributed Perl Documentation. This page is Embperl::Config — Embperl configuration and calling. 💖 No cap, this is the whole vibe: how Embperl gets configured and how you call it. 🫶

🦋 Operating-Modes 🦋

Embperl can operate in one of four modes:

mod_perl — the mostly used way. You run 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 it as a normal CGI script. Due to the overhead of CGI, this mode is much slower. To get better performance, consider using Embperl together with FastCGI. (http://www.fastcgi.com). 🐢➡️🐇
Offline — you can use Embperl on the command line. Useful for generating static content out of dynamic pages, and sometimes helpful for testing. 🖥️✨
Call it from other Perl programs — if you have your own application and want to use Embperl's capabilities, call Embperl::Execute. This lets you 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 add some directives to your httpd.conf to load Embperl and add "Embperl" as the "PerlHandler". The following directives cause all files with extension 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, make sure non-Embperl files like images don't get served from this directory. 🖼️🙅‍♀️

For mod_perl 2.0 you additionally need 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, use "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>

Additionally, you can set up 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 its 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 initialization. If you do so, they 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 filenames 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 parameters like Execute accepts (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 may be 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 the cgi script. You must have FCGI.pm installed. ⚡

🖥️ Offline 🖥️

Run Embperl from the command line using 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 "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 an 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 the hash of the long form are described 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 be 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 interactive 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 🌈

okay bestie, so configuring Embperl is lowkey giving choose your own adventure 💅 — there's like a million ways to do it, depending on how you run it. let me break it down fr fr:

when you run under mod_perl, Embperl adds a whole set of new config directives to the Apache config, so you can just set them in your httpd.conf. iconic.
when you run Embperl as CGI, it takes the config from environment variables. and for compatibility reasons you can also turn that 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 config along with other params as a hash reference. and if you pass use_env =< 1 as a parameter, Embperl will also scan the environment for config info.
last but not least, you can pass config info as options when you run Embperl via embpexec.pl from the command line.

and some of these config options are also settable inside the page via the Embperl objects, and you can read the current config from those objects too. so many vibes ✨

and it's not just about how you pass config — there are also three different contexts: Application, Request, and Component. 🎀

Application — a set of pages/files that belong together and form the application. Application-level config is the same for all files in that app. this info needs to be known before any request processing happens, so it can't be modified during a request. every application has its own name, and you refer to an app's config just by setting the name of the app to use.
Request — config that applies to one request. some of it must be known before the request starts, and some can still be modified during the request.
Component — config can be set up before the request, but can also be passed as an 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. (yes bestie, the typo is canon, I don't make the rules 🫶)

✨ `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 have 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 needing to set up the parameters for the application again. no cap, it's just a nickname for your whole setup. 👑

✨ `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 set up. this gives 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. main character energy, honestly. 💅

NOTE: the default until 1.3.3 was HTML::Embperl::Session, and 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 contain 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. pick a lane bestie, not both. 🫶

✨ `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 the cookie that Embperl uses for the session id. if set, the cookie will only be transferred over a secured connection. 🔒 periodt.

✨ `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 — spills the tea on how the parsed source gets compiled into Perl code ☕
dbgXML = 0x10000000 — logs everything XML-processing related 🦋
dbgXSLT = 0x20000000 — logs everything XSLT-processing related ✨
dbgCheckpoint = 0x40000000 — logs stuff about checkpoints, which are used internally while execution happens. Real talk: this is only useful if you have deep knowledge of Embperl internals. Like, deep deep. 🕳️

🌸 Embperl_Maildebug 🌸

Env: EMBPERL_MAILDEBUG
Method: $application -> config -> maildebug
Since: 1.2.1

The debug value that gets passed straight to Net::SMTP. 📧

🌸 Embperl_Mailhost 🌸

Env: EMBPERL_MAILHOST
Method: $application -> config -> mailhost
Default: localhost

Tells you which host the mail-related functions of Embperl use as their SMTP server. 💌

🌸 Embperl_Mailhelo 🌸

Env: EMBPERL_MAILHELO
Method: $application -> config -> mailhelo
Default: chosen by Net::SMTP
Since: 1.3b4

Which host/domain all mail-related functions use in the HELO/EHLO command. Net::SMTP normally picks a reasonable default, but depending on your installation you might have to set it manually. 🙈

🌸 Embperl_Mailfrom 🌸

Env: EMBPERL_MAILFROM
Method: $application -> config -> mailfrom
Default: www-server@<server_name>
Since: 1.2.1

The email address used as the sender for all mail-related functions. 💅

🌸 Embperl_Mail_Errors_To 🌸

Env: EMBPERL_MAIL_ERRORS_TO
Method: $application -> config -> mail_errors_to

If you set this, all errors get sent to the email address you gave. 😭📨

🌸 Embperl_Mail_Errors_Limit 🌸

Env: EMBPERL_MAIL_ERRORS_LIMIT
Method: $application -> config -> mail_errors_limit [read only]
Since: 2.0b6

Do not mail more than <num> errors. Set it to 0 for no limit at all. 🔥

🌸 Embperl_Mail_Errors_Reset_Time 🌸

Env: EMBPERL_MAIL_ERRORS_RESET_TIME
Method: $application -> config -> mail_errors_reset_time [read only]
Since: 2.0b6

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

🌸 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 every <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

The 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. That file should hold the Perl code for the application object. There must be no package name given inside the file (because the package is set by Embperl::Object), 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

Extra 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 an 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

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

If a file is requested but can't be found at the given location, the directories given in 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. 👀

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

The 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 isn't found by Embperl::Object, the file given by "EMBPERL_OBJECT_FALLBACK" gets displayed instead. If "EMBPERL_OBJECT_FALLBACK" isn't set, a status 404, NOT_FOUND is returned as usual. If the filename given in "EMBPERL_OBJECT_FALLBACK" doesn't contain a path, it's 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 its @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 environment 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 environment for configuration settings that have the prefix "REDIRECT_". This is normally the case when the request isn't 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 matching the given Perl regular expression will be processed by Embperl. All other files return FORBIDDEN. This is especially useful in a CGI environment, because it makes 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 matching the given Perl regular expression get processed by Embperl, and all other files get handled by the standard Apache handler. Super handy if you've got Embperl documents and non-Embperl documents (like gifs) living 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

The character used to separate multiple form values that share the same name. 💜

🌸 Embperl_Path 🌸

Env: EMBPERL_PATH
Method: $request -> config -> path [read only]
Since: 1.3b6

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

There's special handling if the filename starts with any number of "../", i.e. it 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 an array ref. ✨

🌸 Embperl_Debug 🌸

Env: EMBPERL_DEBUG
Method: $request -> config -> debug

See the application configuration for a description 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, just 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 that 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 an array reference. (1.3b5+) 😭

optShowBacktrace = 0x8000000 — when set, every error message shows not only 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 for XML. If set to XML, all tags generated by Embperl 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

Okay so this one tells Embperl which charset to assume when it's escaping stuff. Big caveat bestie: you can only set this before the request even starts — like in httpd.conf or at the very top of the page. Set it halfway down inside the page and you get undefined results. We don't do that. 🚫

ocharsetUtf8 = 0 — UTF-8, or literally any charset that isn't one of the known ones. Characters with codes above 128 will not be escaped at all.
ocharsetLatin1 = 1 — ISO-8859-1, and this is the default, bestie. When a Perl string has its utf-8 bit set, this mode behaves exactly the same as mode 0, meaning it won't escape anything above 128. 🫶
ocharsetLatin2 = 2 — ISO-8859-2. Same vibe: when a Perl string has its utf-8 bit set, it acts like mode 0 and nothing above 128 gets escaped.

🦋 Embperl_Session_Mode 🦋

Env: EMBPERL_SESSION_MODE

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

Default: smodeUDatCookie = 1

Since: 2.0b6

This one decides how the session id travels between requests. Options, bestie:

smodeNone = 0 — no session id gets passed, at all, periodt.
smodeUDatCookie = 1 — the session id for the user session rides along via cookie. 🍪
smodeUDatParam = 2 — the session id for the user session gets appended as a parameter to any URL, and gets inserted as a hidden field in any form.
smodeUDatUrl = 4 — the session id for the user session is passed as part of the URL. NOT YET IMPLEMENTED!! 💀
smodeSDatParam = 0x20 — the session id for the state session gets appended as a parameter to any URL, and gets inserted as a hidden field in any form.

And here's the cute part: you can add the UDat and SDat values together to get both kinds of sessions at once. For example, 0x21 will pass the user session's id inside a cookie and the state session's id as parameters. slay. ✨

🌸 Embperl_Useenv 🌸

Env: EMBPERL_USEENV

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

Default: off, unless it's running as a CGI script

Since: 2.0b6

Tells Embperl to scan the environment for configuration settings. Yes, the environment. It's giving "look around and pick up what's there". 👀

🌸 use_redirect_env 🌸

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

Default: off, unless it's running as a CGI script

Since: 2.0b6

Tells Embperl to scan the environment for config settings that have the prefix "REDIRECT_". This is normally the case when the request isn't the main request but a subrequest. iykyk. 🧚

👑 Embperl_Package 👑

Env: EMBPERL_PACKAGE

Method: $component -> config -> package

The name of the package where your code gets executed. By default, Embperl generates a unique package name for every file, which is honestly so considerate of it — it means variables and functions from one file don't start drama with those from another file. (And no cap, any package's variables are still reachable if you use explicit package names.) 💅

🔥 Embperl_Debug 🔥

Env: EMBPERL_DEBUG

Method: $component -> config -> debug

Go look at the application configuration for a description of the possible values. That's it, that's the section. 😌

✨ Embperl_Options ✨

Env: EMBPERL_OPTIONS

Method: $component -> config -> options

This bitmask specifies some options for how Embperl executes stuff. Wanna use multiple options? Just add the values together. Math is your friend, bestie. 🧮

optDisableVarCleanup = 1 — disables the automatic cleanup of variables at the end of each request.
optDisableEmbperlErrorPage = 2 — tells Embperl not to send its own error page when something fails, and instead show as much of the page as possible. Errors only get logged to the log file. Without this option, Embperl sends its own error page showing all the errors that occurred. And if you have dbgLogLink enabled, every error is a link straight to the corresponding spot in the log file. Heads up: this option does nothing if optReturnError is set.
optReturnError = 262144 — with this set, Embperl sends no output at all when there's an error. It returns the error back to Apache or to the calling program instead. Under mod_perl this is your moment ✨ — you get to use the Apache ErrorDocument directive to show a custom error document. And inside that ErrorDocument you can grab the error messages with:

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

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

optShowBacktrace = 0x8000000 — when set, every error message shows not only the source files but all the files from which this file was called by Execute. Receipts for days. 🧾
optSafeNamespace = 4 — tells Embperl to execute the embedded code in a safe namespace so the code can't touch data or code in any other package. (Peep the chapter about "(Safe-)Namespaces and opcode restrictions" below for the deets.)
optOpcodeMask = 8 — tells Embperl to apply an operator mask, which gives you the chance to disallow special (unsafe) opcodes. (Again: see the chapter about "(Safe-)Namespaces and opcode restrictions" below.)
optDisableFormData = 256 — this disables the setup of %fdat and @ffld. Embperl won't do anything with the posted form data. Set this when you're using Execute from your perl script and you've already read the form data (via, like, CGI.pm or whatever).
optFormDataNoUtf8 = 0x2000000 — by default Embperl checks all the formfields in %fdat to see if they contain valid UTF-8 strings, and if yes, it sets Perl's internal UTF-8 flag. If this option is set, Embperl will never set UTF-8 on any data in %fdat.
optAllFormData = 8192 — makes Embperl insert all formfields into %fdat and @ffld, even the empty ones. Empty formfields get inserted with an empty string. Without this option, empty formfields are just straight-up absent from %fdat and @ffld.
optRedirectStdout = 16384 — redirects STDOUT to the Embperl output stream before every request and resets it afterwards. If it's set, you can use a normal Perl print inside any Perl block to output data. Without it? You can only output data using the [+ ... +] block, or by printing to the filehandle OUT. Choose wisely. 💅
optNoHiddenEmptyValue = 65536 (only 1.2b2 and above) — normally, if there's a value defined in %fdat for a specific input field, Embperl outputs a hidden input element for it when you use hidden. When this option is set, Embperl won't output a hidden input element for that field when the value is a blank string.
optKeepSpaces = 1048576 (only 1.2b5 and above) = 0x100000, — disables the removal of spaces and empty lines from the output. Super useful for sources that aren't HTML. 🌈
optChdirToSource = 0x10000000 (only 2.5 and above) — changes the 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. The power is in your hands, bestie. ✨

NOTE: if you wanna output binary data, you must set the escmode to zero. no cap.

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

escXML = 8 (or 15) (2.0b4 and above) — the result of a Perl expression is always XML-escaped (like > becomes > and ' becomes ').
escUrl + escHtml = 3 (or 7) — the result of a Perl expression is HTML-escaped (like > becomes >) in normal text, and URL-escaped (like & becomes %26) inside of "A", "EMBED", "IMG", "IFRAME", "FRAME" and "LAYER" tags.
escUrl = 2 (or 6) — the result of a Perl expression is always URL-escaped (like & becomes %26).
escHtml = 1 (or 5) — the result of a Perl expression is always HTML-escaped (like > becomes >).
escNode = 0 — no escaping takes place. none. zero. nada.
escEscape = 4 — add this value to any of the above and Embperl will always perform the escaping. Without it, you can disable escaping by preceding the item that normally gets escaped with a backslash. And yes, that's a handy thing, but it could be very dangerous in situations where content inserted by some user gets redisplayed — because they can enter arbitrary HTML and slap a backslash in front of it to dodge correct escaping when their input shows up again. 😭

NOTE: you can localize $escmode inside a [+ +] block, like, to temporarily turn escaping 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 it finds in the source. Here's the tea:

0 — don't interpret input (this is the default)
1 — unescape html escapes to their characters (i.e. < 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 a lifesaver when an html editor inserts 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 you set this to the value "utf8", the source gets interpreted as utf8 encoded, so you can use utf8 literals. It has the exact same effect as adding use utf8 to a normal Perl script. cute! 🦋

⭐ Embperl_Top_Include ⭐

Env: EMBPERL_TOP_INCLUDE

Method: $component -> config -> top_include

Since: 2.0b10

Gives you a piece of code that gets included at the very top of every file. Main character energy for real.

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. Don't forget the semicolon, bestie, she's important. ✨

NOTE: if you pass top_include as a parameter to Execute, it's only used in the case that 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

A literal string that gets appended to the cache key. short and sweet. 💖

🌈 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. that's the whole thing, bestie. 💅

🎀 `Embperl_Expires_Func` 🎀

Env: EMBPERL_EXPIRES_FUNC
Method: $component -> config -> expires_func [read only]
Since: 2.0b1

Bestie, this one is literally the bouncer at the door of your cache. 💅 This is the function that gets called every single time before data is taken out of the cache. And if this function returns true? The cached data isn't used anymore, it just gets rebuilt. Fresh. Brand new. Slay. ✨

The function can be any of these cuties:

a coderef (when you pass it to Execute),
a name of a subroutine, or
a string starting with "sub " — in which case it gets compiled as an anonymous subroutine.

NOTE: If &EXPIRES is defined inside the page, it gets evaluated before the execution of the page. iykyk 🙈

🦋 `Embperl_Cache_Key_Func` 🦋

Env: EMBPERL_CACHE_KEY_FUNC
Method: $component -> config -> cache_key_func
Since: 2.0b1

This is the function that should be called when you build a cache key. And the result? Appended to the cache key. That's it, that's the whole vibe. 💖

🌸 `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, okay?

0 = never
-1 = forever

Pick your fighter. 👑

NOTE: If $EXPIRES is set inside the page, it gets evaluated before the execution of the page. Not me reminding you twice, but like… I am. 😭

💜 `Embperl_Expires_Filename` 💜

Env: EMBPERL_EXPIRES_FILENAME
Method: $component -> config -> expires_filename [read only]
Since: 2.0b8

The cache should be expired when the given file is modified. Simple as that, bestie — file changes, cache dips. 🫶

✨ `Embperl_Syntax` ✨

Env: EMBPERL_SYNTAX
Method: $component -> config -> syntax
Default: Embperl
Since: 2.0b1

This is the one that tells Embperl which syntax to use inside a page. And Embperl comes with the following syntaxes, no cap:

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. So like, plug in the name, get the tea. ☕

You can also specify multiple syntaxes, e.g.

EMBPERL_SYNTAX "Embperl SSI"

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

And the 'syntax' metacommand lets you switch the syntax, or 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. Gone. Deleted. 💀

[$ syntax SSI $]

now you can only use SSI commands inside your page. That's the whole menu, bestie. 🍓

🌈 `Embperl_Recipe` 🌈

Env: EMBPERL_RECIPE
Method: $component -> config -> recipe [read only]
Since: 2.0b4

Tells Embperl which recipe to use to process this component. Cook with the right one. 👩‍🍳

🧚 `Embperl_Xsltstylesheet` 🧚

Env: EMBPERL_XSLTSTYLESHEET
Method: $component -> config -> xsltstylesheet [read only]
Since: 2.0b5

Tell the xslt processor which stylsheet to use. (Yes, that's how it's spelled, don't come for me. 🙈)

⭐ `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. Currently "libxslt" and "xalan" are supported by Embperl, but they must be compiled in to be available. So like, if you didn't build it in, it's not showing up. Periodt. 🔥

🌸 Parameters 🌸

Okay bestie, so Parameters is where you get the tea ☕ on the current request or the current component doing its little thing. There's two flavors, and yes they're both iconic:

Request parameters — Embperl sets these up for you, automatically, from whatever's happening in the running environment. No effort required, she's self-sufficient 💅
Component parameters — these mostly just mirror whatever you handed to Execute.

🎀 `filename`

Method: $request -> param -> filename
Since: 2.0b6

Gives you the filename of the file that was actually requested. And here's the fun part: inside the application's init function you can change it to force Embperl to serve a whole different file. Sneaky. Love that for us. 👑

🎀 `unparsed_uri`

Method: $request -> param -> unparsed_uri
Since: 2.0b6

The full unparsed_uri, and when I say full I mean it — query_string and path_info are both in there too. The whole package deal. 🎁

🎀 `uri`

Method: $request -> param -> uri
Since: 2.0b6

The decoded path of the unparsed_uri. So like, the unparsed one but with its makeup off. ✨

🎀 `server_addr`

Method: $request -> param -> server_addr
Since: 2.0b9

URL of the server handling the current request, formatted like schema://addr:port/ — for example http://perl.apache.org/. And the port gets omitted if it's a default port, because she doesn't need to announce herself when she's being obvious. 💁♀️

🎀 `path_info`

Method: $request -> param -> path_info
Since: 2.0b6

The path_info — meaning anything in the path that comes after the file currently being served. The leftovers, the bonus content, the director's cut. 🎬

🎀 `query_info`

Method: $request -> param -> query_info
Since: 2.0b6

Any parameters passed in a GET request after the question mark. Now, the hash %fdat will contain these values already decoded and in a super easy-to-use way, so honestly it's normally more convenient to just use %fdat instead. Do with that what you will. 🙈

🎀 `language`

Method: $request -> param -> language
Since: 2.0b6

The primary language found in the browser's Accept-Language HTTP header. This value gets used for all the language-dependent functions inside Embperl. You can set it to change which message comes back from $request -> gettext and [= =]. Multilingual queen 🌍

🎀 `cookies`

Method: $request -> param -> cookies
Since: 2.0b6

A hashref containing all the cookies the browser sent to the server. All of them. Every last crumb. 🍪

🎀 `cgi`

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

Holds the CGI.pm object, which is what's used for file upload. But heads up: if no file-uploaded data was sent to the request, this member is undefined. So vibe check it before you go touching it. 🫶

🎀 `inputfile`

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

Gives the name of the file that should be processed, like:

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

And because we're nice, there's a shortcut for when you only need to give the input file and no other parameters. The above does the same thing as:

Execute('mysource.epl') ;

Same energy, fewer characters. Slay. 💅

🎀 `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

Use this parameter when you already have the source sitting in memory. You should pass a reference to a scalar that contains the source. And additionally you should give the inputfile parameter, so Embperl's caching can keep track of all your different in-memory sources (yes bestie, it needs the receipts 🧾).

The mtime parameter is what tells Embperl's cache whether the source has changed since the last call or not. If mtime is undef, or if it's a different value than it was during the last call, the source is considered changed and everything gets 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 you the option to write the output into a scalar instead of sending it off 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

Calls the given Embperl subroutine that's defined with [$sub$] inside the page. And there's a shortcut: just append the name of the subroutine after the filename with a hash sign, because we love efficiency. So these two calls are doing the exact same thing:

Execute('mysource.epl#mysub') ;

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

And if you leave out the filename entirely, the sub gets called in the current file — which means this can only be used inside a file that's already being processed by Embperl. No time travel allowed. ⏳

🎀 `subreq`

Method: $component -> param -> subreq
Since: 2.0b8, Apache 2.x

This one utilizes Apache 2.0 filters to grab the output of a sub-request and use it as the input for the current component. So say you've got a CGI-Script and you need to post-process it through Embperl, or you simply want to include its output inside 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! Do not mess this up, bestie, I'm begging. 😭

🎀 `import`

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

A value of one tells Embperl to define the subroutines inside the file (if that hasn't already been done) and import them as perl subroutines into the current namespace.

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

A value of zero tells Embperl to simply precompile all the code found in the page. And note — with 2.0 it's not necessary anymore to do that before using the sub parameter on a different file. Glow up. ✨

🎀 `firstline`

Method: $component -> param -> firstline [read only]
Default: 1
Since: 1.2.0

Specifies the first linenumber of the sourcefile. Counting starts where you say it starts. 💯

🎀 `mtime`

Method: $component -> param -> mtime [read only]
Default: undef
Since: 1.0.0

Last modification time of parameter input. If it's undef, the code passed by input is always recompiled. Otherwise the code only gets recompiled if mtime changes. Simple as. 🕰️

🎀 `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}) ;

And there's a shortcut, so the following code is the equivalent (NOTE: don't use an array ref here, okay?):

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

The array @param in the Embperl document gets set up as an alias to that 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. And if ffld isn't given, ffld will be set to keys %fdat. Teamwork makes the dream work. 🫱🫲

🎀 `ffld`

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

Pass an array reference to customly set @fdat. Does not affect %fdat. They're separate girls, keep them separate. 🚫

🎀 `object`

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

Takes a filename and returns a hashref that is blessed into the package of the given file. Super useful if you want to call the subs inside that given file as methods. And by using the isa parameter (see below, keep reading bestie) you're able to provide an inherence tree. Bonus: you can also 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 set up an inherence tree between Embperl documents. It's also useful within Embperl::Object. Example:

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

Family tree but make it code. 🌳

🎀 `errors`

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

Takes a reference to an array. Upon return, that array will contain a copy of all the errormessages, if there are any. (Fingers crossed there aren't. 🤞)

🎀 `xsltparam`

Method: $component -> param -> xsltparam
Default: %fdat
Since: 2.0b6

Takes a reference to a hash which contains key/value pairs that are accessible inside the stylesheet via <xsl:param>. Very demure, very XSLT. 💜

👑 Embperl's Objects 👑

Okay so there are three major objects in Embperl, and they're basically the main characters:

application
request
component

Each one of these can be used to get info about the processing and to control the execution. And each one 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. All the methods of those configuration objects are described up in the Configuration section. 📖

The request and component objects additionally have a parameter sub-object, which holds the parameters passed to the current request/component. The param method of these two objects returns the parameter sub-object, and all its methods live in the Parameters section (hi, that's the one you just read 💖).

And on top of all that, each of the three major objects has a set of its own methods, which we're about to get into right now. Let's go. 🔥

🦋 `thread`

Method: $application -> thread [read only]
Since: 2.0b6

Returns a reference to an object which holds per-thread information. There is only one such object per thread — she's exclusive, she's not sharing. 💅

🦋 `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 that's currently running. The one on stage right now. 🎤

🦋 `config`

Method: $application -> config [read only]
Since: 2.0b6

Returns a reference to the configuration object of the application. See the Configuration section for all the deets. ✨

🦋 `user_session`

Method: $application -> user_session [read only]
Since: 2.0b6

Returns a reference to the user session object. Your session, your rules. 🫶

🫶 `state_session`

Method:

$application -> state_session [read only]

Since: 2.0b6

Hands you back a reference to the state session object. That's it, that's the whole vibe. ✨

🫶 `app_session`

Method:

$application -> app_session [read only]

Since: 2.0b6

Returns a reference to the application session object. The app-wide one, bestie, not the personal one. 💅

🍓 `udat`

Method:

$application -> udat [read only]

Since: 2.0b6

Returns a reference to a hash holding the user session data. You can read it and poke at it to modify that data, no cap. It's literally the same thing as reaching for the global %udat. 🔥

🍓 `sdat`

Method:

$application -> sdat [read only]

Since: 2.0b6

Returns a reference to a hash holding the state session data. Read it, change it, live your truth. Exactly the same as touching the global %sdat. ✨

🍓 `mdat`

Method:

$application -> mdat [read only]

Since: 2.0b6

Returns a reference to a hash holding the application session data. Use it to access and modify that data. Same deal as the global %mdat. 💖

💀 `errors_count`

Method:

$application -> errors_count

Since: 2.0b6

Holds the number of errors since the last time they got sent per mail. See also mail_errors_to. Not me tracking my L's 💀

⏰ `errors_last_time`

Method:

$application -> errors_last_time

Since: 2.0b6

The time when the last error occurred. See also mail_errors_to.

📬 `errors_last_send_time`

Method:

$application -> errors_last_send_time

Since: 2.0b6

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

🌈 the request object's little methods

okay bestie, new object, same energy — this is all the stuff hanging off the request object. 🧚

👑 `apache_req`

Method:

$request -> apache_req [read only]

Since: 2.0b6

Returns a reference to mod_perl's Apache request object. In mod_perl 1 it's of type "Apache::", and in mod_perl 2 it's a "Apache2::RequestRec". Pick your era, both are iconic. 💅

⚙️ `config`

Method:

$request -> config [read only]

Since: 2.0b6

Returns a reference to the configuration object of the request. Go peep the Configuration section for the deets.

🎀 `param`

Method:

$request -> param [read only]

Since: 2.0b6

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

🧩 `component`

Method:

$request -> component [read only]

Since: 2.0b6

Returns a reference to the object of the component that's currently running. See the component methods below. ⭐

🌸 `app`

Method:

$request -> app [read only]

Since: 2.0b6

Returns a reference to the object of the application that the current request belongs to. Application methods are above, go look. 💖

🧵 `thread`

Method:

$request -> thread [read only]

Since: 2.0b6

Returns a reference to an object holding per-thread information. There's exactly one of these objects per thread. One. Singular. The main character of its thread. 👑

🔢 `request_count`

Method:

$request -> request_count [read only]

Since: 2.0b6

Returns the number of requests this child process has handled so far. Keeping receipts fr fr.

⏱️ `request_time`

Method:

$request -> request_time [read only]

Since: 2.0b6

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

🆔 `session_id`

Method:

$request -> session_id [read only]

Since: 2.0b6

The combined id of the current user and state session. Two sessions, one id, iconic duo energy. 💅

🆔 `session_state_id`

Method:

$request -> session_state_id [read only]

Since: 2.0b6

The id of the current state session as received by the browser. Which means for a brand new session this method returns "undef" — she's new here, no id yet. 🙈

🆔 `session_user_id`

Method:

$request -> session_user_id [read only]

Since: 2.0b6

The id of the current user session as received by the browser. Same deal: for a new session this returns "undef". 🦋

🍪 `cookie_expires`

Method:

$request -> cookie_expires

Since: 2.1.1

Use this to retrieve the actual expiration date that Embperl uses for the cookie holding the session id. Yes, cookies. Delicious. 🍪✨

🚪 `had_exit`

Method:

$request -> had_exit [read only]

Since: 2.0b6

True if exit was called in one of the components processed so far. She left the building. 💀

📄 `log_file_start_pos`

Method:

$request -> log_file_start_pos [read only]

Since: 2.0b6

The file position of the log file at the moment the request started. Bookmarking where we came in. 🔖

😭 `error`

Method:

$request -> error

Since: 2.0b6

True if there were any errors during the request. A vibe check that came back negative.

📚 `errors`

Method:

$request -> errors

Since: 2.0b6

A reference to an array holding all error messages that have occurred so far. The whole receipts folder.

🗂️ `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

More additional information passed to the error handler when an error is reported. Yes there are two. One for each pocket. 🎀

⚠️ `lastwarn`

Method:

$request -> lastwarn

Since: 2.0b6

The last warning message.

🪄 `errobj`

Method:

$request -> errobj

Since: 2.0rc3

The object passed to the last die, if there was one. Super handy when you pass an object to die inside an Execute: afterwards you can check $epreq -> errobj to grab that object back. The object also gets pushed onto the array you passed to the errors parameter of Execute. Look at her, being useful. 🌟

🧹 `cleanup_vars`

Method:

$request -> cleanup_vars

Since: 2.0b6

A reference to an array filled with references to variables that need cleaning up after the request. You can add your own variables that need cleanup here.

🚨 bestie listen: you should never remove any variables from this array. Ever. Do not touch the removals. 🙅‍♀️

🧼 `cleanup_packages`

Method:

$request -> cleanup_packages

Since: 2.0b6

A reference to a hash containing all the packages that must be cleaned up after the request. Spring cleaning but make it Perl. ✨

📁 `initial_cwd`

Method:

$request -> initial_cwd [read only]

Since: 2.0b6

The working directory when the request started. Where we were when this whole thing began. 🌸

🌍 `messages`

Method:

$request -> messages

Since: 2.0b6

A reference to an array of hashes of messages. Embperl uses this to translate messages into different languages. When a [= =] block is processed, or when $request -> gettext is called, Embperl searches this array. It starts at the first element (and every element in the array has to be a hashref) and tries to look up the text for the given symbol in that hash. If it fails, it moves on to the next array element. That way you can set up multiple translation tables that all get searched 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> grabs the language as given by the browser's language-accept header (or as set earlier in your program). Then it pushes the German or English messages hash onto the message array. On top of that, it pushes the English messages onto the default_messages array. Messages get taken from that array whenever nothing can be found in the messages array. Backups, bestie. Always have backups. 🫶

🗃️ `default_messages`

Method:

$request -> default_messages

Since: 2.0b6

A reference to an array of default messages. Messages get pulled from this array whenever nothing can be found in the messages array. The fallback bestie who always shows up. 💖

🧩 the component object's methods

new object, who dis — everything below hangs off the component object. 🌈

⚙️ `config`

Method:

$component -> config [read only]

Since: 2.0b6

Returns a reference to the configuration object of the component.

🎀 `param`

Method:

$component -> param [read only]

Since: 2.0b6

Returns a reference to the parameter object of the component.

🏃‍♀️ `req_running`

Method:

$component -> req_running [read only]

Since: 2.0b6

True if Embperl is currently inside the execution of the request. She's running, don't interrupt. 🔥

🪆 `sub_req`

Method:

$component -> sub_req [read only]

Since: 2.0b6

True if this is not the outermost Embperl component — i.e. this component got called from inside another component. A component within a component. 🪆

🫧 `inside_sub`

Method:

$component -> inside_sub [read only]

Since: 2.0b6

True if we're inside an Embperl subroutine ([$ sub $] ... [$ endsub $]). Deep in the sub, bestie. 💅

🚪 `had_exit`

Method:

$component -> had_exit [read only]

Since: 2.0b6

True if exit was called during the execution of the component. She said bye. 😭

🛤️ `path_ndx`

Method:

$component -> path_ndx [read only]

Since: 2.0b6

Tells Embperl how much of the path should be ignored when searching through the path. Skipping ahead, iconic. ⭐

📂 `cwd`

Method:

$component -> cwd [read only]

Since: 2.0b6

The directory of the source file of the component.

📄 `sourcefile`

Method:

$component -> sourcefile [read only]

Since: 2.0b6

The source file of the component. Where she came from. 🦋

🎨 `syntax`

Method:

$component -> syntax

Since: 2.0b6

The syntax of the component.

⬅️ `prev`

Method:

$component -> prev [read only]

Since: 2.0b6

The previous component — like, the component that called this one. Her origin story. 📖

📦 `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. During normal execution it's "undef". So if you see "undef", nothing's being imported right now, chill. ✨

📤 `exports`

Method:

$component -> exports

Since: 2.0b6

The symbols that should be exported by this component. Sharing is caring. 🫶

🏷️ `curr_package`

Method:

$component -> curr_package [read only]

Since: 2.0b6

The name of the package the component is executed in. Know her name, know her game. 👑

🦋 `code` 🦋

Method: $component -> code
Since: 2.0b6

Okay bestie, listen — this one is only valid during the compile phase. Like, it does not exist outside of that window, so don't go calling it at runtime and then act surprised, because the vibe check will fail. 🙈

What it does though? It's lowkey iconic. You can use it to retrieve and modify the code that Embperl is generating. Yes, the actual generated code. The way that it just hands you the source being built... main character energy fr fr. 💅

If you wanna go deeper, hit up Embperl::Syntax for all the details, and if you're the kind of person who learns by example (me too, always), Embperl::Syntax::RTF is right there serving as a whole example. 🫶

And that's a wrap, bestie!! 🌈 This whole little manual page was brought to you by perl v5.34.0, dated 2022-02-06, and it lives under the name Config(3pm). ✨ Go forth and configure responsibly, mwah 💖🎀🌸

📦 where this page comes from

ubuntu jammy: libembperl-perl 2.5.0-16build1 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Config(3pm)

✨ NAME ✨

🦋 Operating-Modes 🦋

💻 mod_perl 💻

🚀 Preloading pages 🚀

🌐 CGI/FastCGI 🌐

🖥️ Offline 🖥️

🪄 By calling Embperl::Execute (\%param) 🪄

🐛 Debugging 🐛

🌈 Configuration 🌈

✨ Embperl_Useenv ✨

✨ use_redirect_env ✨

✨ Embperl_Appname ✨

✨ Embperl_App_Handler_Class ✨

✨ Embperl_Session_Handler_Class ✨

✨ Embperl_Session_Args ✨

✨ Embperl_Session_Classes ✨

✨ Embperl_Session_Config ✨

✨ Embperl_Cookie_Name ✨

✨ Embperl_Cookie_Domain ✨

✨ Embperl_Cookie_Path ✨

✨ Embperl_Cookie_Expires ✨

✨ Embperl_Cookie_Secure ✨

✨ Embperl_Log ✨

✨ Embperl_Debug ✨

🌟 dbgStd = 1 (0x1)

🌟 dbgMem = 2 (0x2)

🌟 dbgEval = 4 (0x4)

🌟 dbgEnv = 16 (0x10)

🌟 dbgForm = 32 (0x20)

🌟 dbgInput = 128 (0x80)

🌟 dbgFlushOutput = 256 (0x100)

🌟 dbgFlushLog = 512 (0x200)

🌟 dbgLogLink = 8192 (0x2000)

🌟 dbgDefEval = 16384 (0x4000)

🌟 dbgHeadersIn = 262144 (0x40000)

🌟 dbgShowCleanup = 524288 (0x80000)

🌟 dbgSession = 2097152 (0x200000)

🌟 dbgImport = 4194304 (0x400000)

🌟 dbgOutput = 0x08000

🌟 dbgDOM = 0x10000

🌟 dbgRun = 0x20000

🌟 dbgBuildToken = 0x800000

🌟 dbgParse = 0x1000000

🌟 dbgObjectSearch = 0x2000000

🌟 dbgCache = 0x4000000

🌸 Embperl_Maildebug 🌸

🌸 Embperl_Mailhost 🌸

🌸 Embperl_Mailhelo 🌸

🌸 Embperl_Mailfrom 🌸

🌸 Embperl_Mail_Errors_To 🌸

🌸 Embperl_Mail_Errors_Limit 🌸

🌸 Embperl_Mail_Errors_Reset_Time 🌸

🌸 Embperl_Mail_Errors_Resend_Time 🌸

🌸 Embperl_Object_Base 🌸

🌸 Embperl_Object_App 🌸

🌸 Embperl_Object_Addpath 🌸

🌸 Embperl_Object_Reqpath 🌸

🌸 Embperl_Object_Stopdir 🌸

🌸 Embperl_Object_Fallback 🌸

🌸 Embperl_Object_Handler_Class 🌸

🌸 Embperl_Useenv 🌸

🌸 use_redirect_env 🌸

🌸 Embperl_Allow 🌸

🌸 Embperl_Urimatch 🌸

🌸 Embperl_Multfieldsep 🌸

🌸 Embperl_Path 🌸

🌸 Embperl_Debug 🌸

🌸 Embperl_Options 🌸

🌸 Embperl_Output_Mode 🌸

🌸 Embperl_Output_Esc_Charset 🌸

🦋 Embperl_Session_Mode 🦋

🌸 Embperl_Useenv 🌸

🌸 use_redirect_env 🌸

👑 Embperl_Package 👑

🔥 Embperl_Debug 🔥

✨ Embperl_Options ✨

🎀 Embperl_Escmode 🎀

🧚 Embperl_Input_Escmode 🧚

💜 Embperl_Input_Charset 💜

✨ `Embperl_Useenv` ✨

✨ `use_redirect_env` ✨

✨ `Embperl_Appname` ✨

✨ `Embperl_App_Handler_Class` ✨

✨ `Embperl_Session_Handler_Class` ✨

✨ `Embperl_Session_Args` ✨

✨ `Embperl_Session_Classes` ✨

✨ `Embperl_Session_Config` ✨

✨ `Embperl_Cookie_Name` ✨

✨ `Embperl_Cookie_Domain` ✨

✨ `Embperl_Cookie_Path` ✨

✨ `Embperl_Cookie_Expires` ✨

✨ `Embperl_Cookie_Secure` ✨

✨ `Embperl_Log` ✨

✨ `Embperl_Debug` ✨

🌟 `dbgStd = 1 (0x1)`

🌟 `dbgMem = 2 (0x2)`

🌟 `dbgEval = 4 (0x4)`

🌟 `dbgEnv = 16 (0x10)`

🌟 `dbgForm = 32 (0x20)`

🌟 `dbgInput = 128 (0x80)`

🌟 `dbgFlushOutput = 256 (0x100)`

🌟 `dbgFlushLog = 512 (0x200)`

🌟 `dbgLogLink = 8192 (0x2000)`

🌟 `dbgDefEval = 16384 (0x4000)`

🌟 `dbgHeadersIn = 262144 (0x40000)`

🌟 `dbgShowCleanup = 524288 (0x80000)`

🌟 `dbgSession = 2097152 (0x200000)`

🌟 `dbgImport = 4194304 (0x400000)`

🌟 `dbgOutput = 0x08000`

🌟 `dbgDOM = 0x10000`

🌟 `dbgRun = 0x20000`

🌟 `dbgBuildToken = 0x800000`

🌟 `dbgParse = 0x1000000`

🌟 `dbgObjectSearch = 0x2000000`

🌟 `dbgCache = 0x4000000`

🎀 `Embperl_Expires_Func` 🎀

🦋 `Embperl_Cache_Key_Func` 🦋

🌸 `Embperl_Expires_In` 🌸

💜 `Embperl_Expires_Filename` 💜

✨ `Embperl_Syntax` ✨

🌈 `Embperl_Recipe` 🌈

🧚 `Embperl_Xsltstylesheet` 🧚

⭐ `Embperl_Xsltproc` ⭐

🎀 `filename`

🎀 `unparsed_uri`

🎀 `uri`

🎀 `server_addr`

🎀 `path_info`

🎀 `query_info`

🎀 `language`

🎀 `cookies`

🎀 `cgi`

🎀 `inputfile`

🎀 `outputfile`

🎀 `input`

🎀 `output`

🎀 `sub`

🎀 `subreq`

🎀 `import`

🎀 `firstline`

🎀 `mtime`

🎀 `param`

🎀 `fdat`

🎀 `ffld`

🎀 `object`

🎀 `isa`

🎀 `errors`

🎀 `xsltparam`

🦋 `thread`

🦋 `curr_req`

🦋 `config`

🦋 `user_session`

🫶 `state_session`

🫶 `app_session`

🍓 `udat`

🍓 `sdat`

🍓 `mdat`

💀 `errors_count`

⏰ `errors_last_time`