Wikipedia:Lua

Lua is a programming language that is safely available via the Scribunto MediaWiki extension on the Simple English Wikipedia. Lua modules can be called into wiki templates by using the {{#invoke:}} functionality of Scribunto. This extension supports Lua 5.1 as of July 2015.

Hello World! in Lua

The Lua source code is stored on a wiki page named with the Module: prefix followed by the module name. These modules are then invoked by the template {{#invoke:}}, without the Module: prefix.

The syntax of #invoke is similar to template syntax. You need to indicate a function name after the pipe | :

{{#invoke:ModuleName|functionName}}

A function is a set of instructions that takes input values, processes them, and returns an output value. This is much like what a template does: you give it arguments, it processes them, and you get a result. However, you can define many functions in one Lua module, whereas you can only define one template on one page.

Additionally, you can't just run a Lua module directly – you can only run one of the module's functions. The module is a container for the functions, and doesn't do anything by itself. So there are two reasons that we need to input a function name:

1. We can't run a module by itself.
2. Without defining a function name, Lua will not know which function it is we want to run.

We can run the function named hello in lowercase in Module:Example. You do not need to install or save anything.

1. Edit your user page.
2. Paste the following call at the beginning of a new line on your user page:

{{#invoke:Example|hello}}

3. Click Show preview. The call of the function hello in the Module:Example is replaced with the following:

Hello World!

4. Click Cancel. When prompted, click Leave.
5. Your user page remains unmodified.

Using arguments

Arguments are passed to modules in the same way that they are passed to templates. Note, however, that the text after the first pipe character is always the function name; the first positional argument is the text after the second pipe.

{{#invoke:ModuleName|functionName|argument}}

In Module:Example, the hello_to function greets different people depending on the first positional argument. It works like this.

In your user page:

# {{#invoke:Example|hello_to|Kate}}
# {{#invoke:Example|hello_to|Fred}}

1. Hello, Kate!
2. Hello, Fred!

Named arguments |key=value

{{#invoke:ModuleName|functionName|namedArgument1=value1|namedArgument2=value2}}

A third function in Module:Example, named has count_fruit uses the named arguments |bananas= and |apples= to count the number of bananas and apples we have. It can be run switching the order of arguments:

# {{#invoke:Example|count_fruit|apples=3|bananas=4}}
# {{#invoke:Example|count_fruit|bananas=5|apples=2}}

1. I have 4 bananas and 3 apples
2. I have 5 bananas and 2 apples

Most modules have a documentation page explaining what arguments can be used and what their effects will be.

Request a script

Visit en:Wikipedia talk:Lua to request help in writing a Lua script to perform a specific task on Wikipedia or another Wikimedia Foundation project.

History

Magic words, ParserFunctions, and the Lua extension were introduced. A wiki scripting language was debated (JavaScript versus Lua), followed by the development of WikiScripts. Tim Starling is a major contributor of Scribunto, initially with support for Lua.

Discussed for years, Lua was installed in 2012 for testing on test2.wikipedia.org, with open invitation to all editors to experiment with developing Lua modules. Lua was installed on the English Wikipedia in February 2013, after testing on mediawiki.org and Wikimedia test wikis.

About Lua

See also Brad Jorsch's short presentation for a basic example of how to convert a wikitext template into a Lua module.

Lua is a scripting language which can be used to research data, calculate expressions, and format results using functions or object-oriented programming. Although some Lua scripts can be kept simple, for easy understanding, Lua allows complex structures including tables, dynamic functions, and associative arrays where index subscripts can be words as well as index numbers. Lua also supports recursion of re-nested functions, so care should be taken to avoid excessive complexity where other users would not understand how to maintain a Lua module.

The following is an extract of the Lua source code of the module used for the examples above:

--[[Module:Example]]--
local p = {} -- required module (p)ackage table, initialized as an empty table
function p.hello_to(frame) -- Define the hello_to function.
    local name = frame.args[1] -- contains the firstname.
    return "Hello, " .. name .. "!"  -- Return the function's result concatenated by `..` as a string.
end  -- End the function.
return p  -- Return the (p)ackage table of the module.

A sample of Lua is highlighted by tag <syntaxhighlight lang="lua" line highlight=1 copy> ... </syntaxhighlight> placed around the Lua source code. To view some more complex examples of Lua, see article: "Lua (programming language)".

For instructions on how to use Lua within MediaWiki (and hence Wikipedia), see mw:Extension:Scribunto/Lua reference manual.

Unit testing

Lua unit testing frameworks allow an editor to execute the module with a given set of inputs and verify that the expected outputs are produced.
They are useful for detecting software regressions, where modifications to a script introduce issues.

By convention, unit tests for a module like Module:Example are placed in Module:Example/testcases.
They are executed on Module talk:Example/testcases. Each test method must begin with p:test_.

In your user page:

{{#invoke:Example/testcases|run_tests}}

Click Show preview.

All 3 tests passed.

test_hello

test_hello

	Text	Expected	Actual
Y	{{#invoke:Example | hello}}	Hello World!	Hello World!

test_hello_to

test_hello_to

	Text	Expected	Actual
Y	{{#invoke:Example|hello_to|Fred}}	Hello, Fred!	Hello, Fred!

test_stat_fruit

test_stat_fruit

	Text	Expected	Actual
Y	{{#invoke:Example|count_fruit|bananas=5|apples=3}}	I have 5 bananas and 3 apples	I have 5 bananas and 3 apples

Module:UnitTests (see the list of Lua modules it tests) and Module:ScribuntoUnit are the most widely used testing frameworks.

Wikipedia-specific features

Overall: Lua can only get input as text strings passed to the {{#invoke:}} and what can be fetched via mw.title.new(...):getContent() and frame:expandTemplate(). Lua output will not be preprocessed unless frame:preprocess() is explicitly called, meaning that template calls, parser functions, etc. in the output will not work correctly.

In a wiki page, all Lua code (including long statistics or endless while or repeat loop) is limited to 10 seconds CPU time. You can look in the source code of a rendered page to see how long a template or module took to parse.

Relative to standard Lua, Scribunto's Lua offers safe functions (see the differences from standard Lua).

Lua input limitations

Lua code in Scribunto is only run when the page is being parsed. Therefore, the only user input that Lua can receive is by page editing – it cannot create a box that calculates the square root of a number you type in, or recalculate a piece of the Mandelbrot set depending on which part of the parent set you click on.

The Lua input can use any text page on Wikipedia that can be included in another page. This does not include image files, .SVG files, category listings, or special pages such as Special:WhatLinksHere/Module:ScribuntoUnit.

Wikitext

Transcluded Wikipedia headers frequently contain a hidden code such as "UNIQ5ae8f2aa414ff233-h-3--QINU" which may need to be stripped out in order for them to be parsed effectively.

Wikilinks [[Wikipedia:Help|]] without expression after the pipe | won't work if returned as output – they need to be written explicitly as [[Wikipedia:Help|Help]].

Other pre-save transforms, such as replacing ~~~~ with signatures, will also fail to be processed. Template transclusions, parser function calls, and variable substitutions (i.e. anything with a {{...}}) will not be processed, nor will tags such as <ref> or <nowiki>.

Labeling converted templates

Please place the {{lua}} template on the documentation subpage of all templates that use Lua. It will help to better communicate Lua usage and template conversions.

Related pages

• Special:PrefixIndex/Module: – list of Lua modules
• en:Help:Lua debugging – a how-to guide about debugging Lua modules
• Module:Sandbox provides a pseudo-namespace for experimenting with Lua modules
• en:Wikipedia talk:Lua – requests for Lua-based templates or tasks
• Category:Lua-based templates – groups of Lua-based templates
• Category:Lua metamodules
• Manual:Coding conventions/Lua – standards to improve the directness of code through consistency
• mw:Extension:Scribunto/Lua reference manual and all Modules.
• Wikipedia:Advanced template coding