View source for Help:Lua for beginners

{{WikiProject Lua header}}
{{Selfref|This help page is meant to provide some basic orientation for those new to Lua/Scribunto.}}

== Overview ==
[[WP:Lua|Lua]] is a programming language implemented on Wikipedia with some substantial restrictions via [[mw:Extension:Scribunto|Scribunto]].  Its purpose is to allow you to process the data which is available on Wikipedia content pages to allow various sorts of customized display of information.

The most important help file is the [[mw:Extension:Scribunto/Lua reference manual|MediaWiki Scribunto Lua reference manual]], which provides a concise summary of the language and standard library calls as implemented on MediaWiki. 

The general, non-MediaWiki [http://www.lua.org/manual/5.1/manual.html Lua reference manual] can—while being very well written, comprehensive, and informative—be problematic for beginners, because certain features don't work in Wikipedia—beginning with <code>print()</code>, which appears in standard Lua "hello world" programs.

== Issues with the current implementation ==
Besides the lack of <code>print()</code>, there are other features missing – see [[mw:Extension:Scribunto/Lua reference manual#Differences from standard Lua|Differences from standard Lua]] for a complete list.

At the present time, it is advisable to use ''[[mw:Extension:Scribunto/Lua reference manual#Ustring library|mw.ustring]]'' functions instead of ''[[mw:Extension:Scribunto/Lua reference manual#String library|string]]'', because the latter sometimes fails with Unicode characters.

== Input ==
The programs are run only when the page is "parsed" (when it or a page it incorporates is changed or previewed), not every time you view the output.  Therefore there can be no convenient Lua module that allows you to type in a Fahrenheit temperature in an input box and get back the corresponding Celsius temperature when you press a button, or allows you to click on a segment of a Mandelbrot set visualization on a page to expand it as often as you like. There has to be an actual Wiki page (or at least a page you have submitted for preview) containing the input data.

However, it is possible to use library functions like mw.title.new to import content from any text content page on the Wiki. You cannot, however, import data from files, not even .svg files which contain XML text data.

== Calling a Lua module ==
Lua calls look much like [[WP:template|template]]s, and consist of a small block of text like 

{{mlx|ConvertNumeric|decToHex|73}}, giving {{#invoke:ConvertNumeric|decToHex|73}}

This text calls the Lua script itself, which is housed in the <code>Module:</code> [[WP:namespace|namespace]].  The effect of this call is to send the information within the <code>#invoke</code> block to the Lua module, and to replace everything within the brackets with a piece of text that it sends back in return.  (Literally, in the "return" statement)

Note that the first "parameter", in this case <code>decToHex</code>, is actually a ''function'' called within the Lua module.  This field must always be included in any <code>#invoke</code>. To those unfamiliar with modules, especially Wikipedia template coders who expect anything after <code>|</code> to be a parameter, the need for this extra field is surprising, especially if all uses of the module depend on its presence. When documenting your work for them it is useful to include an explicit usage instruction like <code><nowiki>{{mlx|ConvertNumeric|decToHex|73}}</nowiki></code> so that they understand not to omit it.

For many existing modules, an example <code>#invoke</code> of the script (and little else) is provided on the <code>Module talk:</code> page.  It is convenient for authors to be able to flip quickly to the talk tab to look at the effects of their changes, but you should never transclude the talk page as a template - people might actually talk on it! Alternatively, the module page can show documentation from a separate /doc-page (as [[Module:WikidataIB]] does).

=== Another example: Using LuaCall to perform a single Lua instruction ===
As a beginner, or in casual talk page conversation, you might only have one little calculation you want to use Lua for but don't want to write a full module. You might find [[Module:LuaCall]] convenient for this. For example, you can test how a greedy [https://www.lua.org/pil/20.1.html Lua pattern] works:

* <code><syntaxhighlight lang="wikitext" inline style="background:none; border:none; color:inherit; padding: 0px 0px;">{{#invoke:LuaCall|main|a=bbbbbbbbbba|b=bb(.*)b(.+)bba|</syntaxhighlight>{{code|string.match(a,b)|lua}}}}</code> → <code>{{#invoke:LuaCall|main|a=bbbbbbbbbba|b=bb(.*)b(.+)bba|string.match(a,b)}}</code>

or count up the length of a [[wikipedia:Did you know|''Did you know'']] hook or the text portion of a ''Did you know'' candidate:

* <code><syntaxhighlight lang="wikitext" inline style="background:none; border:none; color:inherit; padding: 0px 0px;">{{#invoke:LuaCall|main|a=... that you can count the length of your DYK hook with a Lua module?|</syntaxhighlight>{{code|string.len(a)|lua}}}}</code> → <code>{{#invoke:LuaCall|main|a=... that you can count the length of your DYK hook with a Lua module?|string.len(a)}}</code>

In these specific examples, however, [[Module:String]] could do both of these tasks.

The script at [[Module:LuaCall]] has been written to accept any set of named parameters <code>somename=value</code>, for each one storing the string <code>value</code> in the variable with the name <code>somename</code>, and then allowing you to use these variables as parameters for any function available in Lua. The script then returns only the ''first'' value returned by the function ([https://www.lua.org/pil/5.1.html Lua functions can return multiple values], but in this case, only the first is returned from the module).

== Errors ==
Lua errors appear as red "Script error" messages. If Javascript is enabled, '''the red script error message is a link''' which usually allows you to follow it back to the line in the module where the error occurred.  There are some exceptions, for example "Module not found", if the name of the module itself is mistyped, or "The function you specified did not exist" if the function name given is invalid.

== Lua program structure: Output ==
The most fundamental part of a Wikipedia Lua program is a '''return''' statement which carries its output back to the page that had the <code>#invoke</code>. You ''can'' have a Lua function that runs without error even though it doesn't contain a return statement, but on Wikipedia it is pointless, as Lua programs cannot generally have side effects on Wikipedia.

The module itself must return a Lua '''table''' of values. A Lua table is expressed as a list of values separated by commas, within curly braces. When the module is called by <code>#invoke</code>, the '''function''' it names (the first argument after |) is looked for in that table. That function, in turn, is expected to return something that can be represented as a '''string'''.

Therefore, <syntaxhighlight lang="lua" inline>return { mw.ustring.gmatch( "Hello world", "(.*)" ) }</syntaxhighlight> is actually a complete Lua module (though a very strange one) - it returns the function returned by mw.ustring.gmatch (an iterator function listed in the Lua reference cited above) as the one and only element in an array (represented within <code>{}</code>)—which when executed using <syntaxhighlight lang="wikitext" inline>{{#invoke:ModuleName|1}}</syntaxhighlight> yields the string "Hello world". ''However'', things are not usually done this way.  Typically we use the overall form:

<syntaxhighlight lang="lua">
local p = {} -- Defines a variable p as an empty table, but *not* nil.

function p.main( frame ) -- This block defines the table element p["main"] as a function.
    return "Hello world" -- The string result of the function.
end -- Ends the block defining the function object p["main"] (or p.main).

return p -- This returns the table p, which under the key "main" contains the 
    -- function above (p.main), which when called returns string "Hello world".
</syntaxhighlight>

Note that <syntaxhighlight lang="lua" inline>function p.main(frame) ... end</syntaxhighlight> is equivalent to <syntaxhighlight lang="lua" inline>p.main = function(frame) ... end</syntaxhighlight> or  <syntaxhighlight lang="lua" inline>p["main"] = function(frame) ... end</syntaxhighlight>. The function is just another type of value, retrieved with the key <code>"main"</code> from table <code>p</code>.  If you want to allow users to invoke the same module with <code><nowiki>{{#invoke:</nowiki>''module-name''<nowiki>|hello}}</nowiki></code> instead of <code><nowiki>{{#invoke:</nowiki>''module-name''<nowiki>|main}}</nowiki></code>, you can write <code>p.hello = p.main</code> to copy the reference to this function to a new key in the table. You can even write <code>p[""] = p.main</code>, which causes <code><nowiki>{{#invoke:</nowiki>''module-name''<nowiki>|}}</nowiki></code> to produce the same output as <code><nowiki>{{#invoke:</nowiki>''module-name''<nowiki>|main}}</nowiki></code>. Learning to think of functions as a data type becomes very important later on for working with library functions like <code>[[mw:Extension:Scribunto/Lua_reference_manual#string.gsub|mw.ustring.gsub]]</code>, and constructing iterator functions.

== Lua program structure: Input ==
The '''<code>frame</code>''' parameter above (which is pretty much always given this name in Wikipedia Lua modules) receives another table, which is passed ''from'' the page that makes the call ''to'' the Lua module. It contains a surprising amount of stuff, of which just a few things concern the novice.

=== Arguments ===
{{see also|Module:Arguments}}
<code>frame.args</code> contains ''another'' table, namely, all the content sent by the user within the <code>#invoke</code> brackets except the first argument which states the name of the function to be executed. So in {{Mlx|ConvertNumeric|decToHex|3377}}, the string <code>"3377"</code> is the content of <code>frame.args[1]</code> (which is the same as <code>frame["args"][1]</code> but ''not'' the same as <code>frame.args["1"]</code> or <code>frame["args"]["1"]</code>). Unnamed parameters come out with numbers as keys (<code>frame.args[1]</code>, <code>frame.args[2]</code>, etc.), while named parameters come out with the parameter names (strings) as keys (<code>frame.args["count"]</code>, <code>frame.args["style"]</code>, etc.). 

''Example:''<blockquote><code><nowiki>{{#invoke:</nowiki>''modulename''|''functionname''<nowiki>|3377|4|count=3|style=bold}}</nowiki></code> </blockquote>results in<blockquote><code>frame.args[1]</code>=3377, <code>frame.args[2]</code>=4, <code>frame.args["count"]</code>=3, <code>frame.args["style"]</code>=<code>"bold"</code>.</blockquote>

=== Parent frame ===
Within <code>frame</code> there is a ''parent'' frame, referring to the page that called the page that gives the script, and you can pull out arguments from that also. Just write

<code>parent=frame.getParent(frame)</code>

and <code>parent.args</code> will contain those arguments.

It is popular in Lua to use the synonymous statement <code>parent=frame''':'''getParent()</code>, cancelling the need to write <code>frame</code> twice. Note the colon (<code>:</code>) instead of the dot (<code>.</code>). <code>parent=frame:getParent()</code> means exactly the same as <code>parent=frame.getParent(frame)</code>. For novices this can be confusing, and it is important to be aware of this idiom. If you use it in the wrong way, though, the script errors are pretty good at pointing out that this was the mistake.

== Basic debugging ==
{{Main|Help:Lua debugging}}
Debugging can start as soon as you write programs, and can be done simply with string concatenation.
Just set up a variable with some recognizable name like "debuglog" in your main function (p.main) with a statement like <syntaxhighlight lang="lua" inline>local debuglog=""</syntaxhighlight>.  This initial {{code|""}} definition helps because otherwise it will be '''nil''' and concatenating a string to nil gets you an error.  Now whenever you have a variable you'd like to test, say {{tt|x}}, just write <syntaxhighlight lang="lua" inline>debuglog = debuglog .. "x=" .. tostring(x)</syntaxhighlight>, and have at the end of your program <syntaxhighlight lang="lua" inline> return output .. debuglog</syntaxhighlight>  The "{{tt|tostring}}" is a function to ensure {{tt|x}} is interpreted as a string, so that if it is an table, nil, etc. it will display as "{{samp|table}}", "{{samp|nil}}", etc. rather than as Script error.

== Format ==
The [[WP:Lua style guide]] gives some basic formatting suggestions expected by the JavaScript module editor, such as using four-space indentations and keeping if, then, else, end at the same level of indentation.

Comments to the end of a line are marked by {{code|--}} .  ''Use them.''  Many modules for Wikipedia have a straightforward, linear design, but that doesn't mean it won't help to have your sections clearly labelled when you go back to the code for the hundredth time.  The Lua style guide gives additional recommendations for using functions to keep your work more organized.

== Exasperating bugs ==
Some bugs you might want to keep in mind:

* ''Attempt to call a string value.''  It means you forgot the .. between a string and a variable somewhere in a mess of stuff you're concatenating.
* A variable ignores all your efforts to assign stuff to it.  You may have inadvertently written ''two'' local statements - the one sets the value of the variable within a limited region, and when the program leaves that region, you're back to the old value.
* A numbered table entry ignores all your efforts to assign to it.  This is because {{code|a["50"]}} '''is not''' {{code|a[50]}}.  Typically you have processed a parameter (which you may have received from the invoke as a string) with string functions in one place, but performed numeric operations in another, leaving you with two different types of variable to use for an index. 
* Some graphics you're trying to display are heading off to the hills.  (actually a HTML error) You didn't close your {{tag|div|c}}s, so all the top: and left: styles keep adding up.
* ''{{code|... nil ...}}''  There are all sorts of things you can't do to a nil variable, like assign <code>x.somefield</code> or {{code|x[n]}} if {{tt|x}} is nil, concatenate <code>a .. b</code> if {{tt|a}} or {{tt|b}} is nil, or evaluate {{code|a[x]}} if {{tt|x}} is nil.  Initialize such variables with (local) {{tt|1=x={}, a=""}}, etc.  Often "global" is mentioned in these errors because you didn't have a {{tt|local}} statement for the nil variable.
* ''string expected, got function.'' Some important things like {{tt|mw.ustring.gmatch}} actually return ''functions'', not strings - see [[#Functions|Functions]] below.
* ''no such module.'' You {{code|#invoked}} a module that didn't exist {{--}} or wrote {{code|#invoke:Module:x}} instead of {{code|#invoke:x}}.
* ''the function specified did not exist.''  You {{code|#invoked}} a module, but the field after the name of the module is wrong.  Often this field expects a standard name like "main", and you've forgotten it and gone straight to the first data parameter.  If you're unsure of the function name, check the module documentation, or look for what function(s) in the code accept a "frame" parameter.

== Understanding tables and related concepts ==
* An '''expression list''' is a set of values separated by commas.  The values can be strings, numbers, tables, functions, etc.
* A '''sequence''' is a set of entries with indices from 1 to N, where N is a positive integer.  They can be created by placing brackets around an expression list.  For example, if <syntaxhighlight lang="lua" inline>a={1, "quotation", mw.ustring.gmatch("abca","a"), {2,3,4}}</syntaxhighlight> then <code>a[1]</code>=1, <code>a[2]</code>="quotation", <code>a[3]</code> is the function returned by <code>gmatch()</code>, and <code>a[4]</code> is the table <code>{2,3,4}</code>.  An expression list can also be recovered from a table using <code>unpack()</code>:  <code>b, c, d = unpack(a)</code> will set <code>b</code>=1, <code>c</code>="quotation", and <code>d</code> as the function returned by <code>gmatch()</code>; <code>{2,3,4}</code> will be discarded in this case.
* A '''table''' is a sequence, optionally supplemented by named keys: <code>digit["two"]="2"</code>.  Several table functions like <code>table.concat</code> will only work with the numbered values and ignore named keys.
* The '''metatable''' offers a large, optional set of methods for altering table behavior.  For example, you can define a table to be callable like a function.

=== Initializing a table ===
It is often useful to create a whole table at once in a statement. There are many equivalent ways to do this, but the shortcuts don't work for every kind of value. To begin with, the most general way is to assign each key and value explicitly:

<syntaxhighlight lang="lua" inline>a = {[0]='zero', [1]='one', ['1']='string for one'}</syntaxhighlight>

If sequence keys (positive integers) are given in order, only the values need to be given, so the following will assign <syntaxhighlight lang="lua" inline>'one'</syntaxhighlight> to <syntaxhighlight lang="lua" inline>a[1]</syntaxhighlight>:

<syntaxhighlight lang="lua" inline>a = {[0]='zero', 'one', ['1']='string for one'}</syntaxhighlight>

If a key has only letters, digits, and underscores, and begins with a non-digit, the brackets and quotation marks can be omitted:

<syntaxhighlight lang="lua" inline>a = {a='one', b='two'}</syntaxhighlight>

This is identical to <syntaxhighlight lang="lua" inline>a = {["a"]='one', ["b"]='two'}</syntaxhighlight>.

However, this will fail for keys that begin with a digit: <syntaxhighlight lang="lua" inline>hex = {7f = 127}</syntaxhighlight> will produce an error; use <syntaxhighlight lang="lua" inline>hex = {['7f'] = 127}</syntaxhighlight> instead.

Note that when given ''within'' brackets, or to the right of the equal sign, quotation marks are needed, or else string values will be taken as variables:

<syntaxhighlight lang="lua" inline> a = {[b] = c}</syntaxhighlight>

assigns the value of variable ''c'' to the key ''contained in variable'' ''b''.

== Functions ==
* Functions can return any kind of value {{--}} ''including a function''.  This is a powerful feature that can readily confuse the beginner.  If you set <syntaxhighlight lang="lua" inline>a=mw.ustring.gmatch(text, "(.)")</syntaxhighlight>, the result assigned to <code>a</code> will be a '''function''', not a string character! However, assigning <code>b=a()</code> by calling the function stored in <code>a</code> will return the first match (a string). Every time you set <code>b=a()</code> after that you'll get another match (string) into <code>b</code>, until you run out of matches and get <code>nil</code>.  Many '''iterator functions''' act this way.
* You can keep separate counts for iterator functions by using different variables. For example, if you set <syntaxhighlight lang="lua" inline>q=mw.ustring.gmatch(text, "(x.)")</syntaxhighlight> in the same module, you can pull characters from the same piece of text (<code>text</code>) by evaluating <code>d=q()</code> without losing your place in <code>a()</code>.
* [[tail call|Tail calls]] offer substantial benefits in performance for those who master the language.
* Function names are often of the form {{code|p.myFunctionName}}, where p is the table from the {{code|return p}} at the bottom of your program.  The reason for this is that you can only access functions that are entries in this table from the original {{code|#invoke}} statement.  Functions for local use within the program can have any name.

== Understanding patterns ==
''Note:'' Lua patterns are ''not'' [[regular expression|regular expressions]] in the traditional POSIX sense, and they are not even a subset of regular expressions. But they share many constructs with regular expressions (more [[Help:Lua for beginners#regex|below]]).

Lua patterns are used to define, find and handle a ''pattern'' in a string. It can do the common search and replace action in a text, but it has more options that doing plain text only. For example, in one go it can change the errors 'New yorker', 'New-Yorker', and 'NewYorker' into 'New Yorker'.

* To begin with, a pattern works like a plain string so long as it doesn't contain the special characters {{code|^ $ () % . [] * + - ?}}

* Square brackets {{code|[ ]}} are used to match ''one'' ''single character'' in the string from a list of choices. {{code|[abc]}} matches the letters a, b, or c.  With {{code|^}} right after {{code|[}} they indicate "anything but": {{code|[^abc]}} = not a, b, or c.  Inside brackets and when not the first character, a minus {{code|-}}indicates a range: {{code|[a-z]}} matches one single character from a, b, c, …, z. 

* Period {{code|.}} matches any character.

* Percent {{code|%}} indicates a large set (class) of possible character matches when it is followed by a letter.  See [https://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual#Character_class] for a full list. <!--- should test/list these empirically to be sure --->  When followed by punctuation (whether a special character above or not) the {{code|%}} is removed and the punctuation is taken as a literal character; {{code|%%}} = literal %.  Special classes include a balanced class {{code|%bxy}} and {{code|%f[set]}}; see the link above for more.

* Parentheses {{code|( )}} indicate captures.  The captures can be accessed later in the search string or in the string.gsub replacement string as {{code|%1}} to {{code|%9}}, and are returned by string.match as an expression list of results.

* The qualifiers {{code|? - * +}} specify repetitions of a single character (not a longer string).
:* {{code|?}} means 0 or 1 repetitions: {{code|a?}} matches "a" or "".
:* {{code|-}} means 0 or more repetitions, choosing as few as possible to achieve a match ("non-greedy").  For example {{code|2=lua|string.match("bbbb", "(.-)")}} yields "", which is less than useful because there is nothing to root the ends of the expression and prevent it from matching zero characters.
:* {{code|*}} means 0 or more repetitions, choosing as many as possible ("greedy").  For example {{code|2=lua|string.match("bbbb", ".*")}} yields bbbb.
:* {{code|+}} means 1 or more repetitions, choosing as many as possible ("greedy").

Note that the greediness of the ''leftmost'' qualifier rules over all others when there is a choice: {{code|(.*)b(.*)}} when matched on "bbb" will return "bb", "", while {{code|a(.-)b(.-)a}} when matched on "abbba" will return "", "bb".

* {{code|^}} and {{code|$}} indicate the beginning and end of the string if they occur in the appropriate place in the pattern. Otherwise they are literal characters. {{code|^}} is not used in the {{code|string.gmatch}} function.

The reference manual for Lua patterns is at [[:mw:Extension:Scribunto/Lua_reference_manual#Patterns|mediawiki.org]].

== {{anchor|regex}}Note on Lua patterns versus regular expressions ==
Lua patterns are ''loosely based'' on [[regular expression]]s (sometimes shortened to regex or regexp). Lua patterns deliberately lack the most complex regular expression constructs (to avoid bloating the Lua code base), where many other computer languages or libraries use a more complete set. Lua patterns are not even a subset of regular expressions, as there are also discrepancies, like Lua using the escape character <code>%</code> instead of <code>\,</code>, and additions, like Lua providing <code>-</code> as a non-greedy version of <code>*</code>. 

Here is a list of some of the things that Lua patterns lack compared to regular expressions:
* You '''cannot''' search for alternations between anything else than single characters (you '''cannot''' say <code>(his|her)</code> to choose between <code>his</code> and <code>her</code>, you can only say <code>[abc]</code> to choose between single characters <code>a</code>, <code>b</code>, or <code>c</code>).
* You '''cannot''' look for multiples of multi-letter constructs such as <code>(choo-)*choo</code> to match <code>choo</code>, <code>choo-choo</code> or <code>choo-choo-choo</code>. There is no way to do this with Lua patterns.
* You '''cannot''' specify the minimum and maximum number of repetitions like <code>[0-9]{3,5}</code> (to match 3 to 5 digits); in Lua you would say <code>%d%d%d%d?%d?</code> instead in this case.
There are Lua libraries that offer more powerful options,<sup>[http://lua-users.org/wiki/PatternsTutorial]</sup> including regular expressions, but the support on Wikipedia is pretty basic. 

Wikipedia help for regular expressions (which Lua, as mentioned, does ''not'' support) is at [[Wikipedia:AutoWikiBrowser/Regular expression]].

{{Wikipedia technical help|collapsed}}

[[Category:Module help|*]]