Extension:Scribunto

Scribunto (Latin: "they shall write") is an extension for embedding scripting languages in MediaWiki. Currently the only supported scripting language is Lua.

The extension is incomplete. None of the interfaces are fixed at this time.

Scripts are contained within a new namespace called "Module". Each module has a collection of functions, and the functions can be called using wikitext syntax like:

Installation
Scribunto comes with bundled Lua binaries for Linux and Windows, on Intel 32 and 64 bit platforms. If you have one of these two platforms, Scribunto should work for you out of the box.

Download Scribunto to your extensions directory using git:

git clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/Scribunto.git

Then add to your LocalSettings.php:

require( "$IP/extensions/Scribunto/Scribunto.php" ); $wgScribuntoDefaultEngine = 'luastandalone';

For a more pleasant user interface, with syntax highlighting and a code editor with autoindent, install the following three extensions:


 * Extension:WikiEditor
 * Extension:SyntaxHighlight GeSHi
 * Extension:CodeEditor

Then in your LocalSettings.php after all the extension registrations, add:

$wgScribuntoUseGeSHi = true; $wgScribuntoUseCodeEditor = true;

Additional binaries
Additional Lua binaries can be obtained from http://luabinaries.sourceforge.net/ or from your Linux distribution. Only Lua 5.1.x is supported. Configure the location of the binary file with:

$wgScribuntoEngineConf['luastandalone']['luaPath'] = '/path/to/lua';

LuaSandbox
We have developed an extension to PHP written in C called LuaSandbox. It can be used as an alternative to the standalone binaries, and will provide improved performance. To install it, install the headers and library files for either Lua 5.1.x or LuaJIT 1.1.x, as well as PHP, then run:

svn co https://svn.wikimedia.org/svnroot/mediawiki/trunk/php/luasandbox cd luasandbox phpize ./configure make make install

About Lua
Lua is a simple programming language intended to be accessible to beginners. The best introduction to Lua is the book Programming in Lua. The first edition (for Lua 5.0) is available online and is mostly relevant to Lua 5.1 used by Scribunto:


 * Programming in Lua (scroll down past the book ads to find the text)

The reference manual is also useful:


 * Lua 5.1 reference manual

The Lua environment
In Lua, the set of all global variables and functions is called an environment.

Each call runs in a separate environment. Variables defined in one will not be available from another. This restriction was necessary to maintain flexibility in the wikitext parser implementation.

The environment which scripts run in is not quite the same as the one documented in the Lua reference manual. The following functions are not available:


 * loadfile, io.*, file.*: Allows local filesystem access, which is insecure.
 * load, loadstring: These were omitted to allow for static analysis of the Lua source code. Also, allowing these would allow Lua code to be added directly to article and template pages, which was not desired for usability reasons.
 * print: This was discussed on wikitech-l and it was decided that it should be omitted in favour of return values, to improve code quality.
 * coroutine: No application is known for us, so it has not been reviewed for security.
 * os.*: There are some insecure functions in here, such as os.execute, which can't be allowed. It may be possible to allow access to the time and date functions, but this is not implemented at present.
 * debug.*: Most of the functions are insecure. Any that are particularly desired will have to be reimplemented.
 * package.loaders: Loaders which access the local filesystem are not present or load C libraries are not present.
 * string.dump: May expose private data from parent environments.

The following functions have been modified:


 * We allow setfenv and getfenv, but with some restrictions on integer arguments to prevent unauthorized access to parent environments.
 * Our implementation of tostring does not provide pointer addresses of tables and functions. This is to make memory corruption vulnerabilities more difficult to exploit.
 * We allow pcall and xpcall, except that certain internal errors cannot be intercepted.
 * require can fetch certain built-in modules distributed with Scribunto, as well as modules present in the Module namespace of the wiki. To fetch wiki modules, use the full page name including the namespace.

Design documents

 * /Parser interface design
 * /API specification
 * /Documentation specification