imported>Nazarzadeh |
imported>Nazarzadeh |
| Line 1: |
Line 1: |
| {{WikiProject Lua/header}}
| | #REDIRECT [[WikiShia:Lua]] |
| {{Information page|WS:Lua}}
| |
| {{Namespaces}}
| |
| | |
| [[Lua (programming language)|Lua]] is a programming language that is now available, via the [[mw:Extension:Scribunto|Scribunto]] MediaWiki extension, on the English Wikishia. Lua code can now be embedded into wiki templates by employing the "
| |
| <nowiki>{{#invoke:}}</nowiki> " functionality of the Scribunto MediaWiki extension.
| |
| | |
| The Lua [[source code]] is stored in pages called modules (e.g., [[Module:Bananas]]). These individual modules are then invoked (by code <code>
| |
| <nowiki>{{#invoke:}}</nowiki> </code>) on template pages (e.g., [[Module:Bananas/doc]] uses the code <code>
| |
| <nowiki>{{#invoke:Bananas|hello}}</nowiki> </code> 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.<ref>You can also have multiple output values, but functions that do this are not normally meant to be accessed from wiki pages.</ref> 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:Bananas]] in this way, which has one function named "hello".
| |
| | |
| * <code>
| |
| <nowiki>{{#invoke:Bananas|hello}}</nowiki> </code> → {{#invoke:Bananas|hello}}
| |
| | |
| === 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''}}
| |
| | |
| For example, in [[Module:BananasArgs]], the "hello" function greets different people depending on the first positional argument. It works like this:
| |
| * <code>
| |
| <nowiki>{{#invoke:BananasArgs|hello|Kate}}</nowiki> </code> → {{#invoke:BananasArgs|hello|Kate}}
| |
| * <code>
| |
| <nowiki>{{#invoke:BananasArgs|hello|Fred}}</nowiki> </code> → {{#invoke:BananasArgs|hello|Fred}}
| |
| | |
| BananasArgs also has a function named "count_fruit" which uses the named arguments <code>bananas</code> and <code>apples</code> to count the number of bananas and apples we have. It can be run like this:
| |
| * <code>
| |
| <nowiki>{{#invoke:BananasArgs|count_fruit|apples=3|bananas=4}}</nowiki> </code> → {{#invoke:BananasArgs|count_fruit|apples=3|bananas=4}}
| |
| * <code>
| |
| <nowiki>{{#invoke:BananasArgs|count_fruit|bananas=5|apples=2}}</nowiki> </code> → {{#invoke:BananasArgs|count_fruit|bananas=5|apples=2}}
| |
| | |
| Most modules will have a documentation page explaining what arguments can be used and what their effects will be.
| |
| | |
| == Example modules ==
| |
| * [[Module:Bananas]]: The simplest possible script, providing a single function with no arguments.
| |
| * [[Module:BananasArgs]]: Demonstrates how to access and use parameters.
| |
| | |
| == Request a script ==
| |
| Visit '''[[Wikishia:Lua requests]]''' to request help in writing a Lua script to perform a specific task on Wikishia or another Wikimedia Foundation project.
| |
| | |
| == History ==
| |
| [[mw:Manual:MediaWiki architecture#Magic words and templates|Sordid history]]. {{tl|qif}}, [[mw:Help:Extension:ParserFunctions|ParserFunctions]], [[mw:Extension:Lua|Lua extension]], wiki scripting language debated (JavaScript v. Lua), [[mw:Extension:WikiScripts]], Tim writes [[mw:Extension:Scribunto|Scribunto]] with initial support for Lua.
| |
| | |
| Discussed for years, Lua was installed in 2012 for testing on [[test2wiki:|test2.wikishia.net]], with open invitation to all editors to experiment with developing Lua modules. Lua was installed on the English Wikishia in February 2013, after testing on mediawiki.org and Wikimedia test wikis.
| |
| | |
| == About Lua ==
| |
| :''See also [[:File:WMF Tech Talk 2013-02-28 slides - Scribunto presentation.pdf|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 array]]s where index [[subscript]]s 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 example of Lua [[source code]] for a [[hello world]] function contained in [[Module:HelloWorld]]:
| |
| <syntaxhighlight lang="lua">
| |
| -- All Lua modules on Wikishia must begin by defining a variable that will hold their
| |
| -- externally accessible functions. They can have any name and may also hold data.
| |
| my_object = {};
| |
| | |
| -- Add a function to the variable. These are callable in Wikishia via the #invoke command.
| |
| -- "frame" will contain the data that Wikishia sends this function when it is called.
| |
| my_object.hello = function( frame )
| |
| | |
| -- Declare a local variable and assign data to it.
| |
| local str = "Hello World!"
| |
| | |
| -- Quit this function and send the information in "str" back to Wikishia.
| |
| -- The "print" function is not allowed, so all output is accomplished via
| |
| -- returning strings in this fashion.
| |
| return str
| |
| | |
| -- End the function.
| |
| end
| |
| | |
| -- All modules end by returning the variable containing its functions to Wikishia.
| |
| return my_object
| |
| | |
| -- We can now use this module by calling {{#invoke: HelloWorld | hello }}.
| |
| -- The #invoke command begins with the module's name, in this case "HelloWorld",
| |
| -- then takes the name of one of its functions as an argument, in this case "hello".
| |
| </syntaxhighlight>
| |
| 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 Wikishia), see [[mw:Extension:Scribunto/Lua reference manual]].
| |
| | |
| == Unit testing ==
| |
| A unit testing framework for Lua scripts on Wikishia 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 problems.
| |
| | |
| By convention, unit tests for a module like [[Module:Bananas]] are placed in [[Module:Bananas/testcases]], and are executed on [[Module talk:Bananas/testcases]] with e.g. <code>
| |
| <nowiki>{{#invoke: Bananas/testcases | run_tests}}</nowiki> </code>. Test methods must begin with "test". A simple example from [[Module:Bananas/testcases]] is below.
| |
| <syntaxhighlight lang="lua">
| |
| -- Unit tests for [[Module:Bananas]]. Click talk page to run tests.
| |
| local p = require('Module:UnitTests')
| |
| | |
| function p:test_hello()
| |
| self:preprocess_equals('{{#invoke:Bananas | hello}}', 'Hello, world!')
| |
| end
| |
| | |
| return p
| |
| </syntaxhighlight>
| |
| | |
| For a list of all modules using unit tests, see [[Special:Whatlinkshere/Module:UnitTests]].
| |
| | |
| There's also an alternative unit testing framework [[Special:Whatlinkshere/Module:ScribuntoUnit|in use]] called [[Module:ScribuntoUnit]], that originates from Hungarian Wikishia. 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.
| |
| | |
| == Wikishia-specific features ==
| |
| Overall: Lua can only get input as text strings passed to the <code>
| |
| <nowiki>{{#invoke:}}</nowiki> </code> and what can be fetched via frame:expandTemplate, frame:preprocess, and the like. Lua on Wikishia can only output wikitext not including pre-save transforms or transclusions and other <code>
| |
| <nowiki>{{...}}</nowiki> </code> constructs. 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 Wikishia. This does ''not'' include graphics files (not even [[Wikishia:SVG help|.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 [[Help:Category|category]], nor the contents of [[Help:Special|Special:]] pages.
| |
| === Wikitext ===
| |
| Transcluded Wikishia 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 of the type '''
| |
| <nowiki>[[Wikishia:Help|]]</nowiki> ''' won't work if returned as output - they need to be written explicitly as '''
| |
| <nowiki>[[Wikishia:Help|Help]]</nowiki> '''. Other pre-save transforms, such as replacing <code>~~<nowiki/>~~</code> with signatures, will also fail to be processed. Template transclusions, parser function calls, and variable substitutions (i.e. anything with a <code>
| |
| <nowiki>{{...}}</nowiki> </code>) will not be processed, nor will tags such as {{tag|ref|o}} or {{tag|nowiki|o}}.
| |
| | |
| == Labeling converted templates ==
| |
| {{lua|Module:Bananas}}
| |
| Please place the {{tl|lua}} template on the documentation subpage of all templates that use Lua. It will help to better communicate Lua usage and template conversions.
| |
| {{clear}}
| |
| | |
| == See also ==
| |
| ; English Wikishia-specific resources
| |
| * [[Wikishia:Lua style guide]] – standards to improve the readability of code through consistency
| |
| * [[Special:PrefixIndex/Module:]] – tracking of Lua modules can be done by using [[Special:PrefixIndex]]
| |
| * [[Help:Lua debugging]] – a how-to guide about [[debugging]] Lua modules
| |
| * [[:Category:Lua-based templates]] – groups of Lua-based templates
| |
| * [[Module:Sandbox]] provides a pseudo-namespace for experimenting with Lua modules
| |
| * [[WS:Lua requests]] – requests for Lua-based templates or tasks
| |
| | |
| == Notes ==
| |
| {{reflist}}
| |
| | |
| {{WikiProject Lua/header}}
| |
