Extension:Scribunto

MediaWiki extensions manual - list

File:Crystal Clear action run.png Scribunto Release status: beta
Implementation	Parser extension
Description	Framework for embedding scripting languages into MediaWiki pages
Author(s)	Victor & Tim (Tim Starlingtalk)
License	No license specified
Download	Download snapshot Subversion [Help] Browse source code View code changes
Check usage (experimental) Bugs: list open list all report

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:

{{#invoke: Module_name | function_name | arg1 | arg2 | arg3 ... }}

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.

Template:ExtensionInstall

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 {{#invoke:}} call runs in a separate environment. Variables defined in one {{#invoke:}} 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

Template:OnWikimedia