TIP PerlPlugin is not installed on Foswiki.org.


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.


%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.


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:
my $x = 99;
$x = $x + 1;
return $x;
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)


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'"}%


Another great Foswiki extension from the wikiringlogo20x20.png 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
Home: http://foswiki.org/Extensions/PerlPlugin
Support: http://foswiki.org/Support/PerlPlugin

PackageForm edit

ExtensionClassification Development, Information structuring and Search, Interface and Visualisation, User interactivity, Workflow automation
ExtensionType PluginPackage
Compatibility Foswiki 1.0+
ImageUrl logo.gif
DemoUrl http://
SupportUrl PerlPlugin
ModificationPolicy PleaseFeelFreeToModify
I Attachment Action Size Date Who Comment
PerlPlugin.md5md5 PerlPlugin.md5 manage 153 bytes 11 Nov 2010 - 09:44 PadraigLennon  
PerlPlugin.sha1sha1 PerlPlugin.sha1 manage 177 bytes 11 Nov 2010 - 09:44 PadraigLennon  
PerlPlugin.tgztgz PerlPlugin.tgz manage 25 K 11 Nov 2010 - 09:44 PadraigLennon  
PerlPlugin.zipzip PerlPlugin.zip manage 27 K 11 Nov 2010 - 09:44 PadraigLennon  
PerlPlugin_installerEXT PerlPlugin_installer manage 4 K 11 Nov 2010 - 09:44 PadraigLennon  
Topic revision: r3 - 11 Nov 2010, PadraigLennon
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy