Help:Lua
- ← Return to Help:Contents
Creating Lua modules instead of templates is a more performant and often more readable way of text transcluding. Lua modules can be used to process complex logic, interact with MediaWiki's API, and more efficiently handle tasks that are difficult or impossible in standard wikitext.
This guide will help you get started with creating Lua modules, particularly in translating wikitext templates into Scribunto Lua modules.
Understanding Lua and Scribunto
Lua is a lightweight programming language designed for extending applications. Scribunto is an extension for MediaWiki that allows Lua scripts to be run or embedded into wiki pages. Lua code in MediaWiki is organized into "modules", which are pages in the Module namespace, just like how wikitext "templates" are pages in the Template namespace.
Creating Lua Modules
1. Learn Basic Lua Syntax: Familiarize yourself with basic programming concepts and the Lua syntax. We have a reference guide for that.
2. Start with a New Module:
- Create a new page in the Module namespace. For example, Module:MyModule.
- Begin the module with a basic Lua structure:
local p = {}
-- Module's business logic that expects all arguments
function p.doTheThing(arg)
return "Hello world: " .. tostring(arg)
end
-- The main function that extracts arguments from the MediaWiki frame
function p.main(frame)
local args = frame:getParent().args
local firstArg = args['name'] or args[1]
return p.doTheThing(firstArg)
end
return p
In the above example, two functions are made. One which expects to be called from MediaWiki using {{#invoke:MyModule|main}}. The other that does the "actual" logic which other modules and tests can use (e.g. {{#invoke:MyModule|doTheThing|test}})
3. If you are translating an existing template into a module:
- Read and fully understand the template.
- Make sure the template documentation is up-to-date. That includes any hidden arguments that were not added to the documentation.
- Update the documentation to include testing of all arguments into the template.
- Move the documentation to Module:MyModule/doc as appropriate.
- Translate the code into Lua. You may want to consult the reference guide.
- On the existing template, replace the code by invoking your module, e.g.
{{#invoke:MyModule|main}}. The preview will confirm if the code is correct or not. For big changes, you may want to create a different template for testing instead of replacing the existing one.
4. If you are creating an entirely new module from scratch:
- Create documentation for the module under Module:MyModule/doc as appropriate. Include testing of all arguments.
- Create a new template that invokes the module, e.g.
{{#invoke:MyModule|main}}.
5. Continue to change the module and documentation as appropriate.
Tips for Translating Wikitext to Lua
- Variables and Parameters: Once the args have been extracted from the frame, you can access each using args[1], args[2]... for args
{{{1}}}and{{{2}}}. For named parameters, args also supports strings e.g.args['name'] or "default"for{{{name|default}}}. - Conditional Statements: Translate wikitext conditionals like #if, #switch into Lua's if-then-else and elseif statements.
- String Manipulation: Use Lua's string functions (string.lower, string.match, etc.) to manipulate text, which are more powerful than wikitext string functions.
- Loops: For repetitive tasks, use Lua loops (for, while) instead of wikitext's repetitive code.
- Comment Your Code: Use comments (
-- comment) to explain complex parts of the script, making it easier for others to understand and maintain. - Interacting with MediaWiki API: A lot of functions are already written for you in the mw library, such as accessing other pages, parsing wikitext, or retrieving site information. See the Lua reference manual.
