Extension:Scribunto

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

Usage
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 such as:

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.

For a more pleasant user interface, with syntax highlighting and a code editor with autoindent, install the following 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:

git clone https://gerrit.wikimedia.org/r/p/mediawiki/php/luasandbox.git cd luasandbox phpize ./configure make make install

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 reference manual

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.

Note
The environment which scripts run in is not quite the same as the one documented in the Lua reference manual.

The following functions have been modified:
 * setfenv
 * getfenv: May not be available, depending on the configuration. If available, attempts to access parent environments will fail.
 * getmetatable: Works on tables only to prevent unauthorized access to parent environments.
 * tostring: Pointer addresses of tables and functions are not provided. This is to make memory corruption vulnerabilities more difficult to exploit.
 * pcall
 * xpcall: 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. Cannot otherwise access the local filesystem.

The following packages are mostly removed. Only those functions listed are available:
 * package.*: Filesystem and C library access has been removed. Available functions and tables are:
 * package.loaded
 * package.preload
 * package.loaders: Loaders which access the local filesystem or load C libraries are not present. A loader for Module-namespace pages is added.
 * package.seeall


 * os.*: There are some insecure functions in here, such as os.execute, which can't be allowed. Available functions are:
 * os.clock
 * os.date
 * os.difftime
 * os.time


 * debug.*: Most of the functions are insecure. Available functions are:
 * debug.traceback

The following functions and packages are not available:
 * collectgarbage
 * module
 * coroutine.*: No application is known for us, so it has not been reviewed for security.
 * dofile
 * 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. If necessary, mw.log may be used to output information to the debug console.
 * string.dump: May expose private data from parent environments.

Design documents

 * /Parser interface design
 * /Victor's API proposal
 * /Documentation specification
 * /Tim's draft roadmap

Other pages

 * /Deployment priorities/
 * /Brainstorming/
 * Lua scripting - Wikimedia activity page describing deployment plan to Wikimedia sites