Module:Separated entries/doc

Usage

Module:Separated entries serves as a template front-end to mw.text.listToText. It takes any number of positional parameters and pieces them together with |separator=. |conjunction= can be optionally defined if a different separator is desired between the last and second last items. The starting positional parameter can be specified using |start=. Leading and trailing whitespace is stripped. To add deliberate leading and trailing whitespace, use the HTML escape code   for a space and 
 for a "newline". Separated entries does not raise any errors by design.

{{#invoke:Separated entries|main|separator=...}}

See also

• {{Enum}}

Overview

There are many mathematical and logical operations that come across naturally as variadic functions. For instance, the summing of numbers or the concatenation of strings or other sequences are operations that can be thought of as applicable to any number of operands (even though formally in these cases the associative property is applied).

Another operation that has been implemented as a variadic function in many languages is output formatting. The C function printf and the Common Lisp function format are two such examples. Both take one argument that specifies the formatting of the output, and any number of arguments that provide the values to be formatted.

Variadic functions can expose type-safety problems in some languages. For instance, C's printf, if used incautiously, can give rise to a class of security holes known as format string attacks. The attack is possible because the language support for variadic functions is not type-safe: it permits the function to attempt to pop more arguments off the stack than were placed there, corrupting the stack and leading to unexpected behavior. As a consequence of this, the CERT Coordination Center considers variadic functions in C to be a high-severity security risk.

In functional languages variadics can be considered complementary to the apply function, which takes a function and a list/sequence/array as arguments, and calls the function with the arguments supplied in that list, thus passing a variable number of arguments to the function. In the functional language Haskell, variadic functions can be implemented by returning a value of a type class T; if instances of T are a final return value r and a function (T t) => x -> t, this allows for any number of additional arguments x.

A related subject in term rewriting research is called hedges, or hedge variables. Unlike variadics, which are functions with arguments, hedges are sequences of arguments themselves. They also can have constraints ('take no more than 4 arguments', for example) to the point where they are not variable-length (such as 'take exactly 4 arguments') - thus calling them variadics can be misleading. However they are referring to the same phenomenon, and sometimes the phrasing is mixed, resulting in names such as variadic variable (synonymous to hedge). Note the double meaning of the word variable and the difference between arguments and variables in functional programming and term rewriting. For example, a term (function) can have three variables, one of them a hedge, thus allowing the term to take three or more arguments (or two or more if the hedge is allowed to be empty).

Open main menu

MediaWiki

Search You have no notifications. Extension:Scribunto/Lua reference manual Extension Discussion Watch History Edit < Extension:Scribunto Other languages: Bahasa Indonesia Deutsch English Esperanto Tiếng Việt Türkçe asturianu català español français italiano magyar polski português do Brasil русский українська עברית فارسی ဖၠုံလိက် မြန်မာဘာသာ 中文 日本語 한국어 This manual documents Lua as it is used in MediaWiki with the Scribunto extension. Some parts are derived from the Lua 5.1 reference manual, which is available under the MIT license.

This page documents the latest version of the Scribunto extension. Some features may not be deployed yet. Introduction

Lua language

Standard libraries

Scribunto libraries Edit

All Scribunto libraries are located in the table mw.

Base functions Edit mw.addWarning Edit mw.addWarning( text )

Adds a warning which is displayed above the preview when previewing an edit. text is parsed as wikitext.

mw.allToString Edit mw.allToString( ... )

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

mw.clone Edit 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.getCurrentFrame Edit mw.getCurrentFrame()

Returns the current frame object, typically the frame object from the most recent #invoke.

mw.incrementExpensiveFunctionCount Edit mw.incrementExpensiveFunctionCount()

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

mw.isSubsting Edit mw.isSubsting()

Returns true if the current #invoke is being substed, false otherwise. See Returning text above for discussion on differences when substing versus not substing.

mw.loadData Edit 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 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 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.

mw.dumpObject Edit mw.dumpObject( object )

Serializes object to a human-readable representation, then returns the resulting string.

mw.log Edit 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.

mw.logObject Edit mw.logObject( object ) mw.logObject( object, prefix )

Calls mw.dumpObject() and appends the resulting string to the log buffer. If prefix is given, it will be added to the log buffer followed by an equals sign before the serialized string is appended (i.e. the logged text will be "prefix = object-string").

Frame object Edit The frame object is the interface to the parameters passed to , and to the parser.

Note that there is no frame library, and there is no global variable named frame. A frame object is typically obtained by being passed as a parameter to the function called by , and can also be obtained from mw.getCurrentFrame().

frame.args Edit 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 ). However, due to how Lua implements table iterators, iterating over arguments will return them in an unspecified order, and there's no way to know the original order as they appear in wikitext.

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: 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 uses a metatable, rather than directly containing the 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 not be expanded, after being passed to Lua, until their values are being requested in Lua. If certain special tags written in XML notation, such as

, <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:callParserFunction
Edit
frame:callParserFunction( name, args )
frame:callParserFunction( name, ... )
frame:callParserFunction{ name = string, args = table }

Note the use of named arguments.
Call a parser function, returning an appropriate string. This is preferable to frame:preprocess, but whenever possible, native Lua functions or Scribunto library functions should be preferred to this interface.

The following calls are approximately equivalent to the indicated wikitext:

-- 
frame:callParserFunction{ name = 'ns', args = 0 }

-- some text
frame:callParserFunction{ name = '#tag', args = { 'nowiki', 'some text' } }
frame:callParserFunction( '#tag', { 'nowiki', 'some text' } )
frame:callParserFunction( '#tag', 'nowiki', 'some text' )
frame:callParserFunction( '#tag:nowiki', 'some text' )

-- 
frame:callParserFunction{ name = '#tag:ref', args = {
    'some text', name = 'foo', group = 'bar'
} }
Note that, as with frame:expandTemplate(), the function name and arguments are not preprocessed before being passed to the parser function.

frame:expandTemplate
Edit
frame:expandTemplate{ title = title, args = table }

Note the use of named arguments.
This is transclusion. The call

frame:expandTemplate{ title = 'template', args = { 'arg1', 'arg2', name = 'arg3' } }
does roughly the same thing from Lua that {{arg1}} 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:extensionTag
Edit
frame:extensionTag( name, content, args )
frame:extensionTag{ name = string, content = string, args = table_or_string }

This is equivalent to a call to frame:callParserFunction() with function name '#tag:' .. name and with content prepended to args.

-- These are equivalent
frame:extensionTag{ name = 'ref', content = 'some text', args = { name = 'foo', group = 'bar' } }
frame:extensionTag( 'ref', 'some text', { name = 'foo', group = 'bar' } )

frame:callParserFunction{ name = '#tag:ref', args = {
    'some text', name = 'foo', group = 'bar'
} }

-- These are equivalent
frame:extensionTag{ name = 'ref', content = 'some text', args = 'some other text' }
frame:callParserFunction{ name = '#tag:ref', args = {
    'some text', 'some other text'
} }
frame:getParent
Edit
frame:getParent()

Called on the frame created by , returns the frame for the page that called . Called on that frame, returns nil.

For instance, if the template 
This is an example of a template. For help with templates, see Help:Template.
 contains the code , and a page transcludes that template with the code 
This is an example of a template. For help with templates, see Help:Template.
, then in Module:ModuleName, calling frame.args[1] and frame.args[2] returns "A" and "B", and calling frame:getParent().args[1] and frame:getParent().args[2] returns "C" and "D", with frame being the first argument in the function call.

frame:getTitle
Edit
frame:getTitle()

Returns the title associated with the frame as a string. For the frame created by , this is the title of the module invoked.

frame:newChild
Edit
frame:newChild{ title = title, args = table }

Note the use of named arguments.
Create a new Frame object that is a child of the current frame, with optional arguments and title.

This is mainly intended for use in the debug console for testing functions that would normally be called by . The number of frames that may be created at any one time is limited.

frame:preprocess
Edit
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 
, <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.

If you are expanding a single parser function, use frame:callParserFunction for the same reasons.

frame:getArgument
Edit
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.

frame:newParserValue
Edit
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
Edit
frame:newTemplateParserValue{ title = title, args = table }

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

frame:argumentPairs
Edit
frame:argumentPairs()

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

Hash library
Edit
mw.hash.hashValue
Edit
mw.hash.hashValue( algo, value )

Hashes a string value with the specified algorithm. Valid algorithms may be fetched using mw.hash.listAlgorithms().

mw.hash.listAlgorithms
Edit
mw.hash.listAlgorithms()

Returns a list of supported hashing algorithms, for use in mw.hash.hashValue().

HTML library
Edit
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 and 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: 
Some text

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

Creates a new mw.html object containing a tagName html element. You can also pass an empty string or nil 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
Edit
html:node( builder )

Appends a child mw.html (builder) node to the current mw.html instance. If a nil parameter is passed, this is a no-op. A (builder) node is a string representation of an html element.

mw.html:wikitext
Edit
html:wikitext( ... )

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

Note that this stops at the first nil item.

mw.html:newline
Edit
html:newline()

Appends a newline to the mw.html object.

mw.html:tag
Edit
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
Edit
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. In the first form, a value of nil causes any attribute with the given name to be unset if it was previously set.

mw.html:getAttr
Edit
html:getAttr( name )

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

mw.html:addClass
Edit
html:addClass( class )

Adds a class name to the node's class attribute. If a nil parameter is passed, this is a no-op.

mw.html:css
Edit
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. In the first form, a value of nil causes any property with the given name to be unset if it was previously set.

mw.html:cssText
Edit
html:cssText( css )

Add some raw css to the node's style attribute. If a nil parameter is passed, this is a no-op.

mw.html:done
Edit
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
Edit
html:allDone()

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

Language library
Edit
Language codes are described at language code. Many of MediaWiki's language codes are similar to IETF language tags, but not all MediaWiki language codes are valid IETF tags or vice versa.

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

mw.language.fetchLanguageName
Edit
mw.language.fetchLanguageName( code, inLanguage )

The full name of the language for the given language code: native name (language autonym) by default, name translated in target language if a value is given for inLanguage.

mw.language.fetchLanguageNames
Edit
mw.language.fetchLanguageNames()
mw.language.fetchLanguageNames( inLanguage )
mw.language.fetchLanguageNames( inLanguage, include )

Fetch the list of languages known to MediaWiki, returning a table mapping language code to language name.

By default the name returned is the language autonym; passing a language code for inLanguage returns all names in that language.

By default, only language names known to MediaWiki are returned; passing 'all' for include will return all available languages (e.g. from Extension:CLDR), while passing 'mwfile' will include only languages having customized messages included with MediaWiki core or enabled extensions. To explicitly select the default, 'mw' may be passed.

mw.language.getContentLanguage
Edit
mw.language.getContentLanguage()
mw.getContentLanguage()

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

mw.language.getFallbacksFor
Edit
 
Fallback chains
mw.language.getFallbacksFor( code )

Returns a list of MediaWiki's fallback language codes for the specified code.

mw.language.isKnownLanguageTag
Edit
mw.language.isKnownLanguageTag( code )

Returns true if a language code is known to MediaWiki.

A language code is "known" if it is a "valid built-in code" (i.e. it returns true for mw.language.isValidBuiltInCode) and returns a non-empty string for mw.language.fetchLanguageName.

mw.language.isSupportedLanguage
Edit
mw.language.isSupportedLanguage( code )

Checks whether any localisation is available for that language code in MediaWiki.

A language code is "supported" if it is a "valid" code (returns true for mw.language.isValidCode), contains no uppercase letters, and has a message file in the currently-running version of MediaWiki.

It is possible for a language code to be "supported" but not "known" (i.e. returning true for mw.language.isKnownLanguageTag). Also note that certain codes are "supported" despite mw.language.isValidBuiltInCode returning false.

mw.language.isValidBuiltInCode
Edit
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.

A language code is a "valid built-in code" if it is a "valid" code (i.e. it returns true for mw.language.isValidCode); consists of only ASCII letters, numbers, and hyphens; and is at least two characters long.

Note that some codes are "supported" (i.e. returning true from mw.language.isSupportedLanguage) even though this function returns false.

mw.language.isValidCode
Edit
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.

A language code is valid if it does not contain certain unsafe characters (colons, single- or double-quotes, slashs, backslashs, angle brackets, ampersands, or ASCII NULs) and is otherwise allowed in a page title.

mw.language.new
Edit
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.

There is a limit on the number of distinct language codes that may be used on a page. Exceeding this limit will result in errors.

mw.language:getCode
Edit
lang:getCode()

Returns the language code for this language object.

mw.language:getFallbackLanguages
Edit
lang:getFallbackLanguages()

Returns a list of MediaWiki's fallback language codes for this language object. Equivalent to mw.language.getFallbacksFor( lang:getCode() ).

mw.language:isRTL
Edit
lang:isRTL()

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

mw.language:lc
Edit
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
Edit
lang:lcfirst( s )

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

mw.language:uc
Edit
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
Edit
lang:ucfirst( s )

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

mw.language:caseFold
Edit
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
Edit
lang:formatNum( n ) 
lang:formatNum( n, options )

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.

The options is a table of options, which can be:

noCommafy: Set true to omit grouping separators and use a dot (.) as the decimal separator. Digit transformation may still occur, which may include transforming the decimal separator.
mw.language:formatDate
Edit
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 wiki's local time rather than in UTC.

The format string and supported values for timestamp are identical to those for the #time parser function from Extension:ParserFunctions. Note however that backslashes may need to be doubled in a Lua string literal, since Lua also uses backslash as an escape character while wikitext does not:

-- This string literal contains a newline, not the two characters "\n", so it is not equivalent to n.
lang:formatDate( '\n' )

-- This is equivalent to n, not \6.
lang:formatDate( '\\n' )

-- This is equivalent to \6, not \\6.
lang:formatDate( '\\\\n' )
mw.language:formatDuration
Edit
lang:formatDuration( seconds ) 
lang:formatDuration( seconds, chosenIntervals )

Breaks a duration in seconds into more human-readable units, e.g. 12345 to 3 hours, 25 minutes and 45 seconds, returning the result as a string.

chosenIntervals, if given, is a table with values naming the interval units to use in the response. These include 'millennia', 'centuries', 'decades', 'years', 'weeks', 'days', 'hours', 'minutes', and 'seconds'.

mw.language:parseFormattedNumber
Edit
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().

mw.language:convertPlural
Edit
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 localization of magic words and translatewiki's FAQ on PLURAL for some details.

mw.language:convertGrammar
Edit
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 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 Special:MyLanguage/Help:Magic words#Localisation and translatewiki:Grammar for some details.

mw.language:gender
Edit
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.

mw.language:getArrow
Edit
lang:getArrow( direction )

Returns a Unicode arrow character corresponding to direction:

forwards: Either "→" or "←" depending on the directionality of the language.
backwards: Either "←" or "→" depending on the directionality of the language.
left: "←"
right: "→"
up: "↑"
down: "↓"
mw.language:getDir
Edit
lang:getDir()

Returns "ltr" or "rtl", depending on the directionality of the language.

mw.language:getDirMark
Edit
lang:getDirMark( opposite )

Returns a string containing either U+200E (the left-to-right mark) or U+200F (the right-to-left mark), depending on the directionality of the language and whether opposite is a true or false value.

mw.language:getDirMarkEntity
Edit
lang:getDirMarkEntity( opposite )

Returns "‎" or "‏", depending on the directionality of the language and whether opposite is a true or false value.

mw.language:getDurationIntervals
Edit
lang:getDurationIntervals( seconds )
lang:getDurationIntervals( seconds, chosenIntervals )

Breaks a duration in seconds into more human-readable units, e.g. 12345 to 3 hours, 25 minutes and 45 seconds, returning the result as a table mapping unit names to numbers.

chosenIntervals, if given, is a table with values naming the interval units to use in the response. These include 'millennia', 'centuries', 'decades', 'years', 'weeks', 'days', 'hours', 'minutes', and 'seconds'.

Those unit keywords are also the keys used in the response table. Only units with a non-zero value are set in the response, unless the response would be empty in which case the smallest unit is returned with a value of 0.

Message library
Edit
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 and msg:name are methods of a message object (see mw.message.new).

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

Creates a new message object for the given message key. The remaining parameters are passed to the new object's params() method.

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

mw.message.newFallbackSequence
Edit
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.newRawMessage
Edit
mw.message.newRawMessage( msg, ... )

Creates a new message object, using the given text directly rather than looking up an internationalized message. The remaining parameters are passed to the new object's params() method.

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

mw.message.rawParam
Edit
mw.message.rawParam( value )

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

mw.message.numParam
Edit
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
Edit
mw.message.getDefaultLanguage()

Returns a Language object for the default language.

mw.message:params
Edit
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
Edit
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
Edit
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
Edit
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
Edit
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
Edit
msg:plain()

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

mw.message:exists
Edit
msg:exists()

Returns a boolean indicating whether the message key exists.

mw.message:isBlank
Edit
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
Edit
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 "-".

Site library
Edit
mw.site.currentVersion
Edit
A string holding the current version of MediaWiki.

mw.site.scriptPath
Edit
The value of $wgScriptPath.

mw.site.server
Edit
The value of $wgServer.

mw.site.siteName
Edit
The value of $wgSitename.

mw.site.stylePath
Edit
The value of $wgStylePath.

mw.site.namespaces
Edit
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: 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
Edit
Table holding just the content namespaces, indexed by number. See mw.site.namespaces for details.

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

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

mw.site.stats
Edit
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.
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
Edit
mw.site.stats.pagesInCategory( category, which )

This function is expensive
Gets statistics about the category. If which has the special value "*", the result is 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 ("all", "subcats", "files", "pages"), the result is a number with the corresponding value.

Each new category queried will increment the expensive function count.

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

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

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

Returns the number of users in the given group.

mw.site.interwikiMap
Edit
mw.site.interwikiMap( filter )

Returns a table holding data about available interwiki prefixes. If filter is the string "local", then only data for local interwiki prefixes is returned. If filter is the string "!local", then only data for non-local prefixes is returned. If no filter is specified, data for all prefixes is returned. A "local" prefix in this context is one that is for the same project. For example, on the English Wikipedia, other-language Wikipedias are considered local, while Wiktionary and such are not.

Keys in the table returned by this function are interwiki prefixes, and the values are subtables with the following properties:

prefix - the interwiki prefix.
url - the URL that the interwiki points to. The page name is represented by the parameter $1.
isProtocolRelative - a boolean showing whether the URL is protocol-relative.
isLocal - whether the URL is for a site in the current project.
isCurrentWiki - whether the URL is for the current wiki.
isTranscludable - whether pages using this interwiki prefix are transcludable. This requires scary transclusion, which is disabled on Wikimedia wikis.
isExtraLanguageLink - whether the interwiki is listed in $wgExtraInterlanguageLinkPrefixes.
displayText - for links listed in $wgExtraInterlanguageLinkPrefixes, this is the display text shown for the interlanguage link. Nil if not specified.
tooltip - for links listed in $wgExtraInterlanguageLinkPrefixes, this is the tooltip text shown when users hover over the interlanguage link. Nil if not specified.
Text library
Edit
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
Edit
mw.text.decode( s ) 
mw.text.decode( s, decodeNamedEntities )

Replaces HTML entities in the string with the corresponding characters.

If boolean decodeNamedEntities is omitted or false, the only named entities recognized are '<', '>', '&', '"', and ' '. Otherwise, the list of HTML5 named entities to recognize is loaded from PHP's get_html_translation_table function.

mw.text.encode
Edit
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.jsonDecode
Edit
mw.text.jsonDecode( s ) 
mw.text.jsonDecode( s, flags )

Decodes a JSON string. flags is 0 or a combination (use +) of the flags mw.text.JSON_PRESERVE_KEYS and mw.text.JSON_TRY_FIXING.

Normally JSON's zero-based arrays are renumbered to Lua one-based sequence tables; to prevent this, pass mw.text.JSON_PRESERVE_KEYS.

To relax certain requirements in JSON, such as no terminal comma in arrays or objects, pass mw.text.JSON_TRY_FIXING. This is not recommended.

Limitations:

Decoded JSON arrays may not be Lua sequences if the array contains null values.
JSON objects will drop keys having null values.
It is not possible to directly tell whether the input was a JSON array or a JSON object with sequential integer keys.
A JSON object having sequential integer keys beginning with 1 will decode to the same table structure as a JSON array with the same values, despite these not being at all equivalent, unless mw.text.JSON_PRESERVE_KEYS is used.
mw.text.jsonEncode
Edit
mw.text.jsonEncode( value ) 
mw.text.jsonEncode( value, flags )

Encode a JSON string. Errors are raised if the passed value cannot be encoded in JSON. flags is 0 or a combination (use +) of the flags mw.text.JSON_PRESERVE_KEYS and mw.text.JSON_PRETTY.

Normally Lua one-based sequence tables are encoded as JSON zero-based arrays; when mw.text.JSON_PRESERVE_KEYS is set in flags, zero-based sequence tables are encoded as JSON arrays.

Limitations:

Empty tables are always encoded as empty arrays ([]), not empty objects ({}).
Sequence tables cannot be encoded as JSON objects without adding a "dummy" element.
To produce objects or arrays with nil values, a tricky implementation of the __pairs metamethod is required.
A Lua table having sequential integer keys beginning with 0 will encode as a JSON array, the same as a Lua table having integer keys beginning with 1, unless mw.text.JSON_PRESERVE_KEYS is used.
When both a number and the string representation of that number are used as keys in the same table, behavior is unspecified.
mw.text.killMarkers
Edit
mw.text.killMarkers( s )

Removes all MediaWiki strip markers from a string.

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

Joins 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 conjunction 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
Edit
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
Edit
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
Edit
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
Edit
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
Edit
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
Edit
mw.text.truncate( text, length )
mw.text.truncate( text, length, ellipsis )
mw.text.truncate( text, length, ellipsis, adjustLength )

Truncates text to the specified length in code points, 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.unstripNoWiki
Edit
mw.text.unstripNoWiki( s )

Replaces MediaWiki <nowiki> strip markers with the corresponding text. Other types of strip markers are not changed.

mw.text.unstrip
Edit
mw.text.unstrip( s )

Equivalent to mw.text.killMarkers( mw.text.unstripNoWiki( s ) ).

This no longer reveals the HTML behind special page transclusion, <ref> tags, and so on as it did in earlier versions of Scribunto.

Title library
Edit
mw.title.equals
Edit
mw.title.equals( a, b )

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

mw.title.compare
Edit
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.

This compares titles by interwiki prefix (if any) as strings, then by namespace number, then by the unprefixed title text as a string. These string comparisons use Lua's standard < operator.

mw.title.getCurrentTitle
Edit
mw.title.getCurrentTitle()

Returns the title object for the current page.

mw.title.new
Edit
mw.title.new( text, namespace ) 
mw.title.new( id )

This function is expensive when called with an ID
Creates a new title object.

If a number id is given, an object is created for the title with that page_id. The title referenced will be counted as linked from the current page. If the page_id does not exist, returns nil. The expensive function count will be incremented if the title object created is not for a title that has already been loaded.

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
Edit
mw.title.makeTitle( namespace, title, fragment, interwiki )

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.

Note that, unlike mw.title.new(), this method will always apply the specified namespace. For example, mw.title.makeTitle( 'Template', 'Module:Foo' ) will create an object for the page Template:Module:Foo, while mw.title.new( 'Module:Foo', 'Template' ) will create an object for the page Module:Foo.

Title objects
Edit
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. This may be expensive.
interwiki: The interwiki prefix, or the empty string if none.
namespace: The namespace number.
fragment: The fragment (aka section/anchor linking), 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. Interwiki is not returned if equal to the current.
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 file.exists for Media-namespace titles. For File-namespace titles this checks the existence of the file description page, not the file itself. This may be expensive.
file, fileExists: See #File metadata below.
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. This may be expensive.
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.
contentModel: The content model for this title, as a string. This may be expensive.
basePageTitle: The same as mw.title.makeTitle( title.namespace, title.baseText ).
rootPageTitle: The same as mw.title.makeTitle( title.namespace, title.rootText ).
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.
subjectPageTitle: The same as mw.title.makeTitle( mw.site.namespaces[title.namespace].subject.id, title.text ).
redirectTarget: Returns a title object of the target of the redirect page if the page is a redirect and the page exists, returns false otherwise.
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.
cascadingProtection: The cascading protections applicable to the page. This is a table with keys "restrictions" (itself a table with keys like protectionLevels has) and "sources" (an array listing titles where the protections cascade from). If no protections cascade to the page, "restrictions" and "sources" will be empty. This is expensive.
subPageTitle( text ): The same as mw.title.makeTitle( title.namespace, title.text .. '/' .. text ).
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.

Since people find the fact surprising, note that accessing any expensive field on a title object records a "link" to the page (as shown on Special:WhatLinksHere, for example). Using the title object's getContent() method or accessing the redirectTarget field records it as a "transclusion", and accessing the title object's file or fileExists fields records it as a "file link".


File metadata
Edit
Title objects representing a page in the File or Media namespace will have a property called file. This is expensive. This is a table, structured as follows:

exists: Whether the file exists. It will be recorded as an image usage. The fileExists property on a Title object exists for backwards compatibility reasons and is an alias for this property. If this is false, all other file properties will be nil.
width: The width of the file. If the file contains multiple pages, this is the width of the first page.
height: The height of the file. If the file contains multiple pages, this is the height of the first page.
pages: If the file format supports multiple pages, this is a table containing tables for each page of the file; otherwise, it is nil. The # operator can be used to get the number of pages in the file. Each individual page table contains a width and height property.
size: The size of the file in bytes.
mimeType: The MIME type of the file.
length: The length (duration) of the media file in seconds. Zero for media types which do not support length.
Expensive properties
Edit
The properties id, isRedirect, exists, and contentModel require fetching data about the title from the database. For this reason, the expensive function count is incremented the first time one of them is accessed for a page other than the current page. Subsequent accesses of any of these properties for that page will not increment the expensive function count again.

Other properties marked as expensive will always increment the expensive function count the first time they are accessed for a page other than the current page.

URI library
Edit
mw.uri.encode
Edit
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 reversible, as both spaces and underscores are encoded as '_'.

mw.uri.decode
Edit
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
Edit
mw.uri.anchorEncode( s )

Encodes a string for use in a MediaWiki URI fragment.

mw.uri.buildQueryString
Edit
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
Edit
mw.uri.parseQueryString( s, i, j )

Decodes the query string s 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.

The optional numerical arguments i and j can be used to specify a substring of s to be parsed, rather than the entire string. i is the position of the first character of the substring, and defaults to 1. j is the position of the last character of the substring, and defaults to the length of the string. Both i and j can be negative, as in string.sub.

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

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

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

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

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

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

mw.uri.new
Edit
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
Edit
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
Edit
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
Edit
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
Edit
uri:clone()

Makes a copy of the URI object.

mw.uri:extend
Edit
uri:extend( parameters )

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

Ustring library
Edit
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
Edit
The maximum allowed length of a pattern, in bytes.

mw.ustring.maxStringLength
Edit
The maximum allowed length of a string, in bytes.

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

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

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

Returns 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
Edit
mw.ustring.char( ... )

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

local value = mw.ustring.char( 0x41f, 0x440, 0x438, 0x432, 0x435, 0x442, 0x21 ) -- value is now 'Привет!'
mw.ustring.codepoint
Edit
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
Edit
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
Edit
mw.ustring.format( format, ... )

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

mw.ustring.gcodepoint
Edit
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
Edit
mw.ustring.gmatch( s, pattern )

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

mw.ustring.gsub
Edit
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
Edit
mw.ustring.isutf8( s )

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

mw.ustring.len
Edit
mw.ustring.len( s )

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

See string.len() for a similar function that uses byte length rather than codepoints.

mw.ustring.lower
Edit
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
Edit
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
Edit
mw.ustring.rep( s, n )

Identical to string.rep().

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

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

mw.ustring.toNFC
Edit
mw.ustring.toNFC( s )

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

mw.ustring.toNFD
Edit
mw.ustring.toNFD( s )

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

mw.ustring.upper
Edit
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
Edit
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 "Number, decimal digit".
%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.
Like in String library patterns, %A, %C, %D, %L, %P, %S, %U and %W here represent the complementary set ("all characters without given General Category").

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.

Loadable libraries

Extension libraries

Differences from standard Lua

Writing Scribunto libraries

See also

License

Last edited 13 days ago by Shirayuki
MediaWiki
Content is available under CC BY-SA 3.0 unless otherwise noted.
Privacy policy Terms of Use Desktop