HTML::Embperl - Perl extension for embedding Perl code in HTML documents
Embperl is a Perl extension module which gives you the ability to embed Perl code in HTML documents, like server-side includes for shell commands.
Embperl can operate in one of four modes:
Converts an HTML file with embedded Perl statements into a standard HTML file.
embpexec.pl [-o outputfile] [-l logfile] [-d debugflags] htmlfile [query_string]
The full pathname of the HTML file which should be processed by Embperl.
Optional. Has the same meaning as the environment variable QUERY_STRING when invoked as a CGI script. That is, QUERY_STRING contains everything following the first "?" in a URL. <query_string> should be URL-encoded. The default is no query string.
Optional. Gives the filename to which the output is written. The default is stdout.
Optional. Gives the filename of the logfile. The default is /tmp/embperl.log.
Optional. Specifies the level of debugging (what is written to the log file). The default is nothing. See below for exact values.
Instead of a file being sent directly by the web server, the document is processed by the CGI script and the result is sent to the client.
embpexec.pl
If embpexec.pl is invoked without any parameters and the environment variable PATH_TRANSLATED is set, it runs itself as a CGI script. This means that form data is taken either from the environment variable QUERY_STRING or from stdin, depending on whether or not CONTENT_LENGTH is set. (This will be set by the web server depending on whether the request method is GET or POST). Input is taken from the file pointed to by PATH_TRANSLATED and the output is send to stdout. The logfile is generated at its default location, which is configurable via the environment variable EMBPERL_LOG.
To use this mode you must copy embpexec.pl to your cgi-bin directory. You can invoke it with the URL http://www.domain.xyz/cgi-bin/embpexec.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 embpexec.pl as a handler for a specific file extention or directory.
Example of Apache srm.conf:
srm.conf
<Directory /path/to/your/html/docs> Action text/html /cgi-bin/embperl/embpexec.pl </Directory>
This works like the CGI-Script, but with the advantage that the script is compiled only once at server startup, where other one-time actions (such as opening files and databases) can take place. This will drastically reduce response times for the request. To use this you must compile Apache httpd with mod_perl and add HTML::Embperl as the PerlHandler.
Apache httpd
mod_perl
HTML::Embperl
PerlHandler
SetEnv EMBPERL_DEBUG 2285 Alias /embperl /path/to/embperl/eg <Location /embperl/x> SetHandler perl-script PerlHandler HTML::Embperl Options ExecCGI </Location>
Another possible setup (for Apache 1.3bX see below) is
SetEnv EMBPERL_DEBUG 2285 <Files *.epl> SetHandler perl-script PerlHandler HTML::Embperl Options ExecCGI </files> AddType text/html .epl
Don't forget the AddType. In this setup, all files ending with .epl are processed by Embperl.
NOTE: Since <Files> does not work the same in Apache 1.3bX as it does in Apache 1.2.x, you need to use <FilesMatch> instead.
NOTE:
<FilesMatch ".*\.epl$"> SetHandler perl-script PerlHandler HTML::Embperl Options ExecCGI </FilesMatch>
See the section on debugging (dbgLogLink and EMBPERL_VIRTLOG) to find out how you can configure Embperl so you can view the log file with your browser!
Execute takes a hash reference as argument. This gives the chance to vary the parameters according to the job that should be done.
(See eg/x/Excute.pl for more detailed examples)
Possible items are:
File which should be used as source. If input is also specified this parameter should give a unique name to identify the source. Everytime Embperl sees the same text in inputfile it assumes that you compile the same source, that means Embperl uses the same package name as in your last call and only recompiles the code if mtime has changed or is undefined.
Reference to a string which contains the source. inputfile must also be specified to give a name for the source. The name can be any text.
Last modification time of member input. If undef the code passed by input is always recompiled, else the code is only recompiled if mtime changes.
File to which the output should be written. If neither outputfile nor output is specified ouput is written to stdout.
Reference to a scalar where the output should be written to.
This value specifies if and when the cleanup of the package should be executed. (See variables scopes below for more information on cleanup)
Never cleanup the variables
If running under mod_perl cleanup is delayed until the connection to the client is closed, so it does not enlarge the response time to the client. If the Execute function is called more the once before the end of the request all cleanups take place after the end of the request and not between calls of Execute.
If running as cgi or offline cleanup takes immediately place.
Immediate cleanup
Can be used to pass parameters to the Embperl document and back. Must contain an reference to an array.
Example: HTML::Embperl::Execute(..., param => [1, 2, 3]) ; HTML::Embperl::Execute(..., param => \@parameters) ;
The array @param in the Embperl document is setup as an alias to the array. See eg/x/Excute.pl for more detailed example.
Could be used to setup the two Embperl predefined variables.
Same as EMBPERL_OPTIONS (see below), except for cleanup.
Same as EMBPERL_DEBUG (see below).
Same as EMBPERL_ESCMODE (see below).
Same as EMBPERL_PACKAGE (see below).
Same as EMBPERL_VIRTLOG (see below). If virtlog is equal to uri the logfile is send.
The URI of the request. Only needed for the virtlog feature.
Same as EMBPERL_COMPARTMENT (see below).
This function can be used to setup the logfile path and (optional) a default value for the debugflags, which will be used in further calls to Execute. There will be always only one logfile, but you can use Init to change it at any time.
NOTE: You do not need to call Init in version >= 0.27. The initialisation of Embperl takes place automaticly when it is loaded.
Scans the %ENV and setups %params for use by Execute. All Embperl runtime configuration options are recognised, except EMBPERL_LOG.
# Get source form /path/to/your.html and # write output to /path/to/output' HTML::Embperl::Execute ({ inputfile => '/path/to/your.html', outputfile => '/path/to/output'}) ; # Get source from scalar and write output to stdout # Don't forget to modify mtime if $src changes $src = '<html><head><title>Page [+ $no +]</title></head>' ; HTML::Embperl::Execute ({ inputfile => 'some name', input => \$src, mtime => 1 }) ; # Get source from scalar and write output another scalar my $src = '<html><head><title>Page [+ $no +]</title></head>' ; my $out ; HTML::Embperl::Execute ({ inputfile => 'another name', input => \$src, mtime => 1, output => \$out }) ; print $out ;
The runtime configuration is done by setting environment variables, either on the command line (when working offline) or in your web server's configuration file. Most HTTP servers understand
SetEnv <var> <value>
If you are using Apache and mod_perl you can use
PerlSetEnv <var> <value>
The advantage of PerlSetEnv over SetEnv is that it can be used on a per directory/virtual host basis.
Gives the name of the compartment from which to take the opcode mask. (See the chapter about Safe namespaces for more details.)
Specifies the initial value for $escmode (see below).
Gives the location of the log file. This will contain information about what Embperl is doing. How much information depends on the debug settings (see below). The log output is intended to show what your embedded Perl code is doing and to help debug it. Default is /tmp/embperl.log.
NOTE: When running under mod_perl you need to use PerlSetEnv for setting the logfile path, and mod_perl >= 1.07_03 if you load Embperl at server startup (with PerlScript or PerlModule).
The name of the package where your code will be executed. By default Embperl generates a unique package name for every file. This ensures that variables and functions from one file can not affect those from another file. (Any package's variables will still be accessible with explict package names.)
Gives a virtual location where you can access the Embperl logfile with a browser. This feature is disabled (default) if EMBPERL_VIRTLOG is not specified. See also dbgLogLink for an Example how to set it up in your srm.conf.
This bitmask specifies some options for the execution of Embperl:
Disables the automatic cleanup of variables at the end of each request.
Tells Embperl to not send its own errorpage in case of failure, instead giving the error back to the web server and let the web server handle it the standard way. Without this option, Embperl sends its own error page, showing all the errors which have occured. If you have dbgLogLink enabled, every error will be a link to the corresponding location in the log file.
Tells Embperl to execute the embbeded code in a safe namespace so the code cannot access data or code in any other package. (See the chapter about Safe namespaces below for more details.)
Tells Embperl to aply an operator mask. This gives you the chance to disallow special (unsafe) opcodes. (See the Chapter about Safe namespaces below for more details.)
Causes Embperl not to preprocess the source for a Perl expression. (The only exception is that carriage returns will be removed, as Perl does not like them.) This option should be set when you writing your code with an ASCII editor.
If you using a WYSIWYG editor which inserts unwanted HTML tags in your Perl expressions and escapes special charcaters automatically (e.g., `<' appears as `<' in the source), you should not set this option. Embperl will automaticly convert the HTML input back to the Perl expressions as you wrote them.
Normally, HTTP headers are sent after a request is finished without error. This gives you the chance to set arbitrary HTTP headers within the page, and Embperl the chance to calculate the content length. Also Embperl watchs out for errors and sends an errorpage instead of the document if something wents wrong. To do this, all the output is kept in memory until the whole request is processed, then the HTTP headers are sent, and then the document. This flag will cause the HTTP headers to be sent before the script is processed, and the script's output will be sent directly.
Without this option Embperl changes the currect directory to the one where the script resides. This gives you the chance to use relative pathnames. Since directory-changeing takes up some millisecs, you can disable it with this option if you don't need it.
This option disables the setup of %fdat and @ffld. Embperl will not do anything with the posted form data.
When set, this option disables the scanning of all html-tags. Embperl will only look for [+/-/!/$ ... $/!/-/+]. This will disable dynamic tables, processing of the input data and so on.
Disables processing of all input related tags. (<INPUT><TEXTAREA><OPTION>)
Disables processing of all table related tags. (<TABLE><TH><TR><TD><MENU><OL><SELECT><UL>)
Disables processing of all meta tags. (<META HTTP-EQUIV>)
This option will cause Embperl to insert all formfields in %fdat and @ffld, even if they are empty. Empty formfields will be insert with an empty string. Without this option empty formfields will not be insert in %fdat and @ffld.
Redirects STDOUT to the Embperl output stream before every request and reset it afterwards. If set, you can use a normal perl print inside any perl block, to output data. Without this option you can only output data by using the [+ ... +] block, or printing to the filehandle OUT.
This is a bitmask which specifies what should be written to the log. The following values are defined:
Show minimum information.
Show memory and scalar value allocation.
Show arguments to and results of evals.
Show metacommands and HTML tags which are processed.
List every request's environment variables.
Lists posted form data.
Show processing of dynamic tables.
Show processing of HTML input tags.
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.
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.
Logs all commands and HTML tags, whether or not they are really excuted or not. (It logs a `+' or `-' to tell you if they are executed.)
Logs the next piece of the HTML source to be processed. (NOTE: This generates a lot of output!)
This is only anvailable when Embperl is compiled with -DEPDEBUGALL, and it normally only used for debugging Embperl itself. Records all function entries to the logfile.
Inserts a link at the top of each page which can be used to view the log for the current HTML file. See also EMBEPRL_VIRTLOG.
Example:
SetEnv EMBPERL_DEBUG 10477 SetEnv EMBPERL_VIRTLOG /embperl/log <Location /embperl/log> SetHandler perl-script PerlHandler HTML::Embperl Options ExecCGI </Location>
Shows every time new Perl code is compiled.
Disables the use of the p-code cache. All Perl code is recompiled every time. (This should not be used in normal operation as it slows down Embperl dramatically.) This option is only here for debugging Embperls cache handling. There is no guarantee, that Embperl behaves the same with and without cache (actually is does not!)
Log all HTTP headers which are sent from the browser.
Show every variable which is undef'd at the end of the request. For scalar variables, the value before undef'ing is logged.
A good value to start is 2285 or 10477 if you want to view the logfile with your browser. (Don't forget to set EMBPERL_VIRTLOG.) If Embperl crashes, add 512 so the logfile is flushed after every line is written and you can see where Embperl is when it crashes.
2285
10477
512
Embperl understands four categories of commands. The first three are special Embperl commands, and the last category are some HTML tags that can trigger special processing. Embperl commands can span multiple lines and need not start or end at a line boundary.
Before the special Embperl commands are processed, and for the VALUE attribute of the INPUT tag (see below), all HTML tags are removed and special HTML characters are translated to their ASCII values (e.g., `<' is translated to `<'). You can avoid from this behavior by preceding the special character or HTML tag with a backslash. This is done in case your favorite (WYSIWYG) HTML editor inserts tags like line breaks or formatting into your Embperl commands where you don't want them.
NOTE: If you do use an ASCII editor to write your HTML documents, you should set the option optRawInput so Embperl does not preprocess your source. You can also HTML-escape your code (i.e. write `<' instead of `<'), to avoid ambiguity. In most cases it will also work without the optRawInput and HTML-escaping, but in some cases Embperl will deteced an HTML tag were there isn't one.
All Embperl commands start with a `[' and end with a `]'. To get a real `[' you must enter `[['.
Embperl does not use SGML comments (i.e., <! ... !> or similar things) because some HTML editors can't create them, or it's much more complicated. Sinces every HTML editor takes (or should take) `[' and `]' as normal text, there should be no problem.
Replace the command with the result of evaluating the Perl code. The Perl code can be anything which can be used as an argument to Perl eval statement. (See Security below for restrictions.) Examples:
[+ $a +] Replaces the [+ $a +] with the content of the variable $a [+ $a+1 +] (Any expression can be used) [+ $x[$i] +] (Arrays, hashes, and more complex expressions work)
NOTE: Whitespace is ignored. The output will be automatically HTML-escaped (e.g., `<' is translated to `<') depending on the value of the variables $escmode. You do not have to worry about it.
$escmode
Executes the Perl code, but delete the whole command from the HTML output.
Examples:
[- $a=1 -] Set the variable $a to one. No output will be generated. [- use SomeModule -] You can use other modules. [- $i=0; while ($i<5) {$i++} -] Even more complex statements or multiple statements are possible.
NOTE: Statements like if, while, for, etc., must be contained in a single Embperl command. You cannot have the if in one command block and the terminating `}' or else in another.
NOTE: To define subroutines, use [! ... !] (see below) instead of [- ... -] to avoid recompilation of the subroutine on every request.
Same as [- Perl Code -] with the exception that the code is only executed at the first request. This could be used to define subroutines, or do one-time initialization.
Execute an Embperl metacommand. Cmd can be one of the following. (Arg varies depending on <Cmd>).
Everything following the if metacommand until the else, elsif, or endif is only output if the Perl expression given in Arg is true. else and elsif work similarly.
[$ if $ENV{REQUEST_METHOD} eq 'GET' $] Method was GET<BR> [$ else $] Method other than GET used<BR> [$ endif $]
This will send one of the two sentences to the client, depending on the request method used to retrieve the document.
Executes a loop until the Arg given to while is false.
Example: (see eg/x/while.htm)
[- $i = 0; @k = keys %ENV -] [$ while ($i < $#k) $] [+ $k[$i] +] = [+ $ENV{$k[$i]} +]<BR> [- $i++ -] [$ endwhile $]
This will send a list of all environment variables to the client.
NOTE: The `<' is translated to `<' before call the Perl eval, unless optRawInput is set.
Arg consists of zero, one or two names of hashes (with or without the leading %) and an optional array as third parameter. The hidden metacommand will generated hidden fields for all data contained in first hash and not in second hash. The default used for the first hash is %fdat, %idat for the second.
%fdat
%idat
If the third parameter is specified, the fields are written in the order they appear in this array. That is, all keys of the first hash must be in this array properly sorted. This is intended for situations where you want to pass data from one form to the next, for example, two forms which should be filled one after the other. (Examples might be an input form and a second form to review and accept the input, or a Windows-style "wizard"). Here you can pass along data from previous forms in hidden fields. (See eg/x/neu.htm for an example.) If you use just the hidden command without parameters, it simply generates hidden fields for all form fields submitted to this document which aren't already contained in another input field.
<FORM ACTION="inhalt.htm" METHOD="GET"> <INPUT TYPE="TEXT" NAME="field1"> [$ hidden $] </FORM>
If you request this with
http://host/doc.htm?field1=A&field2=B&field3=C
the output will be
<FORM ACTION="inhalt.htm" METHOD="GET"> <INPUT TYPE="TEXT" NAME="feld1" VALUE="A"> <INPUT TYPE="HIDDEN" NAME="field2" VALUE="B"> <INPUT TYPE="HIDDEN" NAME="field3" VALUE="C"> </FORM>
NOTE: This should only be used for small amount of data, since the hidden fields are sent to the browser, which sends it back with the next request. If you have a large amount of data, store it in a file with a unique name and send only the filename in a hidden field. Be aware of the fact that the data could be change by the browser if the user didn't behave exactly as you expect. Your program should handle such situations properly.
The var command declares one or more variables for use within this Embperl document and sets the strict pragma. The variable names must be supplied as space separated list.
[$var $a %b @c $]
This is the same as writing the following in normal Perl code:
use strict ; use vars qw($a %b @c) ;
NOTE 1: `use strict' within an Embperl document will only aply to the block where it occurs.
Embperl recognizes the following HTML tags specially. All other are simply passed through, as long as they are not part of a Embperl command.
Embperl can generate dynamic tables (one or two dimensional). You only need to specify one row or column.
Embperl generates as many rows or columns as necessary. This is done by using the magic variables $row, $col, and $cnt. If you don't use $row/$col/$cnt within a table, Embperl does nothing and simply passes the table through.
Embperl checks if any of $row, $col, or $cnt is used. Embperl repeats all text between <table> and </table>, as long the expressions in which $row or $cnt occurs is/are defined.
Embperl repeats all text between <tr> and </tr>, as long the expressions in which $col or $cnt occurs is/are defined.
See also $tabmode (below) for end-of-table criteria.
Examples: (see eg/x/table.htm for more examples)
[- @k = keys %ENV -] <TABLE> <TR> <TD>[+ $i=$row +]</TD> <TD>[+ $k[$row] +]</TD> <TD>[+ $ENV{$k[$i]} +]</TD> </TR> </TABLE>
This will show all entries in array @k (which contains the keys from %ENV), so the whole environment is displayed (as in the while example), with the first column containing the zero-based index, the second containing the content of the variable name, and the third the environment variable's value.
This could be used to display the result of database query if you have the result in an array. You may provide as many columns as you need. It is also possible to call a fetch subroutine in each table row.
The TH tag is interpreted as table heading. If the whole row is made of <TH> </TH> instead of <TD> </TD> it's treated as column heading. Everything else will be treated as row headings in the future, but is ignored in the current version.
Lists and dropdowns or list boxes are treated exactly as one- dimensional tables. Only $row, $maxrow, $col, $maxcol and $tabmode are honored. $col and $maxcol are ignored. See eg/x/lists.htm for an example.
Embperl checks if there is a value from the form data for a specific option in a menu. If so, this option will be preselected.
<FORM METHOD="POST"> <P>Select Tag</P>
If you request this document with list.htm?SEL1=x you can specify that the element which has a value of x is initialy selected <P><SELECT NAME="SEL1"> <OPTION VALUE="[+ $v[$row] +]"> [+ $k[$row] +] </OPTION> </SELECT></P> </FORM>
The INPUT tag interacts with the hashes %idat und %fdat. If the input tag has no value, and a key exists with the same text as the NAME attribute of the input tag, Embperl will generate a VALUE attribute with the corresponding value of the hash key.
All values of <INPUT> tags are stored in the hash %idat, with NAME as the hash key and VALUE as the hash value. Special processing is done for TYPE=RADIO and TYPE=CHECKBOX. If the VALUE attribute contains the same text as the value of the hash the CHECKED attribute is inserted, else it is removed. So if you specify as the ACTION URL the file which contains the form itself, the form will be redisplayed with same values as entered the first time. (See eg/x/neu.htm for an example.)
The TEXTAREA tag is treated excatly like other input fields.
<meta http-equiv= ... > will override the correspondig http header this avoids netscape from asking the user to reload the document when the content-type differs between the http header and the meta http-equiv This can also be used to set http headers. When running under mod_perl http-headers can also be set by the function header_out
Example to set a http header: <META HTTP-EQUIV="Language" CONTENT="DE"> same using a Apache function [- $req_rec -> header_out("Language" => "DE"); -]
The scope of a variable declared with my or local ends at the end of the enclosing [+/- ... -/+] block; the [+/- ... -/+] blocks act much like Perl's { ... } in that regard.
Global variables (everything not declared with my or local) will be undef'ed at the end of each request, so you don't need to worry about any old variables laying around and causing suspicous results. This is only done for variables in the package the code is evaled in-- every variable that does not have an explicit package name. All variables with an explicit package name (i.e., in modules you use) will stay valid until the httpd child process dies. Embperl will change the current package to unique name for every document, so the influence between different documents is kept to a minimum. You can set the name of the package with EMBPERL_PACKAGE. (See also Safe namespaces.)
Since a CGI scripts is always a process of its own, you don't need to worry about that when you use Embperl as a CGI script.
If you need to declare variables which live more the one HTTP request (for example, a database handle), you must declare then in another package (i.e., $Persistent::handle instead of $handle).
If you use the strict pragma, you can use the var metacommand to declare your variables.
NOTE: Bacause Apache::DBI has its own namespace this module will work together with Embperl to maintain your persistent database connection.
You can disable the automatic cleanup of global variables with EMBPERL_OPTIONS or the cleanup parameter of the Execute function.
If you like to do your own cleanup you can define a subroutine CLEANUP in your document. This will called right before the variables will be cleaned up, but after the connection to the client is closed.
EXAMPLE: [! sub CLEANUP { close FH ; } !]
Embperl has some special variables which have a predefined meaning.
Contains the environment as seen from a CGI script.
Contains all the form data sent to the script by the calling form. The NAME attribute builds the key and the VALUE attribute is used as the hash value. Embperl doesn't care if it's called with the GET or POST method, but there may be restrictions on the length of parameters using GET--not from Embperl, but perhaps from the web server, especially if you're using Embperl's CGI mode--do it's safer to use POST.
Embperl also supports ENCTYPE multipart/form-data, which is used for file uploads. The entry in %fdat corresponding to the file field will be a filehandle, as with CGI.pm. (Embperl uses CGI.pm internally to process forms encoded with multipart/form-data.)
File upload example:
HTML page: <FORM METHOD="POST" ENCTYPE="multipart/form-data"> <INPUT TYPE="FILE" NAME="ImageName"> </FORM> Embperl ACTION: [- if (defined $fdat{ImageName}) { open FILE, "> /tmp/file.$$"; print FILE $buffer while read($fdat{ImageName}, $buffer, 32768); close FILE; } -]
Contains all the field names in the order in which they were sent by the browser. This is normally--but not necessarily--the order in which they appear in your form.
Contains all the values from all input tags processed so far.
Row and column counts for use in dynamic tables. (See HTML tag table.)
Maxium number of rows or columns to display in a table. To prevent endless loops, $maxrow defaults to 100 and $maxcol to 10. (See HTML tag table.)
Contains the number of table cells displayed so far. (See HTML tag table.)
Determines how the end of a dynamic table is detected:
end of table
End when an expression with $row becomes undefined. The row containing the undefined expression is not displayed.
End when an expression with $row becomes undefined. The row containing the undefined expression is displayed.
End when $maxrow rows have been displayed.
end of row
End when an expression with $col becomes undefined. The column containing the undefined expression is not displayed.
End when an expression with $col becomes undefined. The column containing the undefined is displayed.
End when $maxcol columns have been displayed.
The default is 17, which is correct for all sort of arrays. You should rarely need to change it. The two values can be added together.
Turn HTML and URL escaping on and off. The default is on ($escmode = 3).
The result of a Perl expression is HTML-escaped (e.g., `>' becomes `>') in normal text and URL-escaped (e.g., `&' becomes `%26') within an <A> tag.
The result of a Perl expression is always URL-escaped (e.g., `&' becomes `%26').
The result of a Perl expression is always HTML-escaped (e.g., `>' becomes `>').
No escaping takes place.
This variable is only available when running under control of mod_perl. It contains the request record needed to access the Apache server API. See perldoc Apache for more information.
This is the filehandle of the Embperl logfile. By writing `print LOG "something"' you can add lines to the logfile. NOTE: The logfile line should always start with the pid of the current process and continue with a four character signature delimited by a ':', which specifies the log reason.
Example: print LOG "[$$]ABCD: your text\n" ;
If you are writing a module for use under Embperl you can say
tie *LOG, 'HTML::Embperl::Log';
to get a handle by which you can write to the Embperl logfile.
This filehandle is tied to Embperls output stream. Printing to it has the same effect as using the [+ ... +] block. (See also optRedirectStdout)
Will be setup by the 'param' parameter of the Execute function. Could be used to pass parameters to an Embperl document and back. (see Execute for further docs)
All options (see EMBPERL_OPTIONS) and all debugging flags (see EMBPERL_DEBUG) can be read and set by the corresponding variables.
Example: [- $optRawInput = 1 -] # Turn the RawInput option on Now write something here [- $optRawInput = 0 -] # Turn the RawInput option off again [+ $dbgCmd +] # Output the state of the dbgCmd flag
Since most web servers will contain more than one document, it is necessary to protect the documents against each other. Embperl does this by using Perl namespaces. By default, Embperl executes every document in its own namespace (package). This will prevent documents from accidentally overriding the others' data. You can change this behavior (or simply the package name) with the configuration directive EMBPERL_PACKAGE. NOTE: By explicitly specifing a package name, you can access data that is used by another document.
If Embperl is used by more then one person, it may be neccessary to really protect one document from each other. To do this, Embperl gives you the option to use safe namespaces. Each document runs in its own package and can't access anything outside of this package. (See the documentation of Safe.pm for a more detailed discusion about safe namespaces.)
To make a document run in a safe namespace, simply add optSafeNamespace to EMBPERL_OPTIONS. The default package name used is the same as in normal operation and can be changed with EMBPERL_PACKAGE. NOTE: From the perspective of the document being executed, the code is running in the package main!
A second option to make Embperl more secure is the use of the opcode restriction mask. Before you can use the opcode mask, you must set up a safe compartement.
B<$cp = HTML::Embperl::AddCompartment($name);>
This will create a new compartment with a default opcode mask and the name $name. (The name is used later to tell Embperl which compartment to use.) Now you can change the operator mask. For example:
B<$cp->deny(':base_loop');>
In your configuration you must set the option optOpcodeMask in EMBPERL_OPTIONS and specify from which compartment the opcode mask should be taken by setting EMBPERL_COMPARTMENT.
Example (for use with mod_perl): B<srm.conf:> PerlScript startup.pl SetEnv EMBPERL_DEBUG 2285 Alias /embperl /path/to/embperl/eg <Location /embperl/x> SetHandler perl-script PerlHandler HTML::Embperl Options ExecCGI PerlSetEnv EMBPERL_OPTIONS 12 PerlSetEnv EMBPERL_COMPARTMENT test </Location> B<startup.pl:> $cp = HTML::Embperl::AddCompartment('test'); $cp->deny(':base_loop');
This will execute the file startup.pl on server startup. startup.pl sets up a compartment named `test', which will have a default opcode mask and additionaly, will have loops disabled. Code will be executed in a safe namespace.
NOTE: The package name from the compartment is NOT used!
Look at the documentation of Safe.pm and Opcode.pm for more detailed information on how to set opcode masks.
Adds a compartment for use with Embperl. Embperl only uses the opcode mask from it, not the package name. AddCompartement return the newly- created compartment so you can allow or deny certain opcodes. See the Safe.pm documentation for details of setting up a compartment. See chapter about Safe namepsaces for details of how Embperl uses it.
$cp = HTML::Embperl::AddCompartment('TEST'); $cp->deny(':base_loop');
Sends the content of the hash %fdat in the order specified by @ffld to the given $MailTo addressee, with a subject of $Subject. If you specify $ReturnField the value of that formfield will be used as Return-Path. Usualy this should be the field where the user enters his e-mail adress in the form.
If you specifiy the following example code as the action in your form
<FORM ACTION="x/feedback.htm" METHOD="POST" ENCTYPE="application/x-www-form-urlencoded">
The content of the form will be mailed to the given email address.
<HTML> <HEAD> <TITLE>Feedback</TITLE> </HEAD> <BODY> [- MailFormTo('webmaster@domain.xy', 'Mail from WWW Form', 'email') -] Your data has been sccesfully sent! </BODY> </HTML>
This will send a mail with all fields of the form to webmaster@domain.xy, with the Subject 'Mail form WWW Form' and will set the Return-Path of the mail to the adress which was entered in the field with the name 'email'.
NOTE: You must have Net::SMTP (from the libnet package) installed to use this function.
If Embperl encounters a pieces of perl code ([+/-/!/$ .... $/!/-/+]) it takes the following steps.
Steps 1-4 take place only the first time the perl code is encountered. Embperl stores the evaled subroutine, so all subsequent requests only need to execute steps 5-7.
Steps 6 and 7 take place only for code surrounded by [+ ... +].
What does this mean?
Lets take a piece of code like the following:
[+ <BR> $a = "This '>' is a greater-than sign" <BR> +]
[+ $a = "This '>' is a greater-than sign" +]
The <BR>s were inserted by some WYSIWYG HTML editor (e.g., by hitting return to make the source more readable. Also, such editors often generate "random" tags like <FONT>, etc.). Embperl removes them so they don't cause syntax errors.
There are cases where you actually want the HTML tag to be there. For example, suppose you want to output something like
[+ "<FONT COLOR=$col>" +]
If you write it this way Embperl will just remove everything, leaving only
[+ "" +]
There are several ways to handle this correctly.
a. <FONT COLOR=[+$col+]> Move the HTML tag out of the perl code. This is the best way, but not possible everytime. b. [+ "\<FONT COLOR=$col>" +] You can escape the opening angle bracket of the tag with `\'. c. [+ "<FONT COLOR=$col>" +] You can use the HTML escapes instead of the ASCII characters. Most HTML editors will automatically do this. (In this case, you don't have to worry about it at all.) d. Set optRawInput (see below). This will completely disable the removal of HTML tags.
NOTE: In cases b-d, you must also be aware of output escaping (see below).
You should also be aware that Embperl will interpret the perl spaceship operator (<>) as an HTML tag and will remove it. So instead of
[- $line = <STDIN>; -]
you need to write either
a. [- $line = \<STDIN>; -] b. [- $line = <STDIN>; -]
Again, if you use a high-level HTML editor, it will probably write version (b) for you automatically.
Since perl doesn't understand things like $a < $b, Embperl will translate it to $a < $b. If we take the example from earlier, it will now look like
[+ $a = "This '>' is a greater sign" +]
This step is done to make it easy to write perl code in a high level HTML editor. You do not have to care that your editor writes > instead of > in the source.
Again, sometimes you need to have such escapes in your code. You can write them
a. \> Escape them with a `\' and Embperl will not translate them. b. &gt; Write the first `&' as its HTML escape (&). A normal HTML editor will do this on its own if you enter > as text. c. Set optRawInput (see below) This will completely disable the input translation.
Since not all people writing in a high level or WYSIWYG HTML editor, there is an option to disable steps 1 and 2. You can use the optRawInput in EMBPERL_OPTIONS to tell Embperl to leave the perl code as it is. It is highly recommended to set this options if you are writing your HTML in an ASCII editor. You normally don't want to set it if you use some sort of high level HTML editor.
All carriage returns (\r) are removed from the perl code, so you can write source on a DOS/Windows platform and execute it on a UNIX server. (perl doesn't like getting carriage returns in the code it parses.)
The next step generates a subroutine out of your perl code. In the above example it looks like:
sub foo { $a = "This '>' is a greater sign" }
The subroutine is now stored in the perl interpreter in its internal precompiled format and can be called later as often as necessary without doing steps 1-4 again. Embperl recognizes if you request the same document a second time and will just call the compiled subroutine. This will also speed up the execution of dynamic tables and loops, because the code inside must be compiled only on the first iteration.
Now the subroutine can be called to actually execute the code.
If Embperl isn't executing a [+ ... +] block we are done. If it is a [+ ... +] block, Embperl needs to generate output, so it continues.
Our example returns the string:
"This '>' is a greater sign"
The greater sign is literal text (and not a closing html tag), so according to the HTML specification it must be send as > to the browser. In most cases this won't be a problem, because the browser will display the correct text if we send a literal '>'. Also we could have directly written > in our perl string. But when the string is, for example, the result of a database query and/or includes characters from national character sets, it's absolutely necessary to send them correctly escaped to the browser to get the desired result.
A special case is the <A> HTML tag. Since it includes a URL the text must be URL-escaped instead of HTML-escaped. This means special characters like `&' must be sent by there hexadecimal ASCII code and blanks must be translated to a `+' sign. If you do not do this your browser may not be able to interpret the URL correctly.
<A HREF='http://host/script?name="[+$n+]"'>
When $n is "My name" the requested URL, when you click on the hyperlink, will be
http://host/script?name=My+name
In some cases it is useful to disable escaping. This can be done by the variable $escmode.
Example: (For better readability, we assume that optRawInput is set. Without it, you need to cover the Embperl pre-processing described in steps 1-3.)
[+ "<FONT COLOR=5>" +] This will be sent to the browser as <FONT COLOR=5>, so you will see the tag on the browser screen instead of the browser switching the color. [+ local $escmode=0 ; "<FONT COLOR=5>" +] This will (locally) turn off escaping and send the text as a plain HTML tag to the browser, so the color of the output will change.
Now everything is done and the output can be send to the browser. If you haven't set dbgEarlyHttpHeaders, the output is buffered until the successful completion of document execution of the document and sent to the browser along with the HTTP headers. If an error occurs an error document is sent instead.
The content length and every <META HTTP-EQUIV=...> is added to the HTTP header before sending it. If Embperl is executed as a subrequest or the output is going to a file no http header is sent.
To get the best performace from Embperl, it is necessary to restrict logging to a minimum. You can drastically slow down Embperl if you enable all logging options. (This is why `make test' takes a while to run.) You should never enable dbgFlushOutput, dbgFlushLog or dbgCacheDisable in a production environment. More debugging options are useful for developement where it doesn't matter if the request takes a little bit longer, but on a heavily-loaded server they should be disabled.
Also take a look at mod_perl_tuning.pod for general ideas about performance.
None known.
Under perl5.004 there are memory leaks. This is not an Embperl bug, but can cause your httpd to grow endlessly when running under mod_perl. Please upgrade to perl5.004_04 to fix this. You should also upgrade to a mod_perl version higher than 1.07_01 as soon as possible, because until 1.07_01 there is a memory leak in Apache->push_handler.
I have tested Embperl succesfully
on Linux 2.x with
perl5.004_04 apache_1.2.5 apache_1.2.6 apache_1.3b3 apache_1.3b5 apache_1.3b6 apache_ssl (Ben SSL) Stringhold 2.2
on Windows NT 4.0 with
perl5.004_04 apache_1.3b5
on Windows 95 with perl5.004_02 (binary distribution) Offline mode
I know from other people that it works on many other UNIX systems
Please let me know if you use or test this module. Bugs, questions, suggestions for things you would find useful, etc., are discussed on the mod_perl mailling list.
>From the mod_perl README:
The Apache/Perl mailing list (modperl@apache.org) is available for mod_perl users and developers to share ideas, solve problems and discuss things related to mod_perl and the Apache::* (and Embperl) modules. To subscribe to this list, send mail to majordomo@apache.org with the string "subscribe modperl" in the body.
There is a hypermail archive for this list available from: http://outside.organic.com/mail-archives/modperl/
There is an Epigone archive for the mod_perl mailing list at http://forum.swarthmore.edu/epigone/modperl
You can get free support on the mod_perl mailing list (see above). If you need commercial support (with a guarantee for response time or a solution) for Embperl or want a web site where you can run your Embperl/mod_perl scripts without setting up your own web server, please send email to info@ecos.de.
mod_perl http://perl.apache.org/ mod_perl FAQ http://perl.apache.org/faq Embperl http://perl.apache.org/embperl.html apache web server http://www.apache.org/ ben-ssl (free httpsd) http://www.apache-ssl.org/ stronghold (commerical httpsd) http://www.c2.net/ europe http://www.eu.c2.net/ see also http://www.perl.com/CPAN/modules/by-module/Apache/apache-modlist.html
G. Richter (richter@dev.ecos.de)
perl(1), mod_perl, Apache httpd
6 POD Errors
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head2'
You forgot a '=back' before '=head1'
Non-ASCII character seen before =encoding in '-> '. Assuming CP1252
'=item' outside of any '=over'
To install HTML::Embperl, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HTML::Embperl
CPAN shell
perl -MCPAN -e shell install HTML::Embperl
For more information on module installation, please visit the detailed CPAN module installation guide.