PerlPlugin

Embed perl scripts in Foswiki topics

This plugin allows you to embed scripts within topics, using a tightly controlled subset of Perl. The scripts will be executed on the server, and the result displayed in the topic.

Scripts are executed inside a Safe container that strictly limits what the perl script can do. By default only basic operations are permitted, as well as access to a subset of the Foswiki::Func interface. No IO operations, such as print or file manipulation are permitted, and neither is sub-process execution.

The range of permitted operations can easily be customised from the configure interface.

Usage

%PERL{"perl expression"}%

• Expands to the result of the perl expression, evaluated in a Safe container.

%PERL{topic="topic name"}%

• Expands to the result of the perl program contained between %CODE{}% and %ENDCODE% in the named topic.
• You can only use a subset of perl, as defined in the Foswiki configuration.

Examples

If the plugin is installed, the text after 'expands to' will show the result of the example.

• %PERL{"'A String'"}% expands to %PERL{"'A String'"}%
• %PERL{"101 - 59"}% expands to %PERL{"101 - 59"}%
• %PERL{topic="System.VarPERL"}% expands to %PERL{topic="VarPERL"}%

Perl code used for this example:

%CODE{"perl"}%
my $x = 99;
$x = $x + 1;
return $x;
%ENDCODE%

Because the perl expression is entered as a parameter to a Foswiki macro, the usual constraints on characters apply. Note especially that double-quotes have to be escaped using \" e.g %PERL{"my $meal=\"fish";\"I ate a $meal\""}%

Note that the same container is used for each %PERL call made during rendering. As a result, a perl function defined in one %PERL will be available in other %PERLs that are evaluated later.

• %PERL{"sub x{95};x()"}%...%PERL{"x()+164"}% expands to % PERL{"sub x{95};x()"}%...% PERL{"x()+164"}%

The %CODE...%ENDCODE% delimiters are compatible with SyntaxHighlightingPlugin, should you want to use it. Note that Foswiki macros are not available inside %CODE sections.

Because Foswiki::Func runs outside Foswiki access controls, this has to be use with care.

Note that STDOUT and STDERR are automatically appended to the result of the %PERL macro. Errors and warnings, and STDERR, are output after the normal result. So %PERL{"print '{{this}}'; print STDERR 'ouch'; 'that'"}% expands to:

%PERL{"print '{{this}}'; print STDERR 'ouch'; 'that'"}%

(You cannot suppress errors. Instead, fix your perl)

WARNING

The default configuration is designed for the following requirements:

• Basic Perl,
• Can use loops, define and call functions,
• Can call Foswiki::Func functions (except readFile and saveFile),
• print (but not open)

This provides the user with enough rope to hang your server!

For example, an infinite loop may (in some server configurations) result in a denial of service to other users. You are recommended to think carefully about the abilities of your users before enabling this configuration. You have been warned!

Another common configuration that provides a lot less rope to the end user (and thus protects your server better) is as follows:

$Foswiki::cfg{Plugins}{PerlPlugin}{Opcodes} = {
    Permit => [], # :default only
    Deny => [ ':base_mem', ':base_loop', ':base_orig' ] };
$Foswiki::cfg{Plugins}{PerlPlugin}{Share} = {}; # no access to Foswiki::Func

This denies access to looping constructs.

If you want to use an even smaller subset of Perl then you should read the Safe and Opcode manual pages.

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Check the plugin is working:

%PERL{"'Cushty'"}% expands to %PERL{"'Cushty'"}%

Info

Another great Foswiki extension from the WikiRing - working together to improve your wiki experience!

Author(s):	Crawford Currie http://c-dot.co.uk
Copyright:	© 2008-2010 Crawford Currie
License:	GPL (Gnu General Public License)
Version:	9962 (2010-11-11)
Release:	1.1.3
Change History:
1.1.3	Padraig Lennon: Foswikitask:Item9997
1.1.2	Add STDOUT and STDERR support
1.1.1	First full release
Dependencies:	Name Version Description Safe >0 Required
Home:	http://foswiki.org/Extensions/PerlPlugin
Support:	http://foswiki.org/Support/PerlPlugin