Lua/Tutorial

How to use this tutorial
This tutorial was originally developed for the 2012 Berlin Hackathon, a face-to-face event. It has been adapted for on-wiki, remote use. We encourage you to participate in improving and maintaining it.

The content hereafter is focused on established MediaWiki template developers who are new to Lua. If you're new to templates on MediaWiki, but have Lua experience, you may want to find out more about templates first. Note that some things in Scribunto do not apply to the Lua distribution.

Introduction to Lua



 * Lua scripting general information and brief historical context of its planned use in MediaWiki.
 * What is Lua? Check out the Lua.org demo if you don't want to download Scribunto just yet.
 * What is different from JavaScript and object-oriented languages we could have used?
 * Scribunto: how is the Lua implementation in MediaWiki different? Wikitext is not parsed the way you would normally expect. Parser frames are arguments in Scribunto templates. Strip markers replace certain markup, which, if it is passed, will result in placeholders instead of markup. You will need to use the Namespace:Module.
 * How you adapt for these differences.

Hands-on Lua scripting

 * Create a page in the Module:Sandbox namespace, called for example Module:Sandbox/your username/my_module like Module:Sandbox/ExampleUsername/my_module
 * Put Lua code in it, like this example:


 * Go to the module talk page.
 * Put a #invoke in it to call that new module:

Accessing template parameters
Here's a simple example of a function that uses the parameters:

Such a function can access the  object to get access to the parameters that the template was invoked with. For example, let's change the previous module so that it takes two arguments, like this:

Our Lua function can use the parameters "hair" and "brown" in either of two ways:
 * 1) Access them directly as   and , respectively (named arguments can also be used, such as   or  ).
 * 2) Iterate them using the   function, which returns a (name, value) pair for each; this is the best way to code a template that can take a variable number of parameters.

A few pitfalls to avoid:


 * 1) The parameter values are always strings, even if they are numeric in form; you can use the Lua function   if you need to treat a value as a number.
 * 2) However, numbered parameter keys are numbers, even if they are given explicitly in the template invocation (for example, the parameters in both   and   are indexed by the number 1, not the string '1'.
 * 3) With explicitly named (or numbered) parameters, leading and trailing whitespace is stripped from name and value. This is similar to template parameters.
 * 4) An empty string value is not the same as a missing value, which is  ; for example,    results in frame.args[2] being   (which will cause a script error in the example code hereinbefore), but    results in frame.args[2] being an empty string (which will not, although the resulting text will look odd).  One way to work around this is to assign the desired parameters to a local variable, and replacing nils with empty strings at this step; e.g.,

External resources for general/non-wiki Lua scripting

 * Lua 5.1 Reference Manual
 * Programming in Lua
 * Lua Quick Reference
 * #Lua-Support IRC channel for support questions