Lua reference manual/Scribunto libraries

All Scribunto libraries are located in the table `mw`.

Calls `tostring()` on all arguments, then concatenates them with tabs as separators.

### mw.clearLogBuffer

`mw.clearLogBuffer()`

Removes all data logged with `mw.log()`.

### mw.clone

`mw.clone( value )`

Creates a deep copy of a value. All tables (and their metatables) are reconstructed from scratch. Functions are still shared, however.

### mw.executeFunction

`mw.executeFunction( func )`

This creates a new copy of the frame object, calls the function with that as its parameter, then calls `tostring()` on all results and concatenates them (no separator) and returns the resulting string.

**Note this will not work correctly from the debug console, as there is no frame object to copy.**

### mw.executeModule

`mw.executeModule( func )`

Executes the function in a sandboxed environment; the function cannot affect anything in the current environment, with the exception of side effects of calling any existing closures.

The name "executeModule" is because this is the function used when a module is loaded from the Module: namespace.

**Note this will not work correctly from the debug console, as there is no frame object to copy.**

### mw.getCurrentFrame

`mw.getCurrentFrame()`

**Note this will not work correctly from the debug console, as there is no frame object to copy.**

Returns the current frame object.

### mw.getLogBuffer

`mw.getLogBuffer()`

Returns the data logged by `mw.log()`, as a string.

### mw.incrementExpensiveFunctionCount

`mw.incrementExpensiveFunctionCount()`

Adds one to the "expensive parser function" count, and throws an exception if it exceeds the limit (see $wgExpensiveParserFunctionLimit).

### mw.loadData

`mw.loadData( module )`

Sometimes a module needs large tables of data; for example, a general-purpose module to convert units of measure might need a large table of recognized units and their conversion factors. And sometimes these modules will be used many times in one page. Parsing the large data table for every `{{#invoke:}}` can use a significant amount of time. To avoid this issue, `mw.loadData()` is provided.

`mw.loadData` works like `require()`, with the following differences:

* The loaded module is evaluated only once per page, rather than once per `{{#invoke:}}` call.
* The loaded module is not recorded in `package.loaded`.
* The value returned from the loaded module must be a table. Other data types are not supported.
* The returned table (and all subtables) may contain only booleans, numbers, strings, and other tables. Other data types, particularly functions, are not allowed.
* The returned table (and all subtables) may not have a metatable.
* All table keys must be booleans, numbers, or strings.
* The table actually returned by `mw.loadData()` has metamethods that provide read-only access to the table returned by the module. Since it does not contain the data directly, `pairs()` and `ipairs()` will work but other methods, including `#value`, `next()`, and the functions in the Table library, will not work correctly.

The hypothetical unit-conversion module mentioned above might store its code in "Module:Convert" and its data in "Module:Convert/data", and "Module:Convert" would use `local data = mw.loadData( 'Module:Convert/data' )` to efficiently load the data.

#### Global Modules

Modules containing tables can also be retrieved from a global repository ( specifically dev.wikia.com). This uses a syntax such as:

```
local data = mw.loadData( 'Dev:Convert/data' )

```

The code above will load a table from a module stored in dev.wikia.com/wiki/Module:Convert/data (if it exists).
**Note**: This is **case sensitive.**

### mw.log

`mw.log( ... )`

Passes the arguments to `mw.allToString()`, then appends the resulting string to the log buffer.

In the debug console, the function `print()` is an alias for this function.

## Frame object

The frame object is the interface to the parameters passed to `{{#invoke:}}`, and to the parser.

### frame.args

A table for accessing the arguments passed to the frame. For example, if a module is called from wikitext with

```
```

then `frame.args[1]` will return "arg1", `frame.args[2]` will return "arg2", and `frame.args['name']` (or `frame.args.name`) will return "arg3". It is also possible to iterate over arguments using `pairs( frame.args )` or `ipairs( frame.args )`.

Note that values in this table are always strings; `tonumber()` may be used to convert them to numbers, if necessary. Keys, however, are numbers even if explicitly supplied in the invocation: `{{#invoke:module|function|1|2=2}}` gives string values "1" and "2" indexed by numeric keys 1 and 2.

As in MediaWiki template invocations, named arguments will have leading and trailing whitespace removed from both the name and the value before they are passed to Lua, whereas unnamed arguments will not have whitespace stripped.

For performance reasons, frame.args is a metatable, not a real table of arguments. Argument values are requested from MediaWiki on demand. This means that most other table methods will not work correctly, including `#frame.args`, `next( frame.args )`, and the functions in the Table library.

If preprocessor syntax such as template invocations and triple-brace arguments are included within an argument to #invoke, they will be expanded before being passed to Lua. If certain special tags written in XML notation, such as `<pre>`, `<nowiki>`, `<gallery>` and `<ref>`, are included as arguments to #invoke, then these tags will be converted to "strip markers" — special strings which begin with a delete character (ASCII 127), to be replaced with HTML after they are returned from #invoke.

### frame:getParent

`frame:getParent()`

**Example:**

* Module:Hello

```
local p = {}

function p.hello( frame )
	return "Hello, " .. frame:getParent().args[1] .. "!"
end

return p

```

* Template:Hello

```
{{#invoke:Hello|hello}}

```

* Article

```
{{Hello|FANDOM}}

```

* This will output "Hello, FANDOM!".

### frame:expandTemplate

`frame:expandTemplate{ title=template, args=table }`

Note the use of named args syntactic sugar; see Function calls for details.

This is transclusion. The call

```
frame:expandTemplate{ title = 'template', args = { 'arg1', 'arg2', name = 'arg3' } }

```

does roughly the same thing from Lua that `{{template|arg1|arg2|name=arg3}}` does in wikitext. As in transclusion, if the passed title does not contain a namespace prefix it will be assumed to be in the Template: namespace.

Note that the title and arguments are not preprocessed before being passed into the template:

```
-- This is roughly equivalent to wikitext like
-- {{template|{{!}}}}
frame:expandTemplate{ title = 'template', args = { '|' } }

-- This is roughly equivalent to wikitext like
-- {{template|{{((}}!{{))}}}}
frame:expandTemplate{ title = 'template', args = { '{{!}}' } }

```

### frame:preprocess

`frame:preprocess( string )`

`frame:preprocess{ text = string }`

This expands wikitext in the context of the frame, i.e. templates, parser functions, and parameters such as `{{{1}}}` are expanded. Certain special tags written in XML-style notation, such as `<pre>`, `<nowiki>`, `<gallery>` and `<ref>`, will be replaced with "strip markers" — special strings which begin with a delete character (ASCII 127), to be replaced with HTML after they are returned from `{{#invoke}}`.

If you are expanding a single template, use `frame:expandTemplate` instead of trying to construct a wikitext string to pass to this method. It's faster and less prone to error if the arguments contain pipe characters or other wikimarkup.

```
local p = {}

function p.hello( frame )
	-- This will preprocess the wikitext and expand the template {{foo}}
	return frame:preprocess( "'''Bold''' and ''italics'' is {{Foo}}" )
end

return p

```

### frame:getArgument

`frame:getArgument( arg )`

`frame:getArgument{ name = arg }`

Gets an object for the specified argument, or nil if the argument is not provided.

The returned object has one method, `object:expand()`, that returns the expanded wikitext for the argument.

```
local p = {}

function p.hello( frame )
	local varOne = frame:getArgument( 1 )
	local varTwo = frame.args[2]
	local varThree = frame:getArgument( 'foo' )
	return varOne:expand() .. varTwo .. varThree:expand()
end

return p

```

### frame:newParserValue

`frame:newParserValue( text )`

`frame:newParserValue{ text = text }`

Returns an object with one method, `object:expand()`, that returns the result of `frame:preprocess( text )`.

### frame:newTemplateParserValue

`frame:newTemplateParserValue{ title title, args table }`

Returns an object with one method, `object:expand()`, that returns the result of `frame:expandTemplate` called with the given arguments.

### frame:argumentPairs

`frame:argumentPairs()`

Same as `pairs( frame.args )`. Included for backwards compatibility.

### frame:getTitle

Returns the title associated with the frame as a string.

### Note

As of July 2015, the whole frame library is unavailable in the debug console in FANDOM's version of Scribunto. Unlike MediaWiki's version (1.25+) of `mw.getCurrentFrame()` ,FANDOM's Scribunto will return "nil" when used in the debug console.

## Language library

Language codes are described at Language code.

Functions documented as `mw.language.name` are available on the global `mw.language` table; functions documented as `mw.language:name` are methods of a language object (see `mw.language.new`).

**Difference from MW core:** `mw.language.isSupportedLanguage` and `mw.language.isKnownLanguageTag` removed, and `mw.language.fetchLanguageName` has been modified.

### mw.language.fetchLanguageName

`mw.language.fetchLanguageName( code )`

The full name of the native language name (language autonym).

**Difference from MW core:** The second parameter, `inLanguage`, which returns the language name translated in target language if a value is given for it, is not supported due to missing methods in MW 1.19.

### mw.language.getContentLanguage

`mw.language.getContentLanguage()`

`mw.getContentLanguage()`

Returns a new language object for the wiki's default content language.

### mw.language.isValidBuiltInCode

`mw.language.isValidBuiltInCode( code )`

Returns true if a language code is of a valid form for the purposes of internal customisation of MediaWiki.

The code may not actually correspond to any known language.

### mw.language.isValidCode

`mw.language.isValidCode( code )`

Returns true if a language code string is of a valid form, whether or not it exists. This includes codes which are used solely for customisation via the MediaWiki namespace.

The code may not actually correspond to any known language.

### mw.language.new

`mw.language.new( code )`

`mw.getLanguage( code )`

Creates a new language object. Language objects do not have any publicly accessible properties, but they do have several methods, which are documented below.

The methods below must all use the language object (e.g. lang).

```
local lang = mw.language.new("en")
local ucText = lang:uc("En Taro Adun executor")
mw.log (ucText)

```

### mw.language:getCode

`lang:getCode()`

Returns the language code for this language object.

### mw.language:isRTL

`lang:isRTL()`

Returns true if the language is written right-to-left, false if it is written left-to-right.

### mw.language:lc

`lang:lc( s )`

Converts the string to lowercase, honoring any special rules for the given language.

When the Ustring library is loaded, the `mw.ustring.lower()` function is implemented as a call to `mw.language.getContentLanguage():lc( s )`.

### mw.language:lcfirst

`lang:lcfirst( s )`

Converts the first character of the string to lowercase, as with `lang:lc()`.

### mw.language:uc

`lang:uc( s )`

Converts the string to uppercase, honoring any special rules for the given language.

When the Ustring library is loaded, the `mw.ustring.upper()` function is implemented as a call to `mw.language.getContentLanguage():uc( s )`.

### mw.language:ucfirst

`lang:ucfirst( s )`

Converts the first character of the string to uppercase, as with `lang:uc()`.

### mw.language:caseFold

`lang:caseFold( s )`

Converts the string to a representation appropriate for case-insensitive comparison. Note that the result may not make any sense when displayed.

### mw.language:formatNum

`lang:formatNum( n , nocommafy)`

Formats a number with grouping and decimal separators appropriate for the given language. Given 123456.78, this may produce "123,456.78", "123.456,78", or even something like "١٢٣٬٤٥٦٫٧٨" depending on the language and wiki configuration.

With the second parameter, one can prevent the output from containing commas, as shown below:

```
 local result = lang:formatNum(123123123, {noCommafy=true})

```

```
output: 123123123
```

### mw.language:formatDate

`lang:formatDate( format, timestamp, local )`

Formats a date according to the given format string. If `timestamp` is omitted, the default is the current time. The value for `local` must be a boolean or nil; if true, the time is formatted in the server's local time rather than in UTC.

The **timestamp** is the actual date. It accepts dates with either a backslash or dash e.g. "2015/10/20" or "2015-10-20".

The format string and supported values for `timestamp` are identical to those for the #time parser function from Extension:ParserFunctions, as shown below:

```
--This outputs the current date with spaces between the month,day and year
lang:formatDate( 'y m d' )

--This outputs the inputted date using the specified format
lang:formatDate( 'y m d', "2015-02-01" )

```

Note that backslashes may need to be doubled in the Lua string where they wouldn't in wikitext:

```
-- This outputs a newline, where {{#time:\n}} would output a literal "n"
lang:formatDate( '\n' )

-- This outputs a literal "n", where {{#time:\\n}} would output a backslash
-- followed by the month number.
lang:formatDate( '\\n' )

-- This outputs a backslash followed by the month number, where {{#time:\\\\n}}
-- would output two backslashes followed by the month number.
lang:formatDate( '\\\\n' )

```

### mw.language:parseFormattedNumber

`lang:parseFormattedNumber( s )`

This takes a number as formatted by `lang:formatNum()` and returns the actual number. In other words, this is basically a language-aware version of `tonumber()`.

This library allows one to do arithmetic in multiple supported languages (simultaneously), and is better than the `{{#expr}}` parser function:

```
local n1 = "١"
local n2 = "٣"
local lang = mw.language.new("ar")
local num1 = lang:parseFormattedNumber(n1)
local num2 = lang:parseFormattedNumber(n2)
local tot = lang:formatNum(num1 + num2)
mw.log(tot)

```

### mw.language:convertPlural

`lang:convertPlural( n, ... )`

`lang:convertPlural( n, forms )`

`lang:plural( n, ... )`

`lang:plural( n, forms )`

This chooses the appropriate grammatical form from `forms` (which must be a sequence table) or `...` based on the number `n`. For example, in English you might use `n .. ' ' .. lang:plural( n, 'sock', 'socks' )` or `n .. ' ' .. lang:plural( n, { 'sock', 'socks' } )` to generate grammatically-correct text whether there is only 1 sock or 200 socks.

The necessary values for the sequence are language-dependent, see mw:Help:Magic words#Language-dependent word conversions for some details.

### mw.language:convertGrammar

`lang:convertGrammar( word, case )`

`lang:grammar( case, word )`

*Note the different parameter order between the two aliases. `convertGrammar` matches the order of the method of the same name on MediaWiki's Language object, while `grammar` matches the order of the parser function of the same name, documented at mw:Help:Magic words#Localisation.*
This chooses the appropriate inflected form of `word` for the given inflection code `case`.

The possible values for `word` and `case` are language-dependent, see mw:Help:Magic words#Language-dependent word conversions for some details.

### mw.language:gender

`lang:gender( what, masculine, feminine, neutral )`

`lang:gender( what, { masculine, feminine, neutral } )`

Chooses the string corresponding to the gender of `what`, which may be "male", "female", or a registered user name.

## Site library

### mw.site.currentVersion

A string holding the current version of MediaWiki.

### mw.site.namespaces

Table holding data for all namespaces, indexed by number.

The data available is:

* **id**: Namespace number.
* **name**: Local namespace name.
* **canonicalName**: Canonical namespace name.
* **displayName**: Set on namespace 0, the name to be used for display (since the name is often the empty string).
* **hasSubpages**: Whether subpages are enabled for the namespace.
* **hasGenderDistinction**: Whether the namespace has different aliases for different genders.
* **isCapitalized**: Whether the first letter of pages in the namespace is capitalized.
* **isContent**: Whether this is a content namespace.
* **isIncludable**: Whether pages in the namespace can be transcluded.
* **isMovable**: Whether pages in the namespace can be moved.
* **isSubject**: Whether this is a subject namespace.
* **isTalk**: Whether this is a talk namespace.
* **~~defaultContentModel~~**(*As of October 2015, this unavailable in FANDOM's scribunto*): The default content model for the namespace, as a string.
* **aliases**: List of aliases for the namespace.
* **subject**: Reference to the corresponding subject namespace's data.
* **talk**: Reference to the corresponding talk namespace's data.
* **associated**: Reference to the associated namespace's data.

A metatable is also set that allows for looking up namespaces by name (localized or canonical). For example, both `mw.site.namespaces[4]` and `mw.site.namespaces.Project` will return information about the Project namespace.

### mw.site.contentNamespaces

Table holding just the content namespaces, indexed by number. See `mw.site.namespaces` for details.

### mw.site.subjectNamespaces

Table holding just the subject namespaces, indexed by number. See `mw.site.namespaces` for details.

### mw.site.talkNamespaces

Table holding just the talk namespaces, indexed by number. See `mw.site.namespaces` for details.

### mw.site.stats

Table holding site statistics. Available statistics are:

* **pages**: Number of pages in the wiki.
* **articles**: Number of articles in the wiki.
* **files**: Number of files in the wiki.
* **edits**: Number of edits in the wiki.
* **views**: Number of views in the wiki. Not available if $wgDisableCounters is set.
* **users**: Number of users in the wiki.
* **activeUsers**: Number of active users in the wiki.
* **admins**: Number of users in group 'sysop' in the wiki.

### mw.site.stats.pagesInCategory

`mw.site.stats.pagesInCategory( category, which )`

This function is expensive
Gets statistics about the category. If `which` is unspecified, nil, or "\*", returns a table with the following properties:

* **all**: Total pages, files, and subcategories.
* **subcats**: Number of subcategories.
* **files**: Number of files.
* **pages**: Number of pages.

If `which` is one of the above keys, just the corresponding value is returned instead.

Each new category queried will increment the expensive function count.

### mw.site.stats.pagesInNamespace

`mw.site.stats.pagesInNamespace( ns )`

Returns the number of pages in the given namespace (specify by number).

### mw.site.stats.usersInGroup

`mw.site.stats.usersInGroup( group )`

Returns the number of users in the given group.

## Uri library

### mw.uri.encode

`mw.uri.encode( s, enctype )`

Percent-encodes the string. The default type, "QUERY", encodes spaces using '+' for use in query strings; "PATH" encodes spaces as %20; and "WIKI" encodes spaces as '\_'.

Note that the "WIKI" format is not entirely reversable, as both spaces and underscores are encoded as '\_'.

### mw.uri.decode

`mw.uri.decode( s, enctype )`

Percent-decodes the string. The default type, "QUERY", decodes '+' to space; "PATH" does not perform any extra decoding; and "WIKI" decodes '\_' to space.

### mw.uri.anchorEncode

`mw.uri.anchorEncode( s )`

Encodes a string for use in a MediaWiki URI fragment.

### mw.uri.buildQueryString

`mw.uri.buildQueryString( table )`

Encodes a table as a URI query string. Keys should be strings; values may be strings or numbers, sequence tables, or boolean false.

### mw.uri.parseQueryString

`mw.uri.parseQueryString( s )`

Decodes a query string to a table. Keys in the string without values will have a value of false; keys repeated multiple times will have sequence tables as values; and others will have strings as values.

### mw.uri.canonicalUrl

`mw.uri.canonicalUrl( page, query )`

Returns a URI object for the canonical url for a page, with optional query string/table.

### mw.uri.fullUrl

`mw.uri.fullUrl( page, query )`

Returns a URI object for the full url for a page, with optional query string/table.

### mw.uri.localUrl

`mw.uri.localUrl( page, query )`

Returns a URI object for the local url for a page, with optional query string/table.

### mw.uri.new

`mw.uri.new( s )`

Constructs a new URI object for the passed string or table. See the description of URI objects for the possible fields for the table.

### mw.uri.validate

`mw.uri.validate( table )`

Validates the passed table (or URI object). Returns a boolean indicating whether the table was valid, and on failure a string explaining what problems were found.

### URI object

The URI object has the following fields, some or all of which may be nil:

* **protocol**: String protocol/scheme
* **user**: String user
* **password**: String password
* **host**: String host name
* **port**: Integer port
* **path**: String path
* **query**: A table, as from `mw.uri.parseQueryString`
* **fragment**: String fragment.

The following properties are also available:

* **userInfo**: String user and password
* **hostPort**: String host and port
* **authority**: String user, password, host, and port
* **queryString**: String version of the query table
* **relativePath**: String path, query string, and fragment

`tostring()` will give the URI string.

Methods of the URI object are:

#### mw.uri:parse

`uri:parse( s )`

Parses a string into the current URI object. Any fields specified in the string will be replaced in the current object; fields not specified will keep their old values.

#### mw.uri:clone

`uri:clone()`

Makes a copy of the URI object.

#### mw.uri:extend

`uri:extend( parameters )`

Merges the parameters table into the object's query table.

## Ustring library

The ustring library is intended to be a direct reimplementation of the standard String library, except that the methods operate on characters in UTF-8 encoded strings rather than bytes.

Most functions will raise an error if the string is not valid UTF-8; exceptions are noted.

### mw.ustring.maxPatternLength

The maximum allowed lengh of a pattern, in bytes.

### mw.ustring.maxStringLength

The maximum allowed lengh of a string, in bytes.

### mw.ustring.byte

`mw.ustring.byte( s, i, j )`

Returns individual bytes; identical to `string.byte()`.

### mw.ustring.byteoffset

`mw.ustring.byteoffset( s, l, i )`

Returns individual the byte offset of a character in the string. The default for both `l` and `i` is 1. `i` may be negative, in which case it counts from the end of the string.

The character at `l` = 1 is the first character starting at or after byte `i`; the character at `l` = 0 is the first character starting at or before byte `i`. Note this may be the same character. Greater or lesser values of `l` are calculated relative to these.

### mw.ustring.char

`mw.ustring.char( ... )`

Much like `string.char()`, except that the integers are Unicode codepoints rather than byte values.

### mw.ustring.codepoint

`mw.ustring.codepoint( s, i, j )`

Much like `string.byte()`, except that the return values are codepoints and the offsets are characters rather than bytes.

### mw.ustring.find

`mw.ustring.find( s, pattern, init, plain )`

Much like `string.find()`, except that the pattern is extended as described in Ustring patterns and the `init` offset is in characters rather than bytes.

### mw.ustring.format

`mw.ustring.format( format, ... )`

Identical to `string.format()`. Widths and precisions for strings are expressed in bytes, not codepoints.

### mw.ustring.gcodepoint

`mw.ustring.gcodepoint( s, i, j )`

Returns three values for iterating over the codepoints in the string. `i` defaults to 1, and `j` to -1. This is intended for use in the iterator form of `for`:

```
for codepoint in mw.ustring.gcodepoint( s ) do
    -- block
end

```

### mw.ustring.gmatch

`mw.ustring.gmatch( s, pattern )`

Much like `string.gmatch()`, except that the pattern is extended as described in Ustring patterns.

### mw.ustring.gsub

`mw.ustring.gsub( s, pattern, repl, n )`

Much like `string.gsub()`, except that the pattern is extended as described in Ustring patterns.

### mw.ustring.isutf8

`mw.ustring.isutf8( s )`

Returns true if the string is valid UTF-8, false if not.

### mw.ustring.len

`mw.ustring.len( s )`

Returns the length of the string in codepoints, or nil if the string is not valid UTF-8.

### mw.ustring.lower

`mw.ustring.lower( s )`

Much like `string.lower()`, except that all characters with lowercase to uppercase definitions in Unicode are converted.

If the Language library is also loaded, this will instead call `lc()` on the default language object.

### mw.ustring.match

`mw.ustring.match( s, pattern, init )`

Much like `string.match()`, except that the pattern is extended as described in Ustring patterns and the `init` offset is in characters rather than bytes.

### mw.ustring.rep

`mw.ustring.rep( s, n )`

Identical to `string.rep()`.

### mw.ustring.sub

`mw.ustring.sub( s, i, j )`

Much like `string.sub()`, except that the offsets are characters rather than bytes.

### mw.ustring.toNFC

`mw.ustring.toNFC( s )`

Converts the string to Normalization Form C. Returns nil if the string is not valid UTF-8.

### mw.ustring.toNFD

`mw.ustring.toNFD( s )`

Converts the string to Normalization Form D. Returns nil if the string is not valid UTF-8.

### mw.ustring.upper

`mw.ustring.upper( s )`

Much like `string.upper()`, except that all characters with uppercase to lowercase definitions in Unicode are converted.

If the Language library is also loaded, this will instead call `uc()` on the default language object.

### Ustring patterns

Patterns in the ustring functions use the same syntax as the String library patterns. The major difference is that the character classes are redefined in terms of Unicode character properties:

* **`%a`**: represents all characters with General Category "Letter".
* **`%c`**: represents all characters with General Category "Control".
* **`%d`**: represents all characters with General Category "Decimal Number".
* **`%l`**: represents all characters with General Category "Lowercase Letter".
* **`%p`**: represents all characters with General Category "Punctuation".
* **`%s`**: represents all characters with General Category "Separator", plus tab, linefeed, carriage return, vertical tab, and form feed.
* **`%u`**: represents all characters with General Category "Uppercase Letter".
* **`%w`**: represents all characters with General Category "Letter" or "Decimal Number".
* **`%x`**: adds fullwidth character versions of the hex digits.

In all cases, characters are interpreted as Unicode characters instead of bytes, so ranges such as `[０-９]`, patterns such as `%b«»`, and quantifiers applied to multibyte characters will work correctly. Empty captures will capture the position in code points rather than bytes.

## HTML library

`mw.html` is a fluent interface for building complex HTML from Lua. A mw.html object can be created using `mw.html.create`.

Functions documented as `mw.html.name` are available on the global `mw.html` table; functions documented as `mw.html:name` are methods of an mw.html object (see `mw.html.create`).

A basic example could look like this:

```
local div = mw.html.create( 'div' )
div
	:attr( 'id', 'testdiv' )
	:css( 'width', '100%' )
	:wikitext( 'Some text' )
	:tag( 'hr' )
return tostring( div )
-- Output: <div id="testdiv" style="width:100%;">Some text<hr /></div>

```

### mw.html.create

`mw.html.create( tagName, args )`

Creates a new mw.html object containing a `tagName` html element. You can also pass an empty string as `tagName` in order to create an empty mw.html object.

`args` can be a table with the following keys:

* `args.selfClosing`: Force the current tag to be self-closing, even if mw.html doesn't recognize it as self-closing
* `args.parent`: Parent of the current mw.html instance (intended for internal usage)

### mw.html:node

`html:node( builder )`

Appends a child mw.html (`builder`) node to the current mw.html instance.

### mw.html:wikitext

`html:wikitext( ... )`

Appends an undetermined number of wikitext strings to the mw.html object.

### mw.html:newline

`html:newline()`

Appends a newline to the mw.html object.

### mw.html:tag

`html:tag( tagName, args )`

Appends a new child node with the given `tagName` to the builder, and returns a mw.html instance representing that new node. The `args` parameter is identical to that of `mw.html.create`

### mw.html:attr

`html:attr( name, value )`

`html:attr( table )`

Set an HTML attribute with the given `name` and `value` on the node. Alternatively a table holding name->value pairs of attributes to set can be passed.

### mw.html:getAttr

`html:getAttr( name )`

Get the value of a html attribute previously set using `html:attr()` with the given `name`.

### mw.html:addClass

`html:addClass( class )`

Adds a class name to the node's class attribute.

### mw.html:css

`html:css( name, value )`

`html:css( table )`

Set a CSS property with the given `name` and `value` on the node. Alternatively a table holding name->value pairs of properties to set can be passed.

### mw.html:cssText

`html:cssText( css )`

Add some raw `css` to the node's style attribute.

### mw.html:done

`html:done()`

Returns the parent node under which the current node was created. Like jQuery.end, this is a convenience function to allow the construction of several child nodes to be chained together into a single statement.

### mw.html:allDone

`html:allDone()`

Like `html:done()`, but traverses all the way to the root node of the tree and returns it.

## Text library

The text library provides some common text processing functions missing from the String library and the Ustring library. These functions are safe for use with UTF-8 strings.

### mw.text.decode

`mw.text.decode( s )`

`mw.text.decode( s, decodeNamedEntities )`

Replaces HTML entities in the string with the corresponding characters.

If `decodeNamedEntities` is omitted or false, the only named entities recognized are '&lt;', '&gt;', '&amp;', '&quot;', and '&nbsp;'. Otherwise, the list of HTML5 named entities to recognize is loaded from PHP's `get_html_translation_table` function.

### mw.text.encode

`mw.text.encode( s )`

`mw.text.encode( s, charset )`

Replaces characters in a string with HTML entities. Characters '<', '>', '&', '"', and the non-breaking space are replaced with the appropriate named entities; all others are replaced with numeric entities.

If `charset` is supplied, it should be a string as appropriate to go inside brackets in a Ustring pattern, i.e. the "set" in `[set]`. The default charset is `'<>&"\' '` (the space at the end is the non-breaking space, U+00A0).

### mw.text.listToText

`mw.text.listToText( list )`

`mw.text.listToText( list, separator, conjunction )`

Join a list, prose-style. In other words, it's like `table.concat()` but with a different separator before the final item.

The default separator is taken from MediaWiki:comma-separator in the wiki's content language, and the default conjuction is MediaWiki:and concatenated with MediaWiki:word-separator.

Examples, using the default values for the messages:

```
-- Returns the empty string
mw.text.listToText( {} )

-- Returns "1"
mw.text.listToText( { 1 } )

-- Returns "1 and 2"
mw.text.listToText( { 1, 2 } )

-- Returns "1, 2, 3, 4 and 5"
mw.text.listToText( { 1, 2, 3, 4, 5 } )

-- Returns "1; 2; 3; 4 or 5"
mw.text.listToText( { 1, 2, 3, 4, 5 }, '; ', ' or ' )

```

### mw.text.nowiki

`mw.text.nowiki( s )`

Replaces various characters in the string with HTML entities to prevent their interpretation as wikitext. This includes:

* The following characters: '"', '&', "'", '<', '=', '>', '[', ']', '{', '|', '}'
* The following characters at the start of the string or immediately after a newline: '#', '\*', ':', ';', space, tab ('\t')
* Blank lines will have one of the associated newline or carriage return characters escaped
* "----" at the start of the string or immediately after a newline will have the first '-' escaped
* "\_\_" will have one underscore escaped
* "://" will have the colon escaped
* A whitespace character following "ISBN", "RFC", or "PMID" will be escaped

### mw.text.split

`mw.text.split( s, pattern, plain )`

Splits the string into substrings at boundaries matching the Ustring pattern `pattern`. If `plain` is specified and true, `pattern` will be interpreted as a literal string rather than as a Lua pattern (just as with the parameter of the same name for `mw.ustring.find()`). Returns a table containing the substrings.

For example, `mw.text.split( 'a b\tc\nd', '%s' )` would return a table `{ 'a', 'b', 'c', 'd' }`.

If `pattern` matches the empty string, `s` will be split into individual characters.

### mw.text.gsplit

`mw.text.gsplit( s, pattern, plain )`

Returns an iterator function that will iterate over the substrings that would be returned by the equivalent call to `mw.text.split()`.

### mw.text.tag

`mw.text.tag( name, attrs, content )`

`mw.text.tag{ name string, attrs = table, content string|false }`

*Note the use of named arguments.*
Generates an HTML-style tag for `name`.

If `attrs` is given, it must be a table with string keys. String and number values are used as the value of the attribute; boolean true results in the key being output as an HTML5 valueless parameter; boolean false skips the key entirely; and anything else is an error.

If `content` is not given (or is nil), only the opening tag is returned. If `content` is boolean false, a self-closed tag is returned. Otherwise it must be a string or number, in which case that content is enclosed in the constructed opening and closing tag. Note the content is not automatically HTML-encoded; use `mw.text.encode()` if needed.

For properly returning extension tags such as `<ref>`, use `frame:extensionTag()` instead.

### mw.text.trim

`mw.text.trim( s )`

`mw.text.trim( s, charset )`

Remove whitespace or other characters from the beginning and end of a string.

If `charset` is supplied, it should be a string as appropriate to go inside brackets in a Ustring pattern, i.e. the "set" in `[set]`. The default charset is ASCII whitespace, `"%t%r%n%f "`.

### mw.text.truncate

`mw.text.truncate( text, length )`

`mw.text.truncate( text, length, ellipsis )`

`mw.text.truncate( text, length, ellipsis, adjustLength )`

Truncates `text` to the specified length, adding `ellipsis` if truncation was performed. If length is positive, the end of the string will be truncated; if negative, the beginning will be removed. If `adjustLength` is given and true, the resulting string including ellipsis will not be longer than the specified length.

The default value for `ellipsis` is taken from MediaWiki:ellipsis in the wiki's content language.

Examples, using the default "..." ellipsis:

```
-- Returns "foobarbaz"
mw.text.truncate( "foobarbaz", 9 )

-- Returns "fooba..."
mw.text.truncate( "foobarbaz", 5 )

-- Returns "...arbaz"
mw.text.truncate( "foobarbaz", -5 )

-- Returns "foo..."
mw.text.truncate( "foobarbaz", 6, nil, true )

-- Returns "foobarbaz", because that's shorter than "foobarba..."
mw.text.truncate( "foobarbaz", 8 )

```

### mw.text.unstrip

`mw.text.unstrip( s )`

Replaces MediaWiki strip markers with the corresponding text. Note that the content of the strip marker do not necessarily correspond to the input, nor do they necessarily match the final page output.

**Note that strip markers are typically used for a reason, and replacing them in Lua rather than allowing the parser to do so at the appropriate time may break things.**

## Title library

### mw.title.equals

`mw.title.equals( a, b )`

Test for whether two titles are equal. Note that fragments are ignored in the comparison.

### mw.title.compare

`mw.title.compare( a, b )`

Returns -1, 0, or 1 to indicate whether the title `a` is less than, equal to, or greater than title `b`

### mw.title.getCurrentTitle

`mw.title.getCurrentTitle()`

Returns the title object for the current page.

### mw.title.new

`mw.title.new( text, namespace )`

`mw.title.new( id )`

This function is expensive
Creates a new title object. The expensive function count will be incremented if the title object created is not for the current page and is not for a title that has already been loaded. The title referenced will be counted as linked from the current page (see ).

If a number `id` is given, an object is created for the title with that page\_id. If the page\_id does not exist, returns nil.

If a string `text` is given instead, an object is created for that title (even if the page does not exist). If the text string does not specify a namespace, `namespace` (which may be any key found in `mw.site.namespaces`) will be used. If the text is not a valid title, nil is returned.

### mw.title.makeTitle

`mw.title.makeTitle( namespace, title, fragment, interwiki )`

This function is expensive
Creates a title object with title `title` in namespace `namespace`, optionally with the specified `fragment` and `interwiki` prefix. `namespace` may be any key found in `mw.site.namespaces`. If the resulting title is not valid, returns nil. This function is expensive under the same conditions as `mw.title.new()`, and records a link just as does `mw.title.new()`.

Note that `mw.title.new( 'Module:Foo', 'Template' )` will create an object for the page Module:Foo, while `mw.title.makeTitle( 'Template', 'Module:Foo' )` will create an object for the page Template:Module:Foo.

Note some of the properties below are methods and other are fields or variables in the title object, as shown in the example:

```
local titleobject = mw.title.new( 'Yoda' )
--Doesn't use a colon
local existspage = titleobject.exists
local pagecontent

if existspage then
-- Method uses a colon
  pagecontent = titleobject:getContent()
end

return pagecontent

```

### Title objects

A title object has a number of properties and methods. Most of the properties are read-only.

Note that fields ending with `text` return titles as string values whereas the fields ending with `title` return title objects.

* **id**: The page\_id. 0 if the page does not exist.
* **interwiki**: The interwiki prefix, or the empty string if none.
* **namespace**: The namespace number.
* **fragment**: The fragment, or the empty string. May be assigned.
* **nsText**: The text of the namespace for the page.
* **subjectNsText**: The text of the subject namespace for the page.
* **text**: The title of the page, without the namespace or interwiki prefixes.
* **prefixedText**: The title of the page, with the namespace and interwiki prefixes.
* **fullText**: The title of the page, with the namespace and interwiki prefixes and the fragment.
* **rootText**: If this is a subpage, the title of the root page without prefixes. Otherwise, the same as `title.text`.
* **baseText**: If this is a subpage, the title of the page it is a subpage of without prefixes. Otherwise, the same as `title.text`.
* **subpageText**: If this is a subpage, just the subpage name. Otherwise, the same as `title.text`.
* **canTalk**: Whether the page for this title could have a talk page.
* **exists**: Whether the page exists. Alias for **fileExists** for Media-namespace titles.
* **fileExists**: Whether the file exists. For File- and Media-namespace titles, this is expensive. It will also be recorded as an image usage for File- and Media-namespace titles.
* **isContentPage**: Whether this title is in a content namespace.
* **isExternal**: Whether this title has an interwiki prefix.
* **isLocal**: Whether this title is in this project. For example, on the English Wikipedia, any other Wikipedia is considered "local" while Wiktionary and such are not.
* **isRedirect**: Whether this is the title for a page that is a redirect.
* **isSpecialPage**: Whether this is the title for a possible special page (i.e. a page in the Special: namespace).
* **isSubpage**: Whether this title is a subpage of some other title.
* **isTalkPage**: Whether this is a title for a talk page.
* **isSubpageOf( title2 )**: Whether this title is a subpage of the given title.
* **inNamespace( ns )**: Whether this title is in the given namespace. Namespaces may be specified by anything that is a key found in `mw.site.namespaces`.
* **inNamespaces( ... )**: Whether this title is in any of the given namespaces. Namespaces may be specified by anything that is a key found in `mw.site.namespaces`.
* **hasSubjectNamespace( ns )**: Whether this title's subject namespace is in the given namespace. Namespaces may be specified by anything that is a key found in `mw.site.namespaces`.
* **basePageTitle**: The same as `mw.title.makeTitle( title.namespace, title.baseText )`. This is expensive.
* **rootPageTitle**: The same as `mw.title.makeTitle( title.namespace, title.rootText )`. This is expensive.
* **talkPageTitle**: The same as `mw.title.makeTitle( mw.site.namespaces[title.namespace].talk.id, title.text )`, or nil if this title cannot have a talk page. This is expensive.
* **subjectPageTitle**: The same as `mw.title.makeTitle( mw.site.namespaces[title.namespace].subject.id, title.text )`. This is expensive.
* **protectionLevels**: The page's protection levels. This is a table with keys corresponding to each action (e.g., "edit" and "move"). The table values are arrays, the first item of which is a string containing the protection level. If the page is unprotected, either the table values or the array items will be nil. This is expensive.
* **subPageTitle( text )**: The same as `mw.title.makeTitle( title.namespace, title.text .. '/' .. text )`. This is expensive.
* **partialUrl()**: Returns `title.text` encoded as it would be in a URL.
* **fullUrl( query, proto )**: Returns the full URL (with optional query table/string) for this title. `proto` may be specified to control the scheme of the resulting url: "http", "https", "relative" (the default), or "canonical".
* **localUrl( query )**: Returns the local URL (with optional query table/string) for this title.
* **canonicalUrl( query )**: Returns the canonical URL (with optional query table/string) for this title.
* **getContent()**: Returns the (unparsed) content of the page, or nil if there is no page. The page will be recorded as a transclusion.

Title objects may be compared using Relational operators. `tostring( title )` will return `title.prefixedText`.

## Message library

This library is an interface to the localisation messages and the MediaWiki: namespace.

Functions documented as `mw.message.name` are available on the global `mw.message` table; functions documented as `mw.message:name` are methods of a message object (see `mw.message.new`).

### mw.message.new

`mw.message.new( key, ... )`

Creates a new message object for the given message `key`.

The message object has no properties, but has several methods documented below.

### mw.message.newFallbackSequence

`mw.message.newFallbackSequence( ... )`

Creates a new message object for the given messages (the first one that exists will be used).

The message object has no properties, but has several methods documented below.

### mw.message.rawParam

`mw.message.rawParam( value )`

Wraps the value so that it will not be parsed as wikitext by `msg:parse()`.

### mw.message.numParam

`mw.message.numParam( value )`

Wraps the value so that it will automatically be formatted as by `lang:formatNum()`. Note this does not depend on the Language library actually being available.

### mw.message.getDefaultLanguage

`mw.message.getDefaultLanguage()`

Returns a Language object for the default language.

### mw.message:params

`msg:params( ... )`

`msg:params( params )`

Add parameters to the message, which may be passed as individual arguments or as a sequence table. Parameters must be numbers, strings, or the special values returned by `mw.message.numParam()` or `mw.message.rawParam()`. If a sequence table is used, parameters must be directly present in the table; references using the `__index` metamethod will not work.

Returns the `msg` object, to allow for call chaining.

### mw.message:rawParams

`msg:rawParams( ... )`

`msg:rawParams( params )`

Like `:params()`, but has the effect of passing all the parameters through `mw.message.rawParam()` first.

Returns the `msg` object, to allow for call chaining.

### mw.message:numParams

`msg:numParams( ... )`

`msg:numParams( params )`

Like `:params()`, but has the effect of passing all the parameters through `mw.message.numParam()` first.

Returns the `msg` object, to allow for call chaining.

### mw.message:inLanguage

`msg:inLanguage( lang )`

Specifies the language to use when processing the message. `lang` may be a string or a table with a `getCode()` method (i.e. a Language object).

The default language is the one returned by `mw.message.getDefaultLanguage()`.

Returns the `msg` object, to allow for call chaining.

### mw.message:useDatabase

`msg:useDatabase( bool )`

Specifies whether to look up messages in the MediaWiki: namespace (i.e. look in the database), or just use the default messages distributed with MediaWiki.

The default is true.

Returns the `msg` object, to allow for call chaining.

### mw.message:plain

`msg:plain()`

Substitutes the parameters and returns the message wikitext as-is. Template calls and parser functions are intact.

### mw.message:exists

`msg:exists()`

Returns a boolean indicating whether the message key exists.

### mw.message:isBlank

`msg:isBlank()`

Returns a boolean indicating whether the message key has content. Returns true if the message key does not exist or the message is the empty string.

### mw.message:isDisabled

`msg:isDisabled()`

Returns a boolean indicating whether the message key is disabled. Returns true if the message key does not exist or if the message is the empty string or the string "-".

## See also

* Lua reference manual/Standard libraries

## References

1. ↑ Brad Jorsch. Make mw.getCurrentFrame() work in console, add frame:newChild() (Wikimedia Gerrit Merge). Retrieved 2015 October. https://github.com/wikimedia/mediawiki-extensions-Scribunto/commit/b6ea64f1325433c574b39f7f360f7f5f4ec0fdde, https://gerrit.wikimedia.org/r/#/c/49801/ , http://www.gossamer-threads.com/lists/wiki/mediawiki-cvs/335745
2. ↑ https://phabricator.wikimedia.org/T12857