perl

Executes the Perl code, contained in the tag's body text, and returns the result.

Summary

[perl tables] Perl code [/perl]

Parameter	Description	Default
tables	Database tables to be made available to Perl code.	None
table	Alias for tables.	None
failure	Return the specified value if the Perl code fails to evaluate.	None
no_return	Suppress this tag's return value.	No
subs	Allow calls to GlobalSub routines, from within the enclosed Perl code, if AllowGlobal is also set.	No
arg	Same as subs (arg="subs")	No
global	Turn off Safe protection within the Perl code if AllowGlobal is also set.	No
file	Prepend the contents of the specified file or FileDatabase entry to the enclosed Perl code.	None
number_errors	Add line numbers to the source code displayed in the error.log file.	No
short_errors	Only logs errors - not the whole block of Perl code.	No
trim_errors	On error, only the specified number of lines before and after the broken line will be logged.	No
hide	Suppress any output text that would ordinarily be returned from this tag. (This universal parameter was introduced with Interchange version 5.5.2.)	No
interpolate	Parse Interchange tags, included in the body text, before this container tag executes.	No
reparse	Process any Interchange tags found in the text output from this tag.	Yes

Examples

Tag expansion example

[perl]
my $foo = 'Hello world'
return $foo;
[/perl]

Hello world

Perl example

$Tag->perl({
tables => $tables,
body => $perl_code,
});

or similarly with positional parameters:

$Tag->timed_build($tables, $attribute_hash_reference, $perl_code);

Description

This tag allows you to embed Perl code within an Interchange page. The code will run under the restrictions of Perl's

Safe module by default.

Perl's "warnings" and "strict" pragmas are both turned off and, since it blocks Perl's "use" command,

Safe will block you from turning them on. This is not usually a problem, as you should probably use an alternative such as a UserTag if your code is complex enough to need "strict".

This tag expands to the value returned by the enclosed code and so printing to STDOUT or STDERR is useless.

[perl]
$name = $Values->{name};
$browser = $Session->{browser};
return "Hello, $name. How do you like your $browser?"
[/perl]

Object references are available for most Interchange tags and functions, as well as direct references to Interchange session and configuration values. See Interchange Perl objects for more information.

The [perl] tag will remember variable values inside the current page, unless scoped with "my", so you can do the equivalent of a memory store and recall for a loop. Having said that, you must ensure that unscoped variables are initialised to a known value before they are used, as their default value cannot be relied upon.

Also see the [calc] and [calcn] tags.

Parameters

tables

This should be a whitespace-separated list of database tables you want to make available within your Perl code.

If you would like to use database values in your Perl code then the tag must pre-open the table(s) you will be using. Here is an example using the products table:

[perl tables="products"]
my $cost = $Tag->data({
table => 'products',
column => 'our_cost',
key => $Values->{code},
});
$min_price = $cost * ($min_margin + 1);

return ($min_price > $sale_price) ? $min_price : $sale_price;
[/perl]

If you do not pre-open your tables then your code will fail, with a runtime

Safe error, when it tries to use the [data] tag to look up "our_cost" in the products table.

Even if you properly specify the tables to pre-open, some database operations will still be restricted because

Safe mode prohibits creation of new objects. For SQL, most operations can be performed if the

Safe::Hole module is installed. Otherwise, you may have to set the global=1 attribute to use data from SQL tables.

Interchange database tables can always be accessed as long as they are pre-opened by using an item first.

Safe objects (including database handles) may persist within a page, and the [perl] tag does not necessarily destroy objects created earlier in the page. As a result, your code may work even though you did not specify the "tables" properly, only to break later when you change something elsewhere on the page.

For example, this will work because the first call to [accessories] "opens" the (default) products table:

[accessories code="os28044" attribute="size"]

[perl]
return $Tag->accessories({
attribute => 'size',
code => 'os28085',
});
[/perl]

If you remove the first [accessories] tag, then the $Tag->accessories() call will fail with a

Safe error, unless you also specified tables=products in your call to the [perl] tag.

The moral of this story is to ensure that you pass all necessary tables in the [perl] tag.

failure

If your code contains a compile or runtime error, and fails to evaluate (i.e. eval($code) would set $@), the [perl] tag will return the value set for the failure attribute. The error will be logged as usual.

For example:

[perl failure="It Broke"]
my $cost = $Tag->data('products', 'our_cost', $Values->{code});
$min_price = $cost * ( 1 + $min_margin );
return ($min_price > $sale_price) ? $min_price : $sale_price;
[/perl]

will return "It Broke" because the $Tag->data() call will fail under the

Safe module. See the tables parameter for the reason why.

no_return

If no_return=true ("1", "Yes" or "True") then the Perl code's return value will be suppressed.

You can retrieve the return value from the session hash via [data session mv_perl_result] until it gets overwritten by another [perl] tag's result value.

If no_return is true then the [perl] tag will still return any output explicitly written with the &HTML or $Document->write() functions.

If no_return is not set then the $Document->write() buffer will not be returned (unless you use $Document->hot(1) or $Document->send(), in which case the contents of the write buffer will probably appear before anything else on the page). See the Interchange Perl objects page for more information.

Here is an example:

[perl tables="products" no_return=1]
my $cost = $Tag->data('products', 'our_cost', $Values->{code});

$min_price = $cost * ( 1 + $min_margin );
&HTML( ($min_price > $sale_price) ? $min_price : $sale_price );
return ($min_price > $sale_price) ? 'too low' : 'ok';
[/perl]

This will put the same price on the page as our earlier example, but $Session->{mv_perl_result} will be set to either "too low" or "ok".

Deprecation notice

The arg parameter was deprecated in Interchange 5.5.2. Please do not make use of this parameter as it may be removed, without warning, at any time. See the hide parameter, which was created in version 5.5.2

subs

If you have set the AllowGlobal configuration directive then passing this parameter with a "1", "Yes" or "True" value will enable you to call GlobalSub routines from within the enclosed Perl code.

Security warning

This can compromise security.

arg

If arg="subs" then this is exactly the same as the subs parameter.

global

If you have set the AllowGlobal configuration directive then setting the global paremeter to "1", "Yes" or "True" will turn off

Safe protection within the Perl code.

Security warning

The enclosed Perl code will be able to do anything the user ID running Interchange can do. This seriously compromises security, and you should know what you are doing before using it on a public website. It is especially dangerous if a single Interchange server is shared by multiple companies or user IDs.

Full "use strict" checking is turned on by default when in global mode. You can switch strict checking off by using "no strict" within your code. Note that any strict errors will go to the Interchange error logs, and the [perl] tag itself will fail silently within the page.

file

This prepends the contents of the specified file or FileDatabase entry to the enclosed Perl code (if any), and then executes as usual.

For example:

[perl file="my_script.pl"][/perl]

The above would execute myscript.pl and expand to its return value.

Absolute filenames (filenames starting with "/" or containing "../") are prohibited by the NoAbsolute configuration directive.

If the filename is not absolute then Interchange will first look for a file in the current directory. If it fails to find the named file in the current directory then it will look in the list set with the TemplateDir configuration directive(s). If it still fails to find the file then it will look for an entry by that name in the FileDatabase table.

number_errors

Add line numbers to the source code displayed in the error.log file. This is amazingly useful if some of the Perl is being generated elsewhere, interpolated into the [perl] body and then executed.

eval_label

This will will replace the "(eval ###)" in the error message with the specified label string. This is useful for quickly tracking down bugs when you have more than one [perl] block in the page - especially if you are also using short_errors.

short_errors

If set to a true value, syntax errors and the like in [perl] tags will log just the error, not the whole source code of the block in question. This is handy when you have the code open in an editor anyway, and don't want the error itself to get scrolled away when running "tail -f error.log".

trim_errors

If set to a number, and the error produced includes a line number, only the specified number of lines before and after the broken line will be logged, instead of the whole block.