Bryandamon: Created page with " == Intro == This is not a guide to Lua syntax or behavior, and it's also not documentation. What it does instead is talk about a simple example of a common use case in MediaW..."

2020-04-03T18:17:36Z

Created page with " == Intro == This is not a guide to Lua syntax or behavior, and it's also not documentation. What it does instead is talk about a simple example of a common use case in MediaW..."

New page

== Intro ==
This is not a guide to Lua syntax or behavior, and it's also not documentation. What it does instead is talk about a simple example of a common use case in MediaWiki. I'd suggest reading it as maybe a 2nd or 3rd source when trying to start coding in Lua for a wiki. My example uses Cargo, but you can do very similar things with SMW (or DPL?), or with no databasing extension at all. I also recommend the book ''Clean Code'' by Robert C. Martin. The examples in that book are in Java, but even if you don't know any Java you can still take away a lot of useful things from it.

A couple things you should keep in mind about my coding style:
* <code>data</code> is always a table queried from Cargo
* <code>processed</code> is a table created by processing that data
* <code>make</code> as the first word of a function name means "create and return an mw.HTML object"
* <code>print</code> means "add sections to the mw.html object that is the function's first argument"
* <code>tag</code> means "add a self-contained unit to an mw.html object" (e.g. a footnote)

There are more, but the point is a lot of these arbitrary-seeming names are in fact very deliberate, and globally consistent through my code base (or at least since I decided to start doing things like this). You should try to have internally-consistent conventions as much as possible so that someone reading your code knows what to expect. Have a reason for doing everything!

== How to Invoke ==
For simplicity, on this page I use the <code>invoke</code> parser function directly, e.g. <code><nowiki>{{#invoke:CatsAdoptedTable|main}}</nowiki></code>. But usually you will want to put your invokes inside of templates so that users don't have to worry about the specific syntax - and also to add an extra layer between your call of the code and the definition of where the code is, so if you decide to reorganize things later and your function is no longer called <code>main</code>, it's just a single replacement to change it later. Making potential future changes easy is a constant theme in coding.
== Goal ==
Let's adopt some cats! Check out the data at [[Help:List of Adopted Cats]]. We want to build a table based on that data that looks like this:
<pre>{|class="wikitable"
| rowspan = 3 | Sunday || Luna
|-
|Chloe
|-
|Bella
|-
| Monday || Lucy
|}</pre>
{|class="wikitable"
| rowspan = 3 | Sunday || Luna
|-
|Chloe
|-
|Bella
|-
| Monday || Lucy
|}

As you can see, this is pretty easy to do but it requires that we know ahead of time how many cats were adopted each day so that we can set the correct rowspan. So what if we want to automate this data? Let's use Lua. You can check the final source at {{mod|CatsAdoptedTable}}.

== Writing Our First Lua Module ==
Check out {{mod|HelloWorld}}. It contains the following code:
<syntaxhighlight lang="lua">local util_args = require('Module:ArgsUtil')

local h = {}

local p = {}
function p.main(frame)
local args = util_args.merge(true)
return args.kittens
end
return p</syntaxhighlight>
When we run this in the main wiki, we get the following:
<pre>{{#invoke:HelloWorld|main|kittens=cute}}</pre>
{{#invoke:HelloWorld|main|kittens=cute}}

Don't worry what <code><nowiki>util_args.merge(true)</nowiki></code> does. In fact, all of this is pretty much just boilerplate code other than the line <code>return args.kittens</code>. You can use the rest as a copy-paste basis for everything (assuming you have a module like {{mod|ArgsUtil}} that grabs the template arguments for you on your wiki).
== Writing Our First Lua Module That Does Something ==
=== Cargo ===
First of all, just trust me that the following code will return us a Cargo table of the following form, where <code>cat</code> and <code>day</code> are the data values from the table we stored at [[Help:List of Adopted Cats]]:
<pre>{
{ CatName = cat, Day = day },
{ CatName = cat, Day = day },
{ CatName = cat, Day = day },
{ CatName = cat, Day = day },
}
</pre>
<syntaxhighlight lang="lua">function h.doQuery()
local query = {
tables = 'CatsAdopted',
fields = {
'Day',
'CatName'
},
limit = 9999
}
return util_cargo.queryAndCast(query)
end</syntaxhighlight>
You can look at the Cargo documentation for how <code>mw.ext.cargo.query</code> works, and {{mod|CargoUtil}} for how <code>util_cargo.queryAndCast</code> works, but this page is about Lua not Cargo, so don't worry about it if you don't want to; this is just a convenient way to get some data.
=== Main Function ===
So let's write our main function first. Generally we want to separate code into 3 parts:
# Get the data (in this case, do the Cargo query)
# Manipulate the data
# Print the data

These sections should be TOTALLY SEPARATE from each other: we don't want to get some data, then format it, then get more data, then format it, etc; nor do we want to construct our output object at the same time as we're manipulating the data. Sometimes there will be case-by-case situations where these steps blur together, but in instances of that happening, it's generally better to ''increase'' the number of distinct steps (maybe we manipulate then format then print, or maybe we get data then calculate totals then do the rest of the processing, etc) rather than decrease them.

So here's a nice clean main function:
<syntaxhighlight lang="lua">function p.main(frame)
local args = mw.getCurrentFrame().args
local data = h.doQuery(args)
local processed = h.processData(data)
return h.makeOutput(processed)
end</syntaxhighlight>

Calling the main function is the only way we should ever interact with this module from elsewhere, so in fact let's go one step further and put this function as the only thing in our export table:

<syntaxhighlight lang="lua">local p = {}
function p.main(frame)
local args = util_args.merge(true)
local data = h.doQuery(args)
local processed = h.processData(data)
return h.makeOutput(processed)
end
return p</syntaxhighlight>

All of the supporting functions we write will be "helper" functions or "private" functions that are only able to be accessed from within this single module, so we'll put them in a separate table called <code>h</code> (h for "helper") that won't be returned at the end.

=== Code Part 1 ===
You can see this at {{mod|CatsAdoptedTable/Part 1}}.
<syntaxhighlight lang="lua">local util_args = require('Module:ArgsUtil')
local util_cargo = require('Module:CargoUtil')

local h = {}

function h.doQuery()
local query = {
tables = 'CatsAdopted',
fields = {
'Day',
'CatName'
},
limit = 9999
}
return util_cargo.queryAndCast(query)
end

function h.processData(data)
end

function h.makeOutput(processed)
end

local p = {}
function p.main(frame)
local args = util_args.merge(true)
local data = h.doQuery()
local processed = h.processData(data)
return h.makeOutput(processed)
end
return p
</syntaxhighlight>
You can run this and it will run! It just won't return anything interesting yet.
<pre>{{#invoke:CatsAdoptedTable/Part 1|main}}</pre>
{{#invoke:CatsAdoptedTable/Part 1|main}}<br>
(The line above this contains the output. Yes, it's empty. But it's not throwing any error!)
=== Designing A Data Structure ===
When you're using MediaWiki parser functions to do stuff, you have arrays that you can manipulate a bit, but it's super awkward to do that much with them. Imagine the pain of working with an array where each element itself is an array! And if you wanted to have keyed data instead of ordered data, well...you can't, so you'd need a separate object for each sub-array, with the keys stored in their own array, and.......yeah no. In Lua, though, it's super easy to set up nice data structures. I'll talk about one I like in particular:

<syntaxhighlight lang="lua">{
'Sunday', 'Monday', 'Tuesday',
Sunday = {},
Monday = {},
Tuesday = {},
etc.
}</syntaxhighlight>

Here we have an ordered list of keys Sunday, Monday, etc, and their data are also in the same table. This is nice because we can iterate over the integer keys with <code>ipairs</code> (<code>pairs</code> would iterate over both integer and non-integer keys). Now we can sort the integer keys using <code>table.sort</code>, and then print stuff in the order we want.

This kind of "ordered dictionary" turns out to be a useful structure to return to frequently, particularly when working with Cargo data that gets grouped together into "containers," like this cat-adoption data.

=== Processing Our Data ===
We need to take our one-cat-per-row table and turn it into a one-day-per-row table, with a sub-table that contains a list of cats.
<syntaxhighlight lang="lua">function h.processData(data)
local processed = {}
for _, row in ipairs(data) do
local day = row.Day
local cat = row.CatName
local dayTable = processed[day] -- dayTable is now an alias for processed[day]
if dayTable then
dayTable[#dayTable+1] = cat -- Lua doesn't have a method like .append, instead you literally just say "make the value at 1 more than the current length this"
else
processed[#processed+1] = day
processed[day] = { cat }
end
end
table.sort(processed, h.sortByWeekOrder)
return processed
end</syntaxhighlight>

So what we do here is to go through each row in our data, extract the day and cat name, and then do one of two things:
* If this is the first cat on a new day, then add that day to our table, and add the cat as the first cat in that day, or
* If not then just add the cat to the existing day-list-of-cats.

After we're done with that we just sort the table.

=== Sorting The Table ===
We just hard code the list of days of the week at the start of the module. Depending on your wiki, you may want to have some "libraries" that just contain ordered lists to order by, like day of the week or month of the year etc. You could also in this case import some time library and use a function for that, but we'll just do it ourselves.

<syntaxhighlight lang="lua">local DAY_ORDER = {
'Sunday',
'Monday',
'Tuesday',
'Wednesday',
'Thursday',
'Friday',
'Saturday'
}

local DAY_ORDER_BETTER = {
Sunday = 1,
Monday = 2,
Tuesday = 3,
Wednesday = 4,
Thursday = 5,
Friday = 6,
Saturday = 7
}

function h.sortByWeekOrder(day1, day2)
return DAY_ORDER_BETTER[day1] < DAY_ORDER_BETTER[day2]
end</syntaxhighlight>

So you might notice I have two different ordering tables here. The second is just easier to work with, and in fact I have a generic library function which takes a table like the first, transforms it to a table like the second, and then sorts your array by it. But for this example I wrote out the steps here instead of using a "built-in" function.

=== Printing Output ===
So at this point in time, we haven't had to say a single thing about how we're presenting the data. We could be making a table, an ordered list, an unordered list, even a calendar - everything up until this point would still be exactly the same. This is really nice because it means if our requirements on data presentation change in the future, we can just change one small block of code instead of the entire module. Yay!

<syntaxhighlight lang="lua">function h.makeOutput(processed)
local tbl = mw.html.create('table')
:addClass('wikitable')
for _, day in ipairs(processed) do
h.printDay(tbl, day, processed[day])
end
return tbl
end</syntaxhighlight>
We aren't doing much so far but that's okay, we'll put more specific details in <code>h.printDay</code>.

The next thing I wrote was actually not <code>h.printDay</code> but rather <code>h.printCat</code>.

<syntaxhighlight lang="lua">function h.printCat(tr, cat)
tr:tag('td'):wikitext(cat)
end</syntaxhighlight>

The reason I wrote this first was that there are two separate cases in <code>h.printDay</code>: 1) the first cat in the day; and 2) subsequent cats in the day. The latter case will require creating a new row, whereas the former just adds a cell to an already-existing row.

<syntaxhighlight lang="lua">function h.printDay(tbl, day, catList)
local tr = tbl:tag('tr')
h.printDayName(tr, day, #catList)
local cat = table.remove(catList,1)
h.printCat(tr, cat)
for _, thiscat in ipairs(catList) do
local trSub = tbl:tag('tr')
h.printCat(trSub, thiscat)
end
end

function h.printDayName(tr, day, rowspan)
tr:tag('td')
:attr('rowspan', rowspan)
:wikitext(day)
end</syntaxhighlight>

So here's the actual job of printing out the entire table. We add a row, print the day cell with the rowspan (which is of course the total number of cats), and then print the first cat. Because we don't need to reuse this table ever, it's convenient to actually remove that cat from the table and then we can just use <code>ipairs</code> over the entire remainder of the table, but it's not necessary to do it that way.

Here's an alternative way to write the same function:

<syntaxhighlight lang="lua">function h.printDay(tbl, day, catList)
for i, cat in ipairs(catList) do
local tr = tbl:tag('tr')
if i == 1 then
h.printDayName(tr, day, #catList)
end
h.printCat(tr, cat)
end
end

function h.printDayName(tr, day, rowspan)
tr:tag('td')
:attr('rowspan', rowspan)
:wikitext(day)
end</syntaxhighlight>

You can see that we still do the same thing of treating index 1 as a special case, and the function to print the day name is exactly the same, but now we make the loop more inclusive. Convince yourself these do exactly the same.
=== Final Result ===
And that's it! Check {{mod|CatsAdoptedTable}} for code. There are some blocks commented out based on what we talked about above.

Here's the final table:

{{#invoke:CatsAdoptedTable|main}}
== Challenge ==
See if you can adjust the output functions to print a list instead of a table. You can feel free to create modules on this wiki, but they might be deleted in cleanups on occasion. Please use your user space for anything other than modules.

Lua example - Revision history

Bryandamon: Created page with " == Intro == This is not a guide to Lua syntax or behavior, and it's also not documentation. What it does instead is talk about a simple example of a common use case in MediaW..."