Editing Brighter Shores:Lua

'''Lua''' is a programming language that is integrated into the ''{{SITENAME}}'' with [[mw:Extension:Scribunto|Scribunto]]. Lua source code is run from Modules in their own namespace, and invoked with <code><nowiki>{{#invoke:Module|function}}</nowiki></code>; this should be done with a wrapper template. For example, if we have a module named "foo", then we should have a template called "Template:Foo" consisting of <code><nowiki>{{#invoke:Foo|main}}</nowiki></code> to call the module, and use <code><nowiki>{{Foo}}</nowiki></code> to use the module on pages.

For certain complex templates, Lua runs many times more efficiently than standard wikitext. It can also perform operations not available otherwise in wikitext. Unlike JavaScript, it is available to all readers, and does not need to be enabled. It is also run during parsing, rather than after.

All templates and modules should have a <code><nowiki>/doc</nowiki></code> page with at least {{t|Documentation}} or {{t|No documentation}} on it.

For an introductory guide to using Lua on the wiki see [[Help:Editing/Lua guide]].

==Helpful tips==
In order to produce Lua code that is free from bugs and to do so efficiently there's a few habits you should adopt as they will save you a lot of headaches.

===Use the debug console===
The debug console lets you test code while you're working on it. This saves you a lot of time. It also lets you avoid saving unecessary revisions just to see if your code is working. Instead you'll only be saving known working code after you're done with adding a feature. Don't wait too long though, in case your power or internet goes out.

You can test expressions such as: <pre>= 2+2</pre> which will return <pre>4</pre> as you'd expect. 

You can also call into any function that is ''visible'' from outside. If you defined this function as part of for instance table p which you're then returning to Scribunto, you can call into this function from the debug console:

<syntaxhighlight lang='lua'>
local p = {}

function p.calculate(num)
    return num + 2
end

return p
</syntaxhighlight>

<pre>= p.calculate(3)</pre> or <pre>mw.log( p.calculate(3) )</pre> yields <pre>5</pre>

If this function were instead returning a table you could inspect it like so:

<syntaxhighlight lang='lua'>
local p = {}

function p.calculate2(num)
    return { num + 1, num + 2}
end

return p
</syntaxhighlight>

<pre>mw.logObject( p.calculate2(3) )</pre>

Sometimes you might not be interested in the output and only want to check if a function works. In the above example you could have used one of the following for that:

<pre>= #p.calculate2(3)</pre>
<pre>= type(p.calculate2(3))</pre>

Of course calling any Lua function from the outside, expects the function to only take one argument, the frame object, which we can't provide in the debug console, so we have to work around that. This is usually done by providing two entry-point functions, one which takes the frame object, grabs the arguments from it an passes it on to the ''real'' function like so:

<syntaxhighlight lang='lua'>
local p = {}

function p.calculate(frame)
    local args = frame:getParent().args

    return p._calculate(args)
end

function p._calculate(args)
    local num = args[1]

    return num + 2
end

return p
</syntaxhighlight>

Normal invocation of the module will use the p.calculate() function, but now you can debug the output from the real p._calculate() function in the debug console like so:

<pre>= p._calculate({3})</pre>

===Validate all input parameters===
Make sure to check all the input parameters you get from the entry point function, and do so early on. Invalid or unexpected data will cause your program to crash or misbehave. 

===Don't repeat yourself (DRY)===
If your code has sections that look very similar there's a good chance it can be simplified. Always look for opportunities like this.

===Keep it simple stupid (KISS)===
Don't make something complicated if it doesn't need to be. Simpler code is easier to maintain. For instance maybe if you re-organized your data, it becomes much easier to handle in your code.
Also does the task at hand really need a Lua module? If the problem is simple enough maybe a template or a macro will work just as well.

===Avoid deep nesting===
If you have too many levels of indented code, that's a sign you need to break out some code and put it into functions.

===Comments===
Good commenting is basically describing what a chunk of code does, not how it works. Also do not comment every line, you should comment every function and every major block of code.

==See also==
* [[Wikipedia:Lua (programming language)]] and [[Wikipedia:Project:Lua]], for a more in-depth breakdown of the coding Language
* [[mw:Extension:Scribunto/Lua reference manual]], for the documentation of Lua as used by the Scribunto extension
* [{{fullurl:Special:AllPages|namespace=828&hideredirects=1}} Special:AllPages (namespace:Module)], for a list of all current modules
* [[Brighter Shores:Lua/Modules]], for a list of all modules, excluding Exchange and miscellaneous data pages
* [[Brighter Shores:Lua/Helper modules]], for a table of modules designed to facilitate writing other modules
* [[:Category:Lua-based templates]], for an index of templates that directly invoke Lua
* [[Special:PrefixIndex/Module:Sandbox/]], for a list of personal test modules

{{Editing guides}}
{{Lua guides}}

[[Category:Brighter Shores Wiki community|Lua]]
[[Category:Modules| ]]
[[Category:Lua-based templates| ]]