Lua is a lightweightscripting language that can be embedded intemplates through theScribuntoMediaWiki extension to create scripts on English Wikipedia. Since February 2013, Lua code has been available for use on the English Wikipedia via the{{#invoke:}} function. Scribunto currently supports Lua 5.1 as of October 2022[update].
On Wikipedia, Luasource code is stored on pages called modules in the modulenamespace (e.g., the source code for a module named "Example" would be atModule:Example). Individual modules are then invoked, using thesyntax{{#invoke:<Module name>|<Function name>|(optional) param1 |param2...}}, for example:
Wikitext
Result
{{#invoke:Example|hello}}
Hello World!
Running a module
Modules are run on normal wiki pages using the{{#invoke:}}parser function. The syntax of{{#invoke:}} is similar totemplate syntax, but with some differences. The most important difference is that you need to specify afunction name. Afunction is a set of instructions that take inputted values, processes them, and returns an output value.[1] This is much like what a template does: one gives itparameters, 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.
Furthermore, you cannot just run a Lua module directly – you can only run one of the module's functions. The module is just a container for the functions, and does not do anything by itself. So there are two reasons that we need to input a function name: we cannot run a module by itself, and without specifying a function name, Lua will not know which function it is we want to run.
The simplest way to run a module from a wiki page is like this:
{{#invoke:module name|function name}}
For example, we can runModule:Example in this way, which has a function named "hello".
{{#invoke:Example|hello}} → Hello World!
Using arguments
Arguments, also known as parameters, are passed to modules in the same way that they are passed to templates. Note, however, that the text after the firstpipe character (|) is always the function name; the firstpositional argument (named parameter) is the text after thesecond pipe.
InModule:Example, thehello_to function greets different people depending on the first positional argument. It works like this:
{{#invoke:Example|hello_to|Kate}} → Hello, Kate!
{{#invoke:Example|hello_to|Fred}} → Hello, Fred!
A third function inModule:Example, namedcount_fruit, uses the named argumentsbananas andapples to count the number of bananas and apples we have. It can be run like this:
{{#invoke:Example|count_fruit|apples=3|bananas=4}} → I have 4 bananas and 3 apples
{{#invoke:Example|count_fruit|bananas=5|apples=2}} → I have 5 bananas and 2 apples
Most modules have adocumentation page explaining what arguments can be used and what their effects will be.
Currently,VisualEditor does not allow invoking modules through its interface, even though it can edit existing module invocations. A possible workaround for this is to use{{invoke}} instead. The syntax is very similar to #invoke, so, to use it on VisualEditor, its first unnamed argument must be the module's name, the second the function name, and all arguments passed to the module can be specifiedthe same way as for regular templates. Note that it won't work for modules that expect to read data from the calling template (as the calling template is{{invoke}} itself rather than the page that uses it) as the example below demonstrates:
Discussed for years, Lua was installed in 2012 for testing ontest2.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.
Lua is ascripting language which can be used to analyze data, calculate expressions, and format results using functions orobject-oriented programming. Although some Lua scripts can be kept simple, for easy understanding, Lua allows complex structures including tables, dynamic functions, andassociative arrays where indexsubscripts can be words as well as index numbers. Lua also supportsrecursion 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 the source code of the module used for the examples above.
--- Example module.-- @module example-- @alias plocalp={}--All Lua modules on Wikipedia must begin by defining a variable--that will hold their externally accessible functions.--Such variables can have whatever name you want and may--also contain various data as well as functions.--- Hello world function-- @param {table} frame current frame-- @return Hello worldp.hello=function(frame)--Add a function to "p".--Such functions are callable in Wikipedia--via the #invoke command.--"frame" will contain the data that Wikipedia--sends this function when it runs.-- 'Hello' is a name of your choice. The same name needs to be referred to when the module is used.localstr="Hello World!"--Declare a local variable and set it equal to--"Hello World!".returnstr--This tells us to quit this function and send the information in--"str" back to Wikipedia.end-- end of the function "hello"--- Hello world function-- @param {table} frame current frame-- @param {string} frame.args[1] name-- @return Hello worldfunctionp.hello_to(frame)-- Add another functionlocalname=frame.args[1]-- To access arguments passed to a module, use `frame.args`-- `frame.args[1]` refers to the first unnamed parameter-- given to the modulereturn"Hello, "..name.."!"-- `..` concatenates strings. This will return a customized-- greeting depending on the name given, such as "Hello, Fred!"end--- Counts fruit-- @param {table} frame current frame-- @param {string} frame.args.bananas number of bananas-- @param {string} frame.args.apples number of apples-- @return Number of apples and bananasfunctionp.count_fruit(frame)localnum_bananas=tonumber(frame.args.bananas)or0-- Named arguments ({{#invoke:Example|count_fruit|foo=bar}})localnum_apples=tonumber(frame.args.apples)or0-- are likewise accessed by indexing `frame.args` by name (`frame.args["bananas"]`,-- or equivalently `frame.args.bananas`.localconj_bananas=num_bananas==1and'banana'or'bananas'localconj_apples=num_apples==1and'apple'or'apples'-- Ternary operators assign values based on a condition in a compact way.-- Here, `conj_bananas` gets `'banana'` if `num_bananas` is 1, else `'bananas'`.-- Similarly, `conj_apples` gets `'apple'` if `num_apples` is 1, else `'apples'`.return'I have '..num_bananas..' '..conj_bananas..' and '..num_apples..' '..conj_apples-- Like above, concatenate a bunch of strings together to produce-- a sentence based on the arguments given.end--- Lucky function-- @param {string} a-- @param {string} b-- @return Whether a is lucky.returnp--All modules end by returning the variable containing their functions to Wikipedia.-- Now we can use this module by calling {{#invoke: Example | hello }},-- {{#invoke: Example | hello_to | foo }}, or {{#invoke:Example|count_fruit|bananas=5|apples=6}}-- Note that the first part of the invoke is the name of the Module's wikipage,-- and the second part is the name of one of the functions attached to the-- variable that you returned.-- The "print" function is not allowed in Wikipedia. All output is accomplished-- via strings "returned" to Wikipedia.
A sample of Lua is highlighted by tag<syntaxhighlight lang="lua">...</syntaxhighlight> placed around the Lua source code. To view some more complex examples of Lua, see article: "Lua (programming language)".
A fewunit testing frameworks are available for Lua scripts on Wikipedia. These 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 rapidly detectingsoftware regressions, where modifications to a script introduce new (or identify old) problems.
Module:UnitTests is the prefilled code used when creating a testcases page. You run these unit tests by placing{{#invoke:Example/testcases|run_tests}} on the testcases talk page.
For testing and step-by-step debugging of Lua modules outside of MediaWiki you can try using anmw mock (should work for all simple modules and maybe even some complicated ones).
MediaWiki-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. Also, all Lua in the page 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). And relative to standard Lua, Scribunto's Lua lacks all sorts of functions (seemw:Extension:Scribunto/Lua reference manual § 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 bypage 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 input Lua can receive includes any transcludeable text page on Wikipedia. This doesnot include graphics files (not even.SVG files, although they are actually text, unless you cut and paste it onto a Wiki text page), the list of pages listed in acategory, nor the contents ofnon-transcludeablespecial pages.
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 using thepipe trick[[Wikipedia:Help| ]] 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>. Useframe:extensionTag to add tags like<ref> or<syntaxhighlight> to output.
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.
