Extension:Scribunto/Victor's API proposal
Warning: This page is just a proposal, there is no guarantee that any of the functions listed here will ever be implemented. If any of them are implemented, there is no guarantee that they will do the same thing or that the order of the arguments will be the same. For documentation of functions which actually exist, see the Lua reference manual. |
MediaWiki Lua API
editThe aim of Scribunto Lua in-script API is to provide the scripts an interface to certain features of MediaWiki software which are written in PHP and most of which are not feasible to implement in Lua. The first-priority target is to provide access to all those interfaces which were previously exposed to parser as magic words and parser functions.
Here we try to keep to the table arguments convention whenever it is feasible. func{a, b, c}
means that you should invoke function as func{a = "whatever", b = "argument", c = "trolling"}
.
Whenever a property is defined, it is either read-only ([ro]
), write-only ([wo]
) or read-write ([rw]
).
Provided interfaces
editAll interfaces are the part mw package.
- mw.lang — internationalization-related functions.
- mw.page — interface to provide information about the current page (title, etc) and do direct manipulations with it.
- mw.query — functions which require database queries in order to work. The total amount of calls to those functions is limited; the limit is shared with parser's expensive function count.
- mw.site — functions which provide the information about the site.
- mw.time — functions which provide interfaces for time manipulations.
- mw.Title — provides an object which represents title
- mw.text — functions which are used to handle the wikitext.
- mw.url — functions which provide access to URL-related functions.
Data structures
editThe time is passed in a following structure, which extends over Lua's standard date/time structure:
- Standard members:
year
month
day
hour
min
sec
wday
— week day (Monday is 1)yday
— day of the year
- Extensions:
monthname
— localized month nametimezone
— the timezone in which timestamp is supplied
The revision information is passed in the following structure:
id
author
timestamp
(always UTC)
The titles have a special object, which is described in an individual section below.
Detailed interface description
editmw.lang
editmw.lang.contentLanguage [ro]
— the language code of the content language, i.e. the main language of the wiki.mw.lang.UILanguage [ro]
— the language code of the UI language, i.e. language in which user has his interface now.mw.lang.languageName{code[, language]}
— returns the language name of language withcode
. Iflanguage
is not specified, return in the language itself.mw.lang.message(messageName, ...)
— formats the message and returns it.mw.lang.plural(number, form1, form2...)
— similar to{{plural:number|form1|form2|...|}}
.mw.lang.formatNumber(number)
— formats the number according to the language conventions.mw.lang.gender(username, ...)
— picks the right version of the string depending on the user gender.mw.lang.specialPageName(page)
— returns the localized name of a given special page.
mw.page
editmw.page.title [ro]
— returns the title structuremw.page.currentRevision [ro]
— returns the revision structuremw.page.defaultSort [wo]
— similar to{{DEFAULTSORT}}
mw.page.displayTitle [wo]
— similar to{{DISPLAYTITLE}}
mw.query
editThe query module has different configurable limit-related variables:
blockSize
— defaults to 100listLimit
— defaults to 500
In case when the limit is exceeded, the error is thrown.
mw.query.blockSize [ro]
— theblockSize
.mw.query.listLimit [ro]
— thelistLimit
.mw.query.expensiveFunctionLimit [ro]
— the limit of allowed calls to expensive functions.mw.query.expensiveFunctionRemaining [ro]
— how much more calls to expensive functions are allowedmw.query.pagesExist(pages)
— checks whether thepages
exist and returns the result in form of page->existence table. Note that page name in the resulting table is normalized. This is counted as one expensive query, but for everyblockSize
of pages this count is increased by 1.mw.query.pageInformation{pages, props}
— returns the information aboutpages
. The information to return is specified inprops
array. Currently available aresize
andis_redirect
. This is counted as one expensive query, but for everyblockSize
of pages this count is increased by 1.mw.query.prefixIndex{prefix, startWith, limit}
— list the pages beginning withprefix
, starting withstartWith
. Returns at mostlimit
pages, orlistLimit
, whatever is smaller.- there will be more at the later stage
mw.site
editmw.site.siteName [ro]
— returns the name of the site.mw.site.version [ro]
— returns MediaWiki software version.mw.site.namespaces [ro]
— returns localized namespace ID to namespace name map.mw.site.canonicalNamespaces [ro]
— returns non-localized namespace ID to namespace name map.mw.site.interwikiTable [ro]
— returns the interwiki table in format { interwiki prefix -> { url, api, wikiID, isLocal, isTrans } }mw.site.numberOfPages [ro]
mw.site.numberOfArticles [ro]
mw.site.numberOfFiles [ro]
mw.site.numberOfEdits [ro]
mw.site.numberOfViews [ro]
mw.site.numberOfUsers [ro]
mw.site.numberOfAdmins [ro]
mw.site.numberOfActiveUsers [ro]
mw.Title
editUnlike other packages, this is an object class. It may be returned by any API method or be constructed by user using one of the following constructors:
mw.Title(text)
— creates a title from its text form; returns nil if the title is invalid.mw.Title(data)
— creates a title from its data. Currently the only accepted fields aretext
,namespaceID
andnamespaceName
, allowing to create a title object from namespace + text data. If the data is insufficient, conflicting or invalid, nil is returned.
The title object has the following fields:
namespace
— namespace IDnamespaceName
— namespace name (localized)name
— the name of the page, without namespacefullName
— full name of the page, with namespacefullText
— the full normalized title, including interwiki prefixinterwiki
— the interwiki prefix, if is therefragment
— the destination fragment
It also has the following methods:
titleObj:localURI([query])
— returns a local (relative) URL to the title, optionally withquery
titleObj:fullURI([query])
— same as above, but uses full URL instead of local one (includes server name).titleObj:canonicalURI([query])
— same as above, but has a protocol prefix.
mw.time
editThis interface provides access to MediaWiki's advanced date and time handling, parsing and internationalization interfaces.
mw.time.UTC [ro]
— returns the current time in UTC.mw.time.local [ro]
— returns the current time in the wiki timezone.mw.time.unixTimestamp [ro]
— returns the exact Unix timestamp in seconds, but with highest floating-point precision possible.mw.time.toLocal(timestamp)
— translates the timestamp to the wiki timezone.mw.time.toUTC(timestamp)
— translates the timestamp to UTC.mw.time.parse(text)
— parses thetext
and returns a timestamp object, assuming by default that timezone istimezone
(UTC if not specified).mw.time.format{timestamp, format}
— formats thedate
according to theformat
specification.
mw.text
editmw.text.escape(text)
— escapes wikitext.mw.text.tag{name, contents, params}
— creates a tag marker for tag namedname
. Similar to{{#tag}}
.
mw.uri
editmw.uri.encode(text)
— escapes a URL stringmw.uri.encodeAnchor(text)
— escapes a URL anchor stringmw.uri.server [ro]
— similar to{{SERVER}}
.mw.uri.serverName [ro]
— similar to{{SERVERNAME}}
.mw.uri.scriptPath [ro]
— similar to{{SCRIPTPATH}}
.
ustring API
editThe ustring
module provides UTF-8 strings manipulations. It aims to be similar to built-in string
module in Lua; however, it extends it in some features and it does not provide pattern matching (a separate regular expression library will be provided for that later). Also, it does not provide an OOP interface to strings[1]. There are the following functions in the ustring library:
ustring.find(s, needle[, init])
— does a substring search, and returns the start and the end point of the match (or nil, if not found). Important differences:- The needle argument is not a pattern.
- In case of using empty string as a needle, raises an error.
- The first two returns are start- and endpoint as a string offset in characters; the third and fourth arguments are raw byte offsets.
ustring.len(s)
— returns the string length in code points.ustring.lower(s)
— converts the string to all-lowercaseustring.pairs(s[, start, end])
— allows to iterate over all codepoints in the string, or in a substring (fromstart
toend
).ustring.split(str, separator[, limit])
— splits thestr
into at mostlimit
substrings (default limit is infinity)ustring.sub(s, i[, j])
— returns the substring; the syntax is similar tostring.sub
.ustring.trim(s)
— trims all the whitespace at the beginning and at the end of the string.ustring.upper(s)
— converts the string to all-uppercaseustring.upperFirst(s)
— converts the first character of the string into uppercase
All functions index the offsets in string by codepoints, not bytes. If invalid UTF-8 is supplied, an error is raised.
For all ustring
functions which accept target string as a first argument, a similar function with "u" prefix is provided in usual string metatable. For example, ustring.trim(str)
may also be called as str:utrim()
.
Footnotes
edit- ↑ Such an interface was considered, but it is impossible to adequately implement it in pure Lua.