Gpedia:Lua

Jump to navigation Jump to search
 WP:Lua
WPtalk:Lua
 Help
 
 To do
 
 Resources
mw:reference manual
 
Gpedia data structure
Subject namespaces Talk namespaces
0 (Main/Article) Talk 1
2 User User talk 3
4 Gpedia Gpedia talk 5
6 File File talk 7
8 MediaWiki MediaWiki talk 9
10 Template Template talk 11
12 Help Help talk 13
14 Category Category talk 15
100 Portal Portal talk 101
118 Draft Draft talk 119
710 TimedText TimedText talk 711
828 Module Module talk 829
Currently unused
108 Book Book talk 109
446 Education Program Education Program talk 447
2300 Gadget Gadget talk 2301
2302 Gadget definition Gadget definition talk 2303
-1 Special
-2 Media

Lua is a programming language that is available via the Scribunto MediaWiki extension on the English Gpedia. Lua code can now be embedded into wiki templates by employing the "{{#invoke:}}" functionality of Scribunto. This extension supports Lua 5.1 as of July 2015.

The Lua source code is stored in pages called modules (e.g., Module:Example). These individual modules are then invoked (by code {{#invoke:}}) on template pages (e.g. Module:Example/doc uses the code {{#invoke:Example|hello}} to print the text "Hello World!").

Running a module

Modules are run on normal wiki pages using the #invoke parser function. The syntax of #invoke is similar to template syntax, but with some differences. The most important difference is that you need to specify a function name. A function is a set of instructions that takes input values, processes them, and returns an output value.[1] 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.

Furthermore, you can't 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 doesn't do anything by itself. So there are two reasons that we need to input a function name: we can't 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 run Module:Example in this way, which has a function named "hello".

  • {{#invoke:Example|hello}} → Hello World!

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:module name|function name|first positional argument|second positional argument|named argument = value}}

In Module:Example, the "hello_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 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 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 a documentation page explaining what arguments can be used and what their effects will be.

Request a script

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

History

Sordid history. {{qif}}, ParserFunctions, Lua extension, wiki scripting language debated (JavaScript v. Lua), mw:Extension:WikiScripts, Tim writes Scribunto with initial 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 Gpedia 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 analyze 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 the source code of the module used for the examples above.

local p = {};     --All lua modules on Gpedia 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.

p.hello = function( frame )     --Add a function to "my_object".  
                                        --Such functions are callable in Gpedia
                                        --via the #invoke command.
                                        --"frame" will contain the data that Gpedia
                                        --sends this function when it runs. 
    
    local str = "Hello World!"  --Declare a local variable and set it equal to
                                --"Hello World!".  
    
    return str    --This tells us to quit this function and send the information in
                  --"str" back to Gpedia.
    
end  -- end of the function "hello"
function p.hello_to(frame)		-- Add another function
	local name = 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 module
	return "Hello, " .. name .. "!"  -- `..` concatenates strings. This will return a customized
									 -- greeting depending on the name given, such as "Hello, Fred!"
end
function p.count_fruit(frame)
	local num_bananas = frame.args.bananas -- Named arguments ({{#invoke:Example|count_fruit|foo=bar}}) are likewise 
	local num_apples = frame.args.apples   -- accessed by indexing `frame.args` by name (`frame.args["bananas"]`, or)
										   -- equivalently `frame.args.bananas`.
	return 'I have ' .. num_bananas .. ' bananas and ' .. num_apples .. ' apples'
										   -- Like above, concatenate a bunch of strings together to produce
										   -- a sentence based on the arguments given.
end

return p    --All modules end by returning the variable containing their functions to Gpedia.
-- 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 Gpedia.  All output is accomplished
-- via strings "returned" to Gpedia.

A sample of Lua is highlighted by tag "<source lang="lua">...</source>" 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 Gpedia), see mw:Extension:Scribunto/Lua reference manual.

Unit testing

A unit testing framework for Lua scripts on Gpedia is available at Module:UnitTests. It allows you to execute your script on a given set of inputs and verify that the expected outputs are produced. Unit tests are especially useful for rapidly detecting regressions, where modifications to a script introduce new (or old) problems.

By convention, unit tests for a module like Module:Example are placed in Module:Example/testcases, and are executed on Module talk:Example/testcases with e.g. {{#invoke: Example/testcases | run_tests}}. Test methods must begin with "test". A simple example from Module:Example/testcases is below.

-- Unit tests for [[Module:Example]]. Click talk page to run tests.
local p = require('Module:UnitTests')

function p:test_hello()
    self:preprocess_equals('{{#invoke:Example | hello}}', 'Hello, world!')
end

return p

For a list of all modules using unit tests, see Special:Whatlinkshere/Module:UnitTests.

There's also an alternative unit testing framework in use called Module:ScribuntoUnit, that originates from Hungarian Gpedia. Feature-wise it's very similar to Module:UnitTests, but it has a different coding style, and throws real errors that are trapped using protected calls. It also has a method to compare floats within a given precision.

Gpedia-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 (see mw: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 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 input Lua can receive includes any transcludeable text page on Gpedia. This does not 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 a category, nor the contents of non-transcludeable special pages.

Wikitext

Transcluded Gpedia 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 the Pipe trick [[Gpedia:Help|]] won't work if returned as output – they need to be written explicitly as [[Gpedia: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.

See also

Notes

  1. ^ You can also have multiple output values, but functions that do this are not normally meant to be accessed from wiki pages.
The article is a derivative under the Creative Commons Attribution-ShareAlike License. A link to the original article can be found here and attribution parties here. By using this site, you agree to the Terms of Use. Gpedia Ⓡ is a registered trademark of the Cyberajah Pty Ltd.