Scribunto

Scribunto is the extension on Wikia that allows users to use the Lua language to dynamically add content to pages. It is to replace parser functions as the primary source for adding dynamic templates, although parser functions will still work for smaller templates.

Note: the words method and function are used interchangeably here.

Calling a Module[]

All Lua code must be held in a page in the module namespace. These modules can them be invoked using

{{#invoke:moduleName|functionName|args1|args2|name = named arg|anotherName = named arg 2}}

Multiple related functions can be invoked from the same module.

Note: Lua modules are one of the last things to be parsed on a page, after parser functions, magic words, template expansion, transformations such as signatures and the pipe trick, and the expanding of other extensions such as DPL. This means that, while you can use the results of these changes, you may not invoke them through a Lua module. Links do work though, both wikilinks and external links, when invoked using a module.

Creating a Module & Functions[]

All modules must be held in the module namespace. Their basic structure is as follows:

local p = {}

-- Functions etc.

return p

The output of the module is whatever is held in p by the end of execution. It can be useful to only return strings to p to give the most predictable output, but it will take any data type and convert it into a string for you to add to a page.

You can use as many functions as you like in a module, and you can use both invokable functions and helper functions. Functions which can be invoked through the invoke template must be in the form:

function p.functionName( frame )
    --stuff
    return variableName
end

The frame which is used as an argument here takes the arguments from the invocation. Helper methods on the other hand cannot be invoked directly, but can be used within other functions. Their syntax is as follows:

function functionName ( variable1, variable2, variable3 etc)
    -stuff
    return variableName
end

As in other programming languages, the variable names used in the function declaration (the first line above) are the words used to refer to those bits of information within the function.

Notice how there is no "p." before the function name of a helper method, but there is for the invokable method? That is what defines a method as one or the other. The helper method may take as many arguments as needed, or indeed none at all.

The helper method can be called using the following syntax:

functionName( arg1, arg2, arg3 )

where the number of args matches the number of arguments in the function declaration. It will return the value specified by the variable in the return statement in the function.

Getting the Arguments from the Invocation[]

As mentioned previously, the main, callable methods within the module take in a single argument called "frame". This contains all the variables used in the invoke statement, arranged in what is known as a table. Unnamed arguments are assigned numbers starting from 1 (note that this is different from many programming languages which start at 0) while names arguments are named via their names.

To access a single numbered argument, use

frame.args[1]

Increment the number to access later numbered arguments.

To access a single named argument, use

frame.args.name

where name is the name of the argument as used in the invocation.

If you want to put all arguments in a real table so you can access them later by name (good for when there are a large number of arguments or an unknown quantity of arguments), use the following:

local t = {}
    for name, value in frame:argumentPairs() do
        t[name] = value
    end

You can then access these arguments using

t[name]

If you want to get information out of a template, use the following:

    -- Call a template
    s = s .. frame:expandTemplate{ title = 'tpl', args = {foo = arg1} }

    -- Return expanded text
    return s

You can also just invoke a template as an argument in your invocation, since templates are parsed before Lua.

Making and Accessing Variables[]

Variables in Lua are declared by writing a word followed by an equals sign. Variables may be either local or global, but it is generally best to declare them as local (for reasons which have yet to be explained clearly). You do that as follows:

local variableName = "Something"

This means that the word variableName is now assigned the value "Something". Variable names may be any word containing only letters, numbers, and underscores, however they may not begin with a number. There are also certain words which cannot be used as variables as they are reserved for other things, such as 'local', 'end', 'if', 'for', etc. As a general rule, if it changes colour as you're typing it into the module editor, you can't use it as a variable name.

Variables can hold values of any data type. Assign the value nil to a variable to delete it.

Variables can then be accessed using their name. For example:

local greeting = "Hello"
local place = "World"
local sentence = greeting .. " " .. place

return sentence

This will return the string "Hello World". More info on what those dots are down the page.

All variables have a scope, or the place in which they live. A variable may only be used within the block in which it is declared. That means that if a variable is declared within a function, it may only be used within that function (although it can be sent to another function by using it as an argument while calling that other function, or by returning it from the current function to the function calling that function). If it is declared within a for loop, it may only be used within that for loop. If it is declared within the body of an if statement, it may only be used within the body of that if statement. For example:

local p = {}

function p.main(frame)
    local cool = {
        "bowties"
        "fezzes"
    }
    if cool[1] == "bowties" do
        local approved = cool[1] .. " are cool.  Eleven approves."
    else
        local approved = cool[1] .. " are not cool.  Eleven does not approve."
    end
    return approved
end

return p

This example would return the value nil as the variable approved is local to the blocks within the if statement. However, the table cool, a local variable, is able to be accessed within the if statement as the if statement is itself within the function block. This is known as the scope of the variable. In general:

Data Types[]

Standard data types[]

Lua uses strings, which are enclosed in either 'single' or "double" quotes. There are used for things such as words or sentences. It is the plain text which we can read.

Lua also uses numbers. These are all double precision floating point numbers, which for those who haven't programmed before means that they all use decimals. Integers however are always expressed exactly, despite being of data type float, but numbers with a decimal part, or numbers outside the range -9007199254740992 to 9007199254740992, always have the usual nasty habit of including rounding errors.

A number (or other data type) can be turned into a string using toString( value ). A string (or other data type) can be turned into a number using toNumber( value ) and will return nil if it cannot do so.

Booleans also exist in Lua, and are either true or false. Note the lack of quotes. If converted to a string, will be "true" and "false" respectively. False and nil are considered false by Lua, and all other values, including 0, are considered true. Note that "and" and "or" are used weirdly in Boolean expressions in Lua compared to their meaning in languages such as python or Java.

Nil is the data type for a missing data type. It evaluates to false if used in a Boolean expression and can be used to remove data from a variable, including from tables (more on that below)

Tables[]

Tables are a very flexible data type in Lua. They can be used in a way analogous to arrays/list, or they can be used in a way analogous to python dictionaries. They are declared as follows:

local tableName= {}

You can add items to the table either at the time of declaration or later. For example:

local tableName= {
    "first!"
    "foo"= "bar"
    "Damn, I was so close"
    "eggs" = "bacon"
    "Wikia" = "awesome"
    true = false
    35 = "thirty five"
    tonumber = "Yep, even functions can be used as table keys"
    }

tableName[more] = "Another"
tableName[25] = "5 * 5"
tableName["25"] = "Strings and numbers are different things"
tableName[tableName] = "Yup, even a table can be a key, even to itself. Inception anyone?"

These variables may then be called using the following syntax:

Syntax	Output	Notes
tableName[1]	"first!"	Unnamed variables can be called in numeric order, ignoring named parameters.
tableName[2]	"Damn, I was so close"	The above demonstrated
tableName[3]	nil	Undeclared variables have the value nil. You can also assign the value nil to a variable to delete it from a table
tableName["foo"]	"bar"	Named variables are called in a similar manner to unnamed ones
tableName['eggs']	'bacon'	It makes no difference if you use single or double quotes
tableName.Wikia	"awesome"	If the name is a string, the value can also be called using "dot notation"
tableName[true]	false	Yep, any data type may be used as a key in a table, and any data type may be the value of a table, including booleans.
tableName[25]	"5 * 5"	Numbers can be used as names and can be far outside the range used for the unnamed parameters
tableName["25"]	"Strings and numbers are different things"	Watch out! Strings and numbers are interpreted as different things.

Operators[]

Console[]

No comment as I have no idea how it's supposed to work.