Extension:Scribunto/Lua リファレンス マニュアル

このマニュアルでは、MediaWiki の Scribunto 拡張機能で使用される Lua について解説しています。 このマニュアルの一部は、MIT license のもとで利用できる Lua 5.1 reference manual に基づいています。

はじめに

さあ、はじめましょう

Scribunto が有効化された MediaWiki で、例えば "Module:Bananas" のような、タイトルが "Module:" で始まるページを作成します。 その新しいページに、以下のテキストをコピーします。

local p = {} --p はパッケージの p です。この変数名は何でも構いません。

function p.hello( frame )
    return "Hello, world!"
end

return p

これを保存した後、サンドボックスページなどの（モジュールでない）他のページで次のように記述します。

{{#invoke:Bananas|hello}}

ただし "Bananas" を自分の Module の名前に置き換えてください。このコードは Module からエクスポートされた "hello" 関数を呼び出します。{{#invoke:Bananas|hello}}は、関数が返したテキスト（この場合は"Hello, world!"）に置き換えられます。

Lua のコードをウィキマークアップのテンプレートの形式で呼び出すのは良いことです。 というのは、ウィキペディアのソースという観点からすると、ソース中で使われている各テンプレートが Lua で作らているのかウィキマークアップで作られているのかを意識する必要がないからです。 また、Lua のコードがテンプレートの形となっていると、ウィキペディアの名前空間に新たに複雑な仕組みを導入する必要はありません。

Module の構造

Moduleは {{#invoke:}} で呼び出すことのできる関数を保持するテーブルデータを返さなければなりません。 一般的には、上述の通り、まずテーブルデータを保持する変数を宣言し、そのテーブルデータに関数を追加し、最後にモジュールの最後でこのテーブルデータを返すようなコードになります。

このテーブルに追加されなかった関数は。局所関数であれ大域関数であれ、{{#invoke:}} を使って呼び出すことはできませんが、大域変数については、require() 関数を使うことで他のモジュールから参照することができます。 ですから、他のモジュールから参照されることを意図していないのであれば、全ての関数や変数は局所性のものとして宣言するのが良いことです。

ウィキマークアップから与えられた値の参照

{{#invoke:}}で呼び出された関数には、frame objectという1つのパラメータが渡されます。{{#invoke:}}に渡されたパラメータにアクセスするために、コードは通常、そのフレームオブジェクトのargsテーブルを使用します。また、frame:getParent()を使ってそのフレームのargsにアクセスすることで、{{#invoke:}}を含むテンプレートに渡されたパラメータにアクセスすることも可能です。

このフレーム・オブジェクトは、パーサー関数の呼び出し、テンプレート展開、任意個数のウィキマークアップ文字列の展開など、ウィキマークアップ・パーサーの文脈に特化したものを参照するのにも使えます。

テキストを返す

モジュール中のたいていの関数は単一の文字列データを返さなければなりません。いずれにしても関数から返された値はどんなデータ型であれ tostring() に通されて文字列になり、{{#invoke:}} の処理結果ウィキマークアップに取り込まれます。

At this point in the page parse, templates have already been expanded, parser functions and extension tags have already been processed, and pre-save transforms (i.e., signature tilde expansion, pipe trick, etc.) have already happened. Therefore the module cannot use these features in its output text. For example, if a module returns "Hello, [[world]]! {{welcome}}", the page will read "Hello, world! {{welcome}}".

他方、ウィキマークアップ {{subst:～}} については処理動作のより早い段階で扱われるため、{{#invoke:～}} に対しては {{subst:～}} 処理による代入動作だけが影響を持ちます。{{subst:～}} 処理が失敗した部分についてはウィキマークアップ上に残されることになっているので、それらは次回の「ソースを編集」の時に修正対応さることになるでしょうが、このような事態は避けるべきです。

モジュールの解説

Scribunto allows modules to be documented by automatically associating the module with a wikitext documentation page; by default, the "/doc" subpage of the module is used for this purpose and is transcluded above the module source code on the module page. For example, the documentation for "Module:Bananas" would be at "Module:Bananas/doc".

これは、以下のHelp:システムメッセージ を使用して構成できます:

• scribunto-doc-page-name — ドキュメントに使用されるページの名前を設定します。 モジュールの名前（Module: prefixなし）は$1として渡されます。 モジュール名前空間内にある場合、ここで指定されたページはLuaソースではなくwikitextとして解釈され、{{#invoke:}}と一緒に使用することはできません。 既定では "Module:$1/doc"、つまりモジュールの /doc 下位ページが表示されます。 このメッセージでは、パーサー関数およびその他のブレース拡張を使用できない場合があることに注意してください。
• scribunto-doc-page-does-not-exist — docページが存在しない場合に表示されるメッセージ。 ページの名前は$1として渡されます。 既定値は空です。
• scribunto-doc-page-show — docページが存在する場合に表示されるメッセージです。 ページの名前は$1として渡されます。 既定では、説明文書ページを参照読み込みします。
• scribunto-doc-page-header — ドキュメントページ自体を表示するときに表示されるヘッダー。 ドキュメントを作成するモジュール（Module: prefix付き）の名前は、$1として渡されます。 既定では、簡単な説明が斜体で表示されます。

Note that modules cannot be directly categorized. これらは、説明文書ページで ‎<includeonly>...‎</includeonly> タグ内に配置することができ、説明文書ページがモジュール ページに参照読み込みされたときに、モジュールに適用されます。

Renaming or moving modules

To rename or move a module, use the Move Page link in the Tools sidebar. You will want to move both the module itself, as well as the subpage containing its documentation.

Redirects

MediaWiki バージョン:

1.42 Gerrit change 574086

Since release 1.42, Scribunto recognizes one particular syntax for redirects (so they’re highlighted on special pages, appear on Special:WhatLinksHere, and so on), and also produces redirects when renaming/moving a module, similarly to how renaming of wikitext pages works (before that, module renames left no redirects behind, now extra rights are needed to suppress the redirect).

To manually create a module redirect, use the following syntax (which is valid Lua code, and worked like a redirect even before 1.42, but without MediaWiki recognizing it as such):

return require [[Module:Foo]]

Replace Foo with the name of the module you'd like to redirect to.

Please note that other similarly valid Lua syntax variations (e.g. using quotation marks instead of square brackets, using parentheses around the require parameter, or even whitespace variations) are still not recognized by MediaWiki as redirects.

Lua 言語

トークン

Lua言語における名前（または識別子）とは数字以外ではじまる文字列で、アルファベット、数字、アンダースコアで構成されます。名前は大文字と小文字を区別します。foo、Foo、FOO は、それぞれ別の名前です。

以下のキーワードは予約されており、名前として使用できません。

• and
• break
• do
• else
• elseif
• end
• false
• for
• function
• if
• in
• local
• nil
• not
• or
• repeat
• return
• then
• true
• until
• while

アンダースコアと大文字ではじまる名前は Lua 内部の大域変数として予約されています。

その他のトークン:

• #
• %
• (
• )
• *
• +
• ,
• -
• --
• .
• ..
• ...
• /
• :
• ;
• <
• <=
• =
• ==
• >
• >=
• [
• ]
• ^
• {
• }
• ~=

コメント

注釈文は文字列の外側ならどこででも--で始まります。--の直後に開き長かっこがあれば、対応する閉じ長かっこまでがコメントです。そうでなければ行末までが注釈文となります。

-- Lua 言語の注釈文は「--」で始まり、その行の行末で終わります。
--[[ 複数行に渡る文字列や注釈文は
     二つの角括弧で括ります。]]
--[=[このような形の注釈文は--[[他の注釈文]]を入れ子にすることができます。]=]
--[==[このような形の注釈文は他の
  --[===[何重にも --[=[入れ子された]=] --長い
    ]===] コメントを入れることができます。
    --[[長い括弧の対応が取れていなくても構いません。]===]
]==]

データ型

Lua は動的型付け言語です。変数や関数の引数は型を持たず、代入される値だけを持ちます。値は型を保持します。

Lua には8つの基本的なデータ型がありますが、Scribunto 拡張機能に関係するのはそのうちの6つだけです。type() 関数は値の型を返します。

tostring() 関数は値を文字列へ変換します。tonumber() 関数は可能なら値を数値へ変換し、変換できないなら nil を返します。その他のデータ型へ変換する明示的な関数はありません。

数値は、文字列が期待される場所では自動的に文字列へ変換されます。たとえば文字列連結演算子で。文字列が算術演算子に使用される場合、tonumber() によって数値へ変換されます。真偽値が期待される場所では、nil 以外の全ての値は true として扱われます。

nil

"nil" is the data type of nil, which exists to represent the absence of a value.

nil はテーブルのキーとして使用されることはなく、キーが未割り当であることと、キーとして nil が割り当てられていることは、同じことです。

文字列へ変換される場合、結果は "nil" です。真偽値へ変換される場合、nil は false とみなされます。

Note: Lua does make a distinction between nil and nothing at all in some limited situations. For example, tostring(nil) returns "nil", but tostring() throws an error, as the first parameter is required. This distinction is particularly relevant to the select() function.

真偽値

真偽値は true または false です。

文字列へ変換される場合は "true" または "false" となります。

他の言語と違って、真偽値が直接数値へ変換されることはありません。また、false と nil だけが偽値と見なされ、数値のゼロや空の文字列は真値とみなされます。

文字列

Lua 言語で文字列は8ビット幅のバイト列として扱われており、特定の文字コードとして扱うかどうかはアプリケーション・プログラムに任されています。

文字列即値はシングルクォートかダブルクォート (' または ") で区切られます。この2つに違いは無いという点で JavaScript とは同様であり、PHP とは異なります。以下のエスケープ表現が有効です。

エスケープ表現	名前	ASCIIコードポイント
\a	ベル文字	7
\b	バックスペース	8
\t	水平タブ	9
\n	改行	10
\v	垂直タブ	11
\f	フォームフィード	12
\r	キャリッジリターン	13
\"	ダブルクォート	34
\'	シングルクォート	39
\\	バックスラッシュ	92

文字列中で改行の直前にバックスラッシュ文字「\」があればそこは文字列データ中でも改行として含まれることになります。また文字列中に「'\ddd'」（ddd は 0～ 255 ）の形式の記述があれば、そこには、数字列 が表現するところのバイトデータになります。Unicode文字列をエスケープ表現で記述する場合は、UTF-8文字符号化方式でのバイトの並びを入れる必要があります。

文字列即値は長括弧によって表現することもできます。 開き長括弧は、開き角括弧で始まり、その後に0個以上の等号が続き、その後に開き角括弧で終わるものです。例えば次のものはすべて開き長括弧です:

• [[
• [=[
• [=====[

開き長括弧はそれと対応する閉じ長括弧によって閉められなければなりません。対応する閉じ長括弧とは、開き長括弧の開き角括弧「[」を閉じ角括弧「]」に置換したものです。例えば次のものはすべて閉じ長括弧です。

• ]]
• ]=]
• ]=====].

特別な場合として、開き長括弧の直後が改行になっているものについては、その改行は文字列データには含まれません。しかし閉じ長括弧の直前の改行は文字列データに含まれます。 長括弧で括られた文字列中ではエスケープ表現は特別な意味を持たず書かれてある通りの文字列データになります。

-- 長括弧で括られたこの文字列
foo = [[
bar\tbaz
]]

-- は、以下のものと等価です。
foo = 'bar\\tbaz\n'

長さ 0 の文字列を含めて、全ての文字列データは真偽値としては真値として解釈されます。

数値

Lua には数値型は一つしかなく、通常は64ビット倍精度浮動小数点数として内部的に表現されます。この形式で厳密に表現できる整数の範囲は -9007199254740991 (-2⁵³ + 1) と 9007199254740991 (2⁵³ - 1) の間であり、これを超える数値は丸め誤差が発生する可能性があります。

数値は小数点区切りとしてピリオド (.) を使用し、グループ化区切りなしで 123456.78 のように記述します。 また、指数表記を使用してスペースなしで表現することも可能です。例えば、1.23e-10、123.45e20、1.23E+5 です。 整数は 0x プレフィックスを用いた16進数記法でも指定できます。例えば、0x3A のように記述します。

A handful of number values are handled in a special way:

• Postive and negative infinity, which evalute to being greater or less than every other number, respectively (except the NaNs - see below). These can be accessed in two ways: through the math library, as math.huge and -math.huge, or through numerical operations such as 1/0 and -1/0.
• Lua occasionally distinguishes 0 and -0 (see the IEEE 754 for more information on signed zeros). 0 and -0 are strictly equivalent for almost all purposes, but behave differently in a small number of numerical operations (e.g. 1/0 returns infinity, while 1/-0 returns negative infinity). The distinction also affects conversions from number to string (and vice-versa).
• Positive and negative NaN (standing for Not a Number). No constant is provided for either of these, but 0/0 evaluates to negative NaN. Note that both NaNs have the unique quality that any comparison which involves them evaluates to false (which means they do not even evaluate as being equal to themselves). The only practical distinction between the two is on type conversion to and from string (see below).

すべての数値（0, -0、無限大、NaN を含む）は、真偽値に変換されると真とみなされることに注意してください。これは 0 が通常偽とみなされる他の多くの言語とは異なります。文字列に変換される場合、有限の数値は小数で、10¹⁴ 以上なら指数表記（例: "1e+14"）で表されます。無限大は "inf" と "-inf"、NaN は "nan" と "-nan" となります。

Known bug: the Lua interpreter will treat all instances of 0 and -0 as whichever of the two is encountered first when the script is compiled, which means that the return values of tostring(0), 1/-0 (and so on) are affected by where they occur in the code. This can cause unexpected results, particularly if all instances of 0 are converted to "-0" on return. If necessary, this can be circumvented by generating zero values using tonumber("0") and tonumber("-0"), which doesn't seem to cause or be affected by the issue. See [1].

テーブル

Lua のテーブルは、PHP の配列や JavaScript のオブジェクトによく似た連想配列です。

テーブルは波括弧を使って作成します。空のテーブルは {} です。作成時にフィールドにデータを入れるには、コンマかセミコロン、あるいはその両方で区切られたフィールド指示子のリストで記述します。次のようないくつかの形式をとります。

• [expression1] = expression2 uses the (first) value of expression1 as the key and the (first) value of expression2 as the value.
• name = expression is equivalent to ["name"] = expression
• expression is roughly equivalent to [i] = expression, where i is an integer starting at 1 and incrementing with each field specification of this form. If this is the last field specifier and the expression has multiple values, all values are used; otherwise only the first is kept.

テーブルデータ中にあるフィールド（項目）は「テーブル[キー]」という形で読み書きできます。これはブラケット記法と呼ばれます。

キーが文字列で、その文字列が Lua の識別子としても妥当であるものであれば、「テーブル.キー」という形でも読み書きできます。これはドット記法と呼ばれます。

テーブル中のフィールドの値が関数で、なおかつフィールドのキーが文字列でそのキーがLua の識別子としても妥当である場合、「テーブル:キー()」という形でその関数を呼び出すことができます。これはコロン記法と呼ばれます。これは「テーブル['キー'](テーブル, …)」や「テーブル.キー(テーブル, …)」と等価です。

配列（または「シーケンス」または「リスト」）は、次のすべての性質を満たすテーブルです：

• キーが正の整数である。
• キー範囲 1 ～ N では値が nil でない。
• キー範囲 N+1 以上では値が nil である。

多くの Lua 関数は配列を扱い、非正の整数のキーを無視します。

nil と非数を除く全ての値はテーブルのキーとして使うことができます。どのようなキーも型変換されることはありません。これらすべての値は妥当であり他の値とは異なるものとして扱われます。

-- テーブルの作成
t = {}
t["foo"] = "foo"
t.bar = "bar"
t[1] = "one"
t[2] = "two"
t[3] = "three"
t[12] = "the number twelve"
t["12"] = "文字列12"
t[true] = "true"
t[tonumber] = "yes, even functions may be table keys"
t[t] = "yes, a table may be a table key too. Even in itself."

-- 次のコードは上のテーブルとおおよそ同等なテーブルを作るものです。
t2 = {
    foo = "foo",
    bar = "bar",
    "one",
    "two",
    [12] = "the number twelve",
    ["12"] = "文字列12"、
    "three",
    [true] = "true",
    [tonumber] = "yes, even functions may be table keys",
}
t2[t2] = "yes, a table may be a table key too. Even in itself."

同様に、nil 以外のどんな値でもテーブルの値として入れることができます。nil を表に入れるというのは、対応するキーを削除するのと同じことです。また、それまでに何も値を設定されていないキーの値を参照すると nil が返されます。

Lua言語ではテーブルは暗黙に複製がつくられることはありません。例えばある関数が引数としてテーブルデータを受け取って、その関数がそのテーブルデータに対して何らかの変更を加えるとすれば、その変更はそのまま関数を呼び出し側からも見えてしまうということです。

テーブルデータを文字列に変換すると既定では "table" という文字列になるだけですが、__tostring メタメソッドをオーバラーライド（上書き）することで、この結果を変えることができます。中身が空のテーブルを含めてすべてのテーブルデータは真偽値としては真値として扱われます。

関数

Lua における関数は第一級の値です。関数は匿名のものとして作られたり、引数として渡されたり、変数に代入されたりします。

関数は function キーワードを使って作成され、括弧を使って呼び出されます。名前付き関数、ローカル関数、テーブルのメンバー関数として振る舞う関数に対しては構文糖衣が利用できます。詳しくは関数定義や関数呼出しを参照してください。

Lua の関数はクロージャ（関数閉包）です。つまり、関数は自身が定義された場所のスコープへの参照を保持し、その関数が実際に評価される場所がどこであるかに関係なく、定義された場所のスコープにある変数に対してアクセスしたり操作することが出来ます。

暗黙的に複製されることのないテーブルと同じように、関数オブジェクトも、たとえ異なる変数に代入されるとしても、また、他の関数に引数として渡されるとしても、もとの関数オブジェクトから何も変わることはありません。

関数オブジェクトは文字列へ変換されると、結果は "function" になります。

操作できないデータ型

ユーザーデータ型は、Lua を拡張するために他の言語で書かれた不明な値を保持する型として使用されます。例えばユーザーデータは C 言語のポインタや構造体を保持するのに使われる場合があります。カスタムコンパイルされたコードが許可されないホスティング環境で Scribunto を利用可能にするため、このような拡張は一切使用されません。

スレッド型はコルーチンのハンドラを表し、Scribunto のサンドボックス内では利用できません。

return p

There is a strict limit of max 60 unique upvalues acessed inside a function. An upvalue is a value declared outside of a function and used inside it. As upvalues do count:

• variables (a table with many elements counts as one upvalue)
• functions (only those directly called from function in question, not their dependencies)

A violation of the limit can be triggered by a use of such a variable or function, not by its mere presence or availability. Repeated access to same upvalue does not exhaust the limit further.

メタテーブル

すべてのテーブルはメタテーブルと呼ばれるテーブルと関連付けられています。メタテーブルが保持する各フィールドは、演算子や関数によって参照され、テーブル同士の差分を求めたり、そのテーブルに対するコールバック動作をする目的で使われます。テーブルに関連付けられたメタテーブルを取得するには getmetatable() 関数が使われ、メタテーブルを変更するには $setmetatbale 関数が使われます。

メタの機能にアクセスがあった場合、メタテーブルのフィールドはrawget()があるようにアクセスを処理します。

テーブル自体に影響するメタテーブルのフィールドは次のものです。

__index

これは テーブル[キー] が nil を返す場合に使われます。 もしこのフィールドの値がテーブルデータであれば、__index[キー] というように同じ操作がそのテーブルに対しても繰り返されます（そのテーブルのメタテーブルの __index が呼ばれます）。 もしもこのフィールドの値が関数であれば、その関数が __index(テーブル, キー) で呼び出されます。 rawget() 関数を使えばこのメタメソッドの仕組みを回避してデータの取得をすることができます。

__newindex

これはテーブルデータに対して新規に値を設定するときに使われます。コードで言えば rawget( t, key ) が nil である時に テーブル[キー] = 値 を実行する時に使われます。 もしこのフィールドの値がテーブルであれば、__newindex[キー] のようにそのテーブルに対して割り当てが行われます (この操作により、そのテーブルのメタテーブルの __newindex が呼ばれる可能性があります)。 もしもこのフィールドの値が関数であれば、その関数が __index(テーブル, キー, 値) で呼び出されます。 rawset() 関数を使えばこのメタメソッドの仕組みを回避してデータの取得をすることができます。

__call

これはテーブルに対して関数呼び出しの形（テーブル(～)）が用いられた場合に使われます。 この場合、フィールドの値は関数で __call( t, ··· ) の形で呼び出すことができるものでなければなりません。

__mode

これは弱い参照を保持するテーブルを作る場合に使われます。 フィールドの値は文字列でなければなりません。 普通のテーブルの場合、キーも値もガベージコレクションの対象にはなりません。 しかし、このフィールドの値に文字 'k' が含まれている場合、弱い参照でないものが含まれいなければ、キーはガベージコレクションの対象になります。またこのフィールドの値に文字 'v' が含まれている場合、対応するキーと値の両方がテーブルから削除されます。 テーブルがメタテーブルとして使われた後にこのフィールドが変更された場合の挙動については定義されていません。

メタテーブルの他のフィールドには以下のものがあります。

• __add^†
• __sub^†
• __mul^†
• __div^†
• __mod^†
• __pow^†
• __unm
• __concat^†
• __eq^‡
• __lt^‡
• __le^‡
• __pairs
• __ipairs
• __metatable^*
• __tostring

^† 二項演算子の場合、Lua はまず使うべきメタメソッドとして左の項を見てそれから右の項をみます。

^‡ 関係演算子の場合、メタメソッドは、両方の引数のメタテーブルで同じ関数が指定されている場合にのみ使用されます。ボディとクロージャが同じであっても、異なる無名関数は同じとは見なされない場合があります。

^* __metatable は getmetatable() と setmetatable() に影響

注意：Lua ではすべての文字列が共有する同一のメタテーブルにおいて、__index は string テーブルを参照します。このメタテーブル、あるいは参照する string テーブルは Scribunto からアクセスできません。モジュールが参照する文字列テーブルは複製です。

変数

変数とは値を格納する場所です。Lua では3種類の変数が有ります。大域変数、局所変数、テーブルのフィールドの三つです。

名前（または識別子）は大域変数や局所変数（関数の引数を含む）を表します。キーワード local を使って明示的に宣言されていない変数はすべて大域変数であるとみなされます。値を代入されていない変数は nil で初期化されたのと同じ振る舞いをします。

大域変数は「環境」と呼ばれるLua 標準のテーブルに保存されます。この変数は _G としてアクセス可能であり、しばしば使われます。この変数にメタテーブルを設定することもできます。この変数のメタメソッド __index と __newindex は、同変数のフィールドの値を参照したりフィールドに値を設定する時だけでなく、大域変数の値を参照したり大域変数に値を代入する時にも呼ばれます。

関数についの情報を収めた環境は、getfenv() 関数で取得でき、setfenv() 関数で変更することができます。Scribunto では、これら二つの関数が利用可能であるかどうかについては厳しく制限されています。

局所変数とは構文スコープを持つ変数のことです。詳しくは局所変数宣言を御覧ください。

式

式というのは何かの値を持つもののことを言います。

• リテラル（数値型、文字列型、true、false、nil）
• 無名関数宣言
• テーブルのコンストラクター
• 変数の参照
• 関数呼び出し
• vararg 式
• 何かの式が ( と ) で括られたもの
• 何かの式に単項演算子が付されたもの
• 二つの式が二項演算子で繋げられたもの

ほとんどの演算子は一つの値を持ちます。関数呼び出しと vararg 式については不特定個数の値を持ちます。関数呼び出しや vararg 式を ( と ) で括った式の場合、最初の値を除く全ての値が失われます。

式リストというのは複数の式がカンマで区切られたものを言います。カンマで区切られた最後の式以外のすべての値は式リストの値としては使われません。最後の式が持つすべての値は式リスト全体の値として使われます。

算術演算子

Lua には普通の算術演算子があります。加算、減算、乗算、除算、剰余算、べき乗、反数です。

与えられた値が数値型または文字列型のどちらかであって、それを tonumber に通した結果が非 nil であれば、これらの演算子は適切に機能します。

どれかの値がテーブル型データで、なおかつ適切なメタメソッドが伴っていれば、そのメタメソッドが呼ばれます。

演算子	関数	例	メタメソッド	備考
+	加算	a + b	__add
-	減算	a - b	__sub
*	乗算	a * b	__mul
/	除算	a / b	__div	0で割ってもエラーにはなりません、NaNかinfinityを返します
%	剰余	a % b	__mod	a % b == a - math.floor( a / b ) * b として定義
^	べき乗	a ^ b	__pow	指数は整数でなければなりません。
-	反数	-a	__unm

関係演算子

Lua 言語の関係演算子は==、~=、<、>、<=、>=です。関係演算子の評価結果はどんな場合も真偽値です。

== 演算子はまず両辺のデータ型を比較して型が不一致であれば false を返します。さもなくばこの演算子は両辺の値を比較します。nil、真偽値（false/true）、数値、文字列はそれぞれの方法で比較されます。両辺が関数であれば、二つが完全に同一の実体であるかどうかが見られます。そのため function() end == function() end という比較の場合、両者は機能としては同じでも実体としては異なるため、結果は false となります。既定の動作ではテーブルもこれと同じやり方で比較されますが、比較の仕方は __eq メタメソッドを使って変更することができます。

~= 演算子は単純な論理否定です。

関係演算子は、両辺とも数値型であるかまたは両者とも文字列型であれば直接的に比較し、その結果が false であればメタメソッドによって比較します。

• a < b で処理系は __lt を使います。
• a <= b では利用可能であれば処理系はまず __le を使い、__lt が利用可能であれば not (b < a) を評価します。
• a > b は b < a として処理されます。
• a >= b は b <= a として処理されます。

必要とするメタメソッドが存在しない場合はエラーが投げられます。

論理演算子

Lua言語の論理演算子は and、or、not です。これらの演算子は nil と false を偽値として扱い、それ以外のすべてのデータを真値として扱います。

and 演算子は、まず左側の値を評価しこれが偽値であれば左側の値を返します（短絡評価）。左側の値が偽値でなれば右側の値をそのまま返します。

or 演算子は、まず左側の値を評価しこれが真値であれば左側の値を返します（短絡評価）。左側の値が真値でなれば右側の値をそのまま返します。

not 演算子が返すのは、true または false のどちらかです。

and および or は短絡評価します。例えば、foo() or bar() は foo() が最初の値として false または nil を返す場合にのみ bar() を呼び出します。

結合演算子

結合演算子は「..」であり、a .. b のような形で使われます。a と b のふたつの値が共に数値型または文字列型である場合は両者の文字列表現を連結したものが返されます。そうでない場合、__concat メタメソッドが利用可能であればそれが使われます。それもできない場合はエラーが投げられます。

Lua の文字列はイミュータブル（書き換えが出来ないもの）であり、Lua にはいわゆる「文字列ビルダー」は存在しないため、while 文などの繰り返し中に a = a .. b とゆうようなコードがある場合、繰り返しの都度、中間的な文字列が生成されてはガベージコレクションによって回収されるという無駄が生じることになります。たくさんの文字列を一つに連結しなければならない場合は、string.format() 関数を使うとか、または個々の部分文字列を配列に追加しておいて最後に table.concat() を使う方が高速です。

長さ演算子

長さ演算子は # で、#a のように使用します。もし a が文字列ならバイト長が返されます。もし a が配列型テーブルなら配列長が返されます。

a が配列ではないテーブルの場合は、たとえ上位の添字に nil ではない値があったとしても、#a は 0 または a[N] が nil でなく a[N+1] が nil であるような任意の値 N を返す可能性があります。例:

-- a[3] が nil で a[4] が非 nil なので、これは配列ではありません。
a = { 1, 2, nil, 4 }

-- これは 2 あるいは 4 どちらも出力し得る。
-- また、テーブルが修正されていなくてもこの結果は変わり得る。
mw.log( #a )

演算子の優先順位

Lua の演算子の優先順位は、高いものから低いものへ次のようになります。

1. ^
2. not # - (算術否定)
3. * / %
4. + - (減算)
5. ..
6. < > <= >= ~= ==
7. and
8. or

同じ優先順位内では、ほとんどの2項演算子は左結合で、例えば a / b / c は (a / b) / c と評価されます。べき乗と結合演算子は右結合で、例えば a ^ b ^ c は a ^ (b ^ c) と評価されます。

関数呼び出し

Luaの関数呼び出しは、多くの他言語と似ています。名前の後に括弧で囲まれた引数のリストが続きます。

func( 式リスト )

Luaの式リストでは通常、リスト内の最後の式に複数の引数値を指定することができます。

式リストの値が関数定義の引数の数よりも少ない状態で関数が呼び出された場合、余分な引数にはnilの値が入ります。式リストに引数よりも多くの値が含まれている場合、余分な値は破棄されます。関数が可変数の引数を取ることも可能です。詳細はFunction declarationsを参照してください。

Luaでは、関数の戻り値、つまり func()() を直接呼び出すこともできます。呼び出される関数を決定するために変数アクセスよりも複雑な式が必要な場合は、変数アクセスの代わりに括弧で囲まれた式を使用することができます。

Luaには、2つの一般的なケースを想定したシンタックスシュガーがあります。1つ目は、テーブルをオブジェクトとして使用している場合で、関数をオブジェクト上のメソッドとして呼び出す場合です。構文的には

table:name( 式リスト )

は、以下と同等です

table.name( table, 式リスト )

2つ目の一般的なケースは、名前と値のマッピングを含むテーブルを関数の唯一の位置引数として渡すことで名前付き引数を実装するLuaの方法です。この場合、引数リストの周囲の括弧は省略することができます。これは、関数が単一のリテラル文字列を渡す場合にも機能します。例えば

func{ arg1 = exp, arg2 = exp }
func"string"

は、以下と同等です

func( { arg1 = exp, arg2 = exp } )
func( "string" )

これらは組み合わせることができます。次の呼び出しは同等です:

table:name{ arg1 = exp, arg2 = exp }
table.name( table, { arg1 = exp, arg2 = exp } )

関数宣言

関数宣言の構文は次のようになります:

function nameoptional ( var-listoptional )
    ブロック
end

var-list内のすべての変数は関数のローカル変数であり、関数呼び出し内の式リストから値が代入されます。追加のローカル変数はブロック内で宣言することができます。

関数が呼び出されると、var-listに対応するローカル変数が作成され、値が代入された後、block内の文が実行されます。もしreturn文に達した場合はブロックを終了し、関数呼び出し式の値はreturn文で与えられた値となります。return文に遭遇することなく関数ブロックの最後まで実行された場合、関数呼び出し式の結果はゼロの値はゼロになります。

Lua関数はlexical closuresです。一般的なイディオムは、関数が宣言されているスコープで"private static"変数をローカルとして宣言することです。例えば、

-- これは、引数に数値を追加する関数を返します
function makeAdder( n )
    return function( x )
        -- 外部スコープからの変数 n は、ここで x に追加できます。
        return x + n
    end
end

local add5 = makeAdder( 5 )
mw.log( add5( 6 ) )
-- prints 11

var-listの最後の項目として ... を指定することにより、関数は可変数の引数を受け入れるように宣言できます:

function nameoptional ( var-list, ... )
    ブロック
end
-- or
function nameoptional ( ... )
    ブロック
end

ブロック内では、可変引数式 ... を使用でき、その結果、関数呼び出しのすべての追加値が得られます。例えば、

local join = function ( separator, ... )
    -- 追加の引数を新しいテーブルとして取得します
    local args = { ... }
    -- 追加引数の数を正しく取得します
    local n = select( '#', ... )
    return table.concat( args, separator, 1, n )
end

join( ', ', 'foo', 'bar', 'baz' )
-- 文字列"foo, bar, baz"を返します

select() 関数は、可変引数式で機能するように設計されています。 特に、{ ... } はsequenceではない可能性があるため、可変引数式の値の数をカウントするには、#{ ... } の代わりに select( '#', ... ) を使用する必要があります。

Luaは、関数宣言と変数への代入を組み合わせるための糖衣構文を提供します。詳細はFunction declaration statementsを参照してください。

次に示すコードは動作しません:

local factorial = function ( n )
    if n <= 2 then
        return n
    else
        return n * factorial( n - 1 )
    end
end

関数宣言はローカル変数の代入文が完了する前に処理されるので、関数本体内の"factorial"は外部スコープ内のその名前の(おそらく未定義の)変数を参照します。この問題は、最初にローカル変数を宣言してから後続の文で代入するか、function declaration statement構文を使用することで回避できます。

ステートメント

ステートメント (statement) は実行の基本単位です。1 つの割り当て、制御構造、関数呼び出し、変数宣言などです。

チャンク (chunk) とは、セミコロンで区切られた一連のステートメントのことです。チャンクは基本的に無名関数の本体とみなされ、ローカル変数の宣言、引数の受け取り、値を返すことができます。

ブロック (block)は、チャンクと同じように、一連のステートメントです。ブロックを区切ることで、1 つのステートメントにすることができます。do ブロック end となります。これらは、ローカル変数のスコープを制限したり、他のブロックの途中で return や break を追加するために使用されることがあります。

Assignments

variable-list = 式リスト

variable-list は、コンマで区切られた変数のリスト、expression-list は、コンマで区切られた一つ以上の式のリストです。すべての式は代入が行われる前に評価されるので、a, b = b, a はaとbの値を入れ替えることになります。

局所変数の宣言

local 変数リスト

local 変数リスト = 式リスト

ローカル変数は、blockまたはchunk内のどこでも宣言することができます。式のリストがない最初の形式では、変数を宣言しますが、値を割り当てないので、すべての変数の値はnilになります。2番目の形式では、上記のAssignmentsで説明したように、ローカル変数に値を割り当てます。

ローカル変数の可視性は、ローカル変数宣言の後のステートメントで始まることに注意してください。つまり、local x = x のような宣言は、ローカル変数 x を宣言し、それに外部スコープからの x の値を割り当てます。ローカル変数は、ローカル変数宣言を含む最も内側のブロックの終わりまで、スコープ内に残ります。

制御構造

while 式 do ブロック end

while文は、式の評価値がtrueの値である限り、blockを繰り返します。

repeat ブロック until 式

repeatステートメントは、式の評価値が真の値になるまでblockを繰り返します。blockの中で宣言されたローカル変数は、式の中でアクセスすることができます。

for name = exp1, exp2, exp3 do ブロック end
for name = exp1, exp2 do ブロック end

このforループの最初の形では、ローカル変数を宣言し、exp1からexp2までの値に対してブロックを繰り返し、繰り返しごとにexp3を加えていきます。なお、exp3は完全に省略することができ、その場合は1が使用されますが、nil や false などの非数値はエラーになります。すべての式は、ループが開始される前に一度だけ評価されます。

このforループの形式は、おおよそ次のようなものと同じです

do
    local var, limit, step = tonumber( exp1 ), tonumber( exp2 ), tonumber( exp3 )
    if not ( var and limit and step ) then
        error()
    end
    while ( step > 0 and var <= limit ) or ( step <= 0 and var >= limit ) do
        local name = var
        block
        var = var + step
    end
end

ただし、変数var、limit、stepは他の場所ではアクセスできません。変数nameは block 内のローカル変数であり、ループの後でその値を使用するには、ループの外で宣言された変数にコピーする必要があることに注意してください。

for var-list in 式リスト do block end

forループの第2の形式は，iterator関数で動作します．第1の形式と同様に，expression-listはループを開始する前に1回だけ評価されます。

このforループの形式は、おおよそ次のようなものと同じです

do
    local func, static, var = expression-list
    while true do
        local var-list = func( static, var )
        var = var1  -- ''var1'' is the first variable in ''var-list''
        if var == nil then
            break
        end
        block
    end
end

ただし、ここでも変数 func, static, var は他の場所ではアクセスできません。なお、var-listの変数はblock 内のローカル変数であり、ループの後で使用するには、ループの外で宣言された変数にコピーする必要があります。

多くの場合、expression-listは3つの値を返す単一の関数呼び出しです。 渡されたパラメーターのみに依存するように iterator 関数を記述できる場合は、それが最も効率的です。そうでない場合、Programming in Luaは、テーブルを静的変数として返し、反復ごとにそのメンバーを更新するよりも、クロージャを優先することを提案しています。

if 式1 then ブロック1 elseif 式2 then ブロック2 else ブロック3 end

Executes block1 if exp1 returns true, otherwise executes block2 if exp2 returns true, and block3 otherwise. The else block3 portion may be omitted, and the elseif exp2 then block2 portion may be repeated or omitted as necessary.

return 式リスト

returnステートメントは、関数またはchunk（単なる関数）から値を返すために使用されます。expression-listは、0個以上の式のコンマで区切ったリストです。

Luaはtail callsを実装しています。expression-listが関数呼び出しであるちょうど1つの式で構成されている場合、現在のスタックフレームはその関数への呼び出しに再利用されます。これは、getfenv()やdebug.traceback()のようなコールスタックを扱う関数に影響を与えます。

returnステートメントは、そのblockの最後のステートメントである必要があります。何らかの理由で block の途中で return が必要な場合は、明示的な block do return end を使用できます。

break

breakステートメントは、while、repeat、forなどのループの実行を終了し、ループの後の次のステートメントにスキップするために使用されます。

break文は、block内の最後の文である必要があります。何らかの理由で block の途中で break が必要な場合は、明示的に block do break end を使用できます。

Unlike some other languages, Lua does not have a "continue" statement for loops (i.e. a statement to move onto the next iteration without breaking the loop altogether).

It is straightforward to achieve the same effect by nesting a repeat ... until true block immediately inside the main loop, which will only ever iterate once for each iteration of the main loop (as its condition is always true). Using break will only end the inner loop, which has the practical effect of causing the main loop to continue onto the next iteration.

If it is necessary to use break on the main loop, simply declare a variable which is checked each time the inner loop completes, and set it when necessary.

ステートメントとしての関数呼び出し

関数の呼び出しをステートメントとして使用することができます。この場合、関数はその関数が持つ可能性のある副作用(例えば mw.log() ログの値)のためだけに呼び出され、戻り値はすべて破棄されます。

関数宣言文

Luaは、関数を宣言し、それを変数に割り当てることをより自然にするためのシンタックスシュガー（糖衣構文）を提供します。 次の宣言のペアは同等です

-- 基本宣言
function func( var-list ) block end
func = function ( var-list ) block end

-- 局所変数
local function func( var-list ) block end
local func; func = function ( var-list ) block end

-- Function as a field in a table
function table.func( var-list ) block end
table.func = function ( var-list ) block end

-- Function as a method in a table
function table:func( var-list ) block end
table.func = function ( self, var-list ) block end

ここでのコロン表記は、関数呼び出しのコロン表記と類似しており、引数リストの先頭に self という暗黙の引数を追加します。

エラーハンドリング

エラーを投げるには，error()およびassert()関数を用います。エラーを受け取るには，pcall()またはxpcall()関数を用います。注意: Scribunto内部におけるいくつかのエラーは，Luaコードでは受け取れません。

ガーベージコレクション

Luaは自動メモリ管理を実行します。これは、新しいオブジェクトにメモリを割り当てることや、オブジェクトが不要になったときにメモリを解放することについて心配する必要がないことを意味します。Luaは、garbage collectorを時々実行して、すべてのデッドオブジェクト（つまり、Luaからアクセスできなくなったオブジェクト）とweak referencesを介してのみ到達可能なオブジェクト）を収集することにより、メモリを自動的に管理します。Luaが使用するすべてのメモリは、テーブル、関数、文字列などの自動管理の対象となります。

ガベージコレクションは自動的に行われ、Scribunto 内で設定することはできません。

標準ライブラリ

標準のLuaライブラリは、Luaに不可欠なサービスとパフォーマンスが重要な機能を提供します。Scribunto で利用可能な標準ライブラリの部分のみがここに記載されています。

基本機能

_G

この変数は、現在の大域変数テーブルへの参照を保持します。 大域変数fooは_G.fooとしてアクセスすることもできます。ただし、_G自体について特別なことは何もないことに注意してください。他の変数と同じ方法で再割り当てできます。

foo = 1
mw.log( foo ) -- logs "1"
_G.foo = 2
mw.log( foo ) -- logs "2"
_G = {}       -- _G no longer points to the global variable table
_G.foo = 3
mw.log( foo ) -- still logs "2"

大域変数テーブルは、他のテーブルと同じように使用できます。 例えば、

-- 変数に格納されている名前の関数を呼び出す
_G[var]()

-- すべての大域変数の名前と文字列化された値を記録します
for k, v in pairs( _G ) do
   mw.log( k, v )
end

-- 新しい大域変数の作成を記録する
setmetatable( _G, {
    __newindex = function ( t, k, v )
         mw.log( "Creation of new global variable '" .. k .. "'" )
         rawset( t, k, v )
    end
} )

_VERSION

実行中のLuaのバージョンを含む文字列。例: "Lua 5.1"

assert

assert( v, message, ... )

もしv が nil または false の場合、エラーを通知します。その場合、エラー文として message を採用します。もし nil (あるいは特定しない場合) の場合、エラー文は「assertion failed!」です。文字列もしくは数値の場合、文はその値です。その他の場合、それ自体が問題の原因だと断定します。

もしvが他の値であれば、assertはvとmessageを含むすべての引数を返します。

Luaでやや一般的なイディオムは、関数が通常動作時には "true" を返し、失敗時には最初の値として nil または false を返し、2番目の値としてエラーメッセージを返すというものです。簡単なエラーチェックは、assertへの呼び出しでラップすることで実装できます。

-- これでは、エラーをチェックすることはできません
local result1, result2, etc = func( ... )

-- これは、同じように動作しますが、エラーをチェックします
local result1, result2, etc = assert( func( ... ) )

error

error( message, level )

エラーを発生させ、テキスト message を表示します。

errorは通常、エラーの発生場所に関する情報を追加します。level が 1 または省略された場合、その情報は error 自身の呼び出しの位置であり、2 は error を呼び出した関数の呼び出しの位置を使用し、以下同様です。0を渡すと、場所の情報は含まれません。

getfenv

getfenv( f )

この機能は、エンジンの構成がallowEnvFuncsの場合、使用できないことがあります。

fで指定されているように、環境（大域変数の表）を返します。

• 1，nil，および省略された場合，getfenvを呼び出す関数の環境を返します。しばしば_Gと同じになります。
• 2から10の整数が指定された場合，呼び出し履歴における高位の関数の環境を返します。たとえば，2を指定した場合，現在の関数を呼び出した関数の環境を返し，3の場合はその関数を呼び出した関数を返すといった具合です。呼び出し履歴にある関数以上の値を指定した場合，および指定した関数が末尾呼び出しされていた場合はエラーとなります。
• 関数を指定した場合，その関数が呼び出されたさいの環境を返します。

すべての標準ライブラリ関数と Scribunto ライブラリ関数で使用される環境は保護されています。getfenv を使ってこれらの環境にアクセスしようとすると、代わりに nil が返されます。

getmetatable

getmetatable( table )

tableのmetatableを返します。それ以外の型は nil を返します。

metatable に__metatableフィールドがある場合は、実際の metatable ではなく、その値が返されます。

ipairs

ipairs( t )

イテレータ関数、テーブル t、0の3つの値を返します。これは、iterator form of forでの使用を想定しています。

for i, v in ipairs( t ) do
    -- process each index-value pair
end

これは、( 1, t[1] )、( 2, t[2] )などのペアを反復し、t[i]がnilになった時点で停止します。

標準的な動作は、__ipairs metamethodを指定することでオーバーライドすることができます。そのメタメソッドが存在する場合、ipairsの呼び出しは、代わりに__ipairs( t )で返された3つの値を返します。

next

next( table, key )

これにより、テーブルの中のキーを繰り返し処理することができます。keyがnilまたは指定されていない場合は、テーブルの「最初の」キーとその値を返し、そうでない場合は「次の」キーとその値を返します。それ以上のキーがない場合は、nilを返します。テーブルが空であるかどうかは、next( t ) == nilという式を使って調べることができます。

数値インデックスを持つテーブルの場合でも、キーが返される順序は指定されていないことに注意してください。テーブルを数値順にたどるには、numerical forまたはipairsを使用します。

探索にnextを使用しているときに、存在しないキーに値が割り当てられた場合の動作は未定義です。既存のフィールドに新しい値(nilを含む)を割り当てることは可能です。

pairs

pairs( t )

イテレータ関数(nextまたはそれに類するもの)、テーブルt、そしてnilの3つの値を返します。これは、iterator form of forでの使用を想定しています。

for k, v in pairs( t ) do
    -- 各キーと値のペアを処理します
end

これは、nextと同様に t のキーと値のペアを繰り返し処理します。探索中にテーブルを変更する際の制限については next のドキュメントを参照ください。

標準の動作を上書きするには、__pairs metamethodを指定します。そのメタメソッドが存在する場合、pairs の呼び出しは __pairs( t ) が返す 3 つの値を代わりに返します。

pcall

pcall( f, ... )

与えられた引数で関数 f を protected mode で呼び出します。つまり、f の呼び出し中にエラーが発生した場合、pcall は false を返し、エラー・メッセージが表示されます。エラーが発生しなかった場合、 pcall は true を返し、呼び出しによって返されたすべての値を返します。

pseudocodeでは、pcallは次のように定義されている可能性があります。

function pcall( f, ... )
    try
        return true, f( ... )
    catch ( message )
        return false, message
    end
end

rawequal

rawequal( a, b )

これは、__eqのmetamethodを無視することを除いて、a == bと同じです。

rawget

rawget( table, k )

これは、__indexのmetamethodを無視することを除いて、table[k]と同じです。

rawset

rawset( table, k, v )

これは、__newindexのmetamethodを無視することを除いて、table[k] = vと同じです。

select

select( index, ... )

もし index が数値の場合、... はその検索後、すべての議論を返します。 もし index が文字列 "#" の場合、... において引数の数を返します。

Note: unlike tables, lists of arguments (including the vararg expression ...) treat nil as a distinct value (see documentation for # and unpack for the problem with nil in tables). For example:

• select(2, "foo", "bar") returns "bar".
• select(2, "foo", nil, "bar", nil) returns nil, "bar", nil.
• select("#", "foo", "bar") returns 2.
• select("#", "foo", "bar", nil) returns 3.

In other words, select is roughly like the following (except that it also handles any nil arguments after the final non-nil argument):

function select( index, ... )
    local t = { ... }
    local maxindex = table.maxn( t )
    if index == "#" then
        return maxindex
    else
        return unpack( t, index, maxindex )
    end
end

setmetatable

setmetatable( table, metatable )

metatableのtableを設定します。metatableはnilの場合がありますが、明示的に指定する必要があります。

現在のメタテートに__metatableフィールドがある場合、setmetatableはエラーを投げます。

tonumber

tonumber( value, base )

value を数値に変換しようと試みます。それが数値もしくは文字列で数値に変換可能な場合、tonumber 箱の数値を返します。それ以外は nil を返します。

オプションのbase（既定値 10）は、数字を解釈する基数を指定します。基数は、2から36までの任意の整数です。10以上の基数では、文字 'A' （大文字または小文字）が10を、'B'が11を、そして'Z'が35を表します。

基数10では、値に小数部分があり、E notationで表され、基数16を示す先頭に「0x」が付いている場合があります。他の基数では、符号なし整数のみが受け入れられます。

tostring

tostring( value )

valueを文字列に変換します。それぞれの型がどのように変換されるかについての詳細は、上記のData typesを参照してください。

テーブルの標準的な動作は、__tostring metamethodを指定することで上書きすることができます。そのメタメソッドが存在する場合、tostring の呼び出しは、代わりに __tostring( value ) で返される単一の値を返します。

type

type( value )

valueのタイプを文字列で返します："nil"、"number"、"string"、"boolean"、"table"、"function"。

unpack

unpack( table, i, j )

指定した表の指定した位置にある値を返します。表の例: table[i], table[i+1], ···, table[j]。iがnilまたは未指定の場合の既定値は1であり，jの既定値は#tableです。

If the table does not have a value for a particular key, unpack will return nil for that value. For example, unpack({"foo", [3] = "bar"}, 1, 4) returns "foo", nil, "bar", nil.

注意: table が配列でなく，jがnilまたは未指定の場合，得られる結果は不定です。詳細は長さ演算子を参照してください。

xpcall

xpcall( f, errhandler )

pcallとほとんど同じですが，値を返すまえにエラー内容がerrhandlerにわたるという点で異なります。

pseudocodeでは、xpcallは次のように定義されている可能性があります。

function xpcall( f, errhandler )
    try
        return true, f()
    catch ( message )
        message = errhandler( message )
        return false, message
    end
end

デバッグライブラリ

debug.traceback

debug.traceback(題名, 順位)

呼び出し履歴の遡及的追跡結果を返します。結果の始めに表示される題名を指定できます。遡及的追跡を開始する履歴の順位を指定することもできます。

数学ライブラリ

math.abs

math.abs( x )

xの絶対値を返します。

math.acos

math.acos( x )

Returns the arc cosine of x (given in radians).

math.asin

math.asin( x )

Returns the arc sine of x (given in radians).

math.atan

math.atan( x )

Returns the arc tangent of x (given in radians).

math.atan2

math.atan2( y, x )

Returns the arc tangent of y/x (given in radians), using the signs of both parameters to find the quadrant of the result.

math.ceil

math.ceil( x )

Returns the smallest integer larger than or equal to x.

math.cos

math.cos( x )

Returns the cosine of x (given in radians).

math.cosh

math.cosh( x )

Returns the hyperbolic cosine of x.

math.deg

math.deg( x )

Returns the angle x (given in radians) in degrees.

math.exp

math.exp( x )

Returns the value $e^x$.

math.floor

math.floor( x )

Returns the largest integer smaller than or equal to x.

math.fmod

math.fmod( x, y )

Returns the remainder of the division of x by y that rounds the quotient towards zero. For example, math.fmod( 10, 3 ) yields 1.

math.frexp

math.frexp( x )

Returns two values m and e such that:

• If x is finite and non-zero: $x=m\times 2^e$, e is an integer, and the absolute value of m is in the range $[0.5,1)$
• If x is zero: m and e are 0
• If x is NaN or infinite: m is x and e is not specified

math.huge

The value representing positive infinity; larger than or equal to any other numerical value.

math.ldexp

math.ldexp( m, e )

Returns $m\times 2^e$ (e should be an integer).

math.log

math.log( x )

Returns the natural logarithm of x.

math.log10

math.log10( x )

Returns the base-10 logarithm of x.

math.max

math.max( x, ... )

Returns the maximum value among its arguments.

Behavior with NaNs is not specified. With the current implementation, NaN will be returned if x is NaN, but any other NaNs will be ignored.

math.min

math.min( x, ... )

Returns the minimum value among its arguments.

Behavior with NaNs is not specified. With the current implementation, NaN will be returned if x is NaN, but any other NaNs will be ignored.

math.modf

math.modf( x )

Returns two numbers, the integral part of x and the fractional part of x. For example, math.modf( 1.25 ) yields 1, 0.25.

math.pi

The value of $\pi$.

math.pow

math.pow( x, y )

Equivalent to x^y.

math.rad

math.rad( x )

Returns the angle x (given in degrees) in radians.

math.random

math.random( m, n )

Returns a pseudo-random number.

The arguments m and n may be omitted, but if specified must be convertible to integers.

• With no arguments, returns a real number in the range $[0,1)$
• With one argument, returns an integer in the range $[1,m]$
• With two arguments, returns an integer in the range $[m,n]$

Note that incorrect output may be produced if m or n are less than −2147483648 or greater than 2147483647, or if n - m is greater than 2147483646.

math.randomseed

math.randomseed( x )

Sets x as the seed for the pseudo-random generator.

Note that using the same seed will cause math.random to output the same sequence of numbers.

math.randomseed( tonumber( mw.getContentLanguage():formatDate( "U" ) ) * 10000 + os.clock() * 10000 )

math.sin

math.sin( x )

Returns the sine of x (given in radians).

math.sinh

math.sinh( x )

Returns the hyperbolic sine of x.

math.sqrt

math.sqrt( x )

Returns the square root of x. Equivalent to x^0.5.

math.tan

math.tan( x )

Returns the tangent of x (given in radians).

math.tanh

math.tanh( x )

Returns the hyperbolic tangent of x.

Operating system library

os.clock

os.clock()

Returns an approximation of the amount in seconds of CPU time used by the program.

os.date

os.date( format, time )

Language library's formatDate may be used for more comprehensive date formatting

日付と時間を添え、format の規定する書式を設定した文字列もしくはテーブルを返します。書式が除去されたり nil の場合、"%c" を採用します。

If time is given, it is the time to be formatted (see os.time()). Otherwise the current time is used.

format の1文字目が '!' の場合、データはサーバのローカルの時間ではなく UTC rでフォーマットします。このオプションの文字に続いてフォーマットが文字列 "*t" の場合、日付は以下のフィールドのあるテーブルを返します。

• year (full)
• month (1–12)
• day (1–31)
• hour (0–23)
• min (0–59)
• sec (0–60, to allow for leap seconds)
• wday (weekday, Sunday is 1)
• yday (day of the year)
• isdst (daylight saving flag, a boolean; may be absent if the information is not available)

If format is not "*t", then date returns the date as a string, formatted according to the same rules as the C function strftime.

os.difftime

os.difftime( t2, t1 )

Returns the number of seconds from t1 to t2.

os.time

os.time( table )

Returns a number representing the current Unix time.

When called without arguments, returns the current time. If passed a table, the time encoded in the table will be parsed. The table must have the fields "year", "month", and "day", and may also include "hour" (default 12), "min" (default 0), "sec" (default 0), and "isdst".

Package library

require

require( modulename )

Loads the specified module.

First, it looks in package.loaded[modulename] to see if the module is already loaded. If so, returns package.loaded[modulename].

Otherwise, it calls each loader in the package.loaders sequence to attempt to find a loader for the module. If a loader is found, that loader is called. The value returned by the loader is stored into package.loaded[modulename] and is returned.

See the documentation for package.loaders for information on the loaders available.

For example, if you have a module "Module:Giving" containing the following:

local p = {}

p.someDataValue = 'Hello!'

return p

You can load this in another module with code such as this:

local giving = require( "Module:Giving" )

local value = giving.someDataValue -- value is now 'Hello!'

package.loaded

This table holds the loaded modules. The keys are the module names, and the values are the values returned when the module was loaded.

package.loaders

This table holds the sequence of searcher functions to use when loading modules. Each searcher function is called with a single argument, the name of the module to load. If the module is found, the searcher must return a function that will actually load the module and return the value to be returned by require. Otherwise, it must return nil.

Scribunto provides two searchers:

1. Look in package.preload[modulename] for the loader function
2. Look in the modules provided with Scribunto for the module name, and if that fails look in the Module: namespace. The "Module:" prefix must be provided.

Note that the standard Lua loaders are not included.

package.preload

This table holds loader functions, used by the first searcher Scribunto includes in package.loaders.

package.seeall

package.seeall( table )

Sets the __index metamethod for table to _G.

文字列ライブラリ

すべての文字列関数では1文字目は C、PHP、JavaScript の position 0 ではなく position 1 です。索引はマイナスとなる場合があり、その場合は文字列末から数えます。文字列末尾は position -1 となり、-2 が末尾から2番目のように続きます。

Warning: The string library assumes one-byte character encodings. It cannot handle Unicode characters. To operate on Unicode strings, use the corresponding methods in the Scribunto Ustring library.

string.byte

string.byte( s, i, j )

If the string is considered as an array of bytes, returns the byte values for s[i], s[i+1], ···, s[j]. The default value for i is 1; the default value for j is i. Identical to mw.ustring.byte().

string.char

string.char( ... )

Receives zero or more integers. Returns a string with length equal to the number of arguments, in which each character has the byte value equal to its corresponding argument.

local value = string.char( 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x21 ) --value is now 'Hello!'

See mw.ustring.char() for a similar function that uses Unicode codepoints rather than byte values.

string.find

string.find( s, pattern, init, plain )

Looks for the first match of pattern in the string s. If it finds a match, then find returns the offsets in s where this occurrence starts and ends; otherwise, it returns nil. If the pattern has captures, then in a successful match the captured values are also returned after the two indices.

A third, optional numerical argument init specifies where to start the search; its default value is 1 and can be negative. A value of true as a fourth, optional argument plain turns off the pattern matching facilities, so the function does a plain "find substring" operation, with no characters in pattern being considered "magic".

Note that if plain is given, then init must be given as well.

See mw.ustring.find() for a similar function extended as described in Ustring patterns and where the init offset is in characters rather than bytes.

string.format

string.format( formatstring, ... )

Returns a formatted version of its variable number of arguments following the description given in its first argument (which must be a string).

The format string uses a limited subset of the printf format specifiers:

• Recognized flags are '-', '+', ' ', '#', and '0'.
• Integer field widths up to 99 are supported. '*' is not supported.
• Integer precisions up to 99 are supported. '*' is not supported.
• Length modifiers are not supported.
• Recognized conversion specifiers are 'c', 'd', 'i', 'o', 'u', 'x', 'X', 'e', 'E', 'f', 'g', 'G', 's', '%', and the non-standard 'q'.
• Positional specifiers (e.g. "%2$s") are not supported.

The conversion specifier q is like s, but formats the string in a form suitable to be safely read back by the Lua interpreter: the string is written between double quotes, and all double quotes, newlines, embedded zeros, and backslashes in the string are correctly escaped when written.

Conversion between strings and numbers is performed as specified in Data types; other types are not automatically converted to strings. Strings containing NUL characters (byte value 0) are not properly handled.

Identical to mw.ustring.format().

string.gmatch

string.gmatch( s, pattern )

Returns an iterator function that, each time it is called, returns the next captures from pattern over string s. If pattern specifies no captures, then the whole match is produced in each call.

For this function, a '^' at the start of a pattern is not magic, as this would prevent the iteration. It is treated as a literal character.

See mw.ustring.gmatch() for a similar function for which the pattern is extended as described in Ustring patterns.

string.gsub

string.gsub( s, pattern, repl, n )

Returns a copy of s in which all (or the first n, if given) occurrences of the pattern have been replaced by a replacement string specified by repl, which can be a string, a table, or a function. gsub also returns, as its second value, the total number of matches that occurred.

If repl is a string, then its value is used for replacement. The character % works as an escape character: any sequence in repl of the form %d, with d between 1 and 9, stands for the value of the d-th captured substring. The sequence %0 stands for the whole match, and the sequence %% stands for a single %.

If repl is a table, then the table is queried for every match, using the first capture as the key; if the pattern specifies no captures, then the whole match is used as the key.

If repl is a function, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order; if the pattern specifies no captures, then the whole match is passed as a sole argument.

If the value returned by the table query or by the function call is a string or a number, then it is used as the replacement string; otherwise, if it is false or nil, then there is no replacement (that is, the original match is kept in the string).

See mw.ustring.gsub() for a similar function in which the pattern is extended as described in Ustring patterns.

string.len

string.len( s )

Returns the length of the string, in bytes. Is not confused by ASCII NUL characters. Equivalent to #s.

See mw.ustring.len() for a similar function using Unicode codepoints rather than bytes.

string.lower

string.lower( s )

Returns a copy of this string with all ASCII uppercase letters changed to lowercase. All other characters are left unchanged.

See mw.ustring.lower() for a similar function in which all characters with uppercase to lowercase definitions in Unicode are converted.

string.match

string.match( s, pattern, init )

Looks for the first match of pattern in the string. If it finds one, then match returns the captures from the pattern; otherwise it returns nil. If pattern specifies no captures, then the whole match is returned.

A third, optional numerical argument init specifies where to start the search; its default value is 1 and can be negative.

See mw.ustring.match() for a similar function in which the pattern is extended as described in Ustring patterns and the init offset is in characters rather than bytes.

string.rep

string.rep( s, n )

Returns a string that is the concatenation of n copies of the string s. Identical to mw.ustring.rep().

string.reverse

string.reverse( s )

Returns a string that is the string s reversed (bytewise).

string.sub

string.sub( s, i, j )

Returns the substring of s that starts at i and continues until j; i and j can be negative. If j is nil or omitted, it will continue until the end of the string.

In particular, the call string.sub(s,1,j) returns a prefix of s with length j, and string.sub(s, -i) returns a suffix of s with length i.

See mw.ustring.sub() for a similar function in which the offsets are characters rather than bytes.

string.ulower

string.ulower( s )

An alias for mw.ustring.lower().

string.upper

string.upper( s )

Returns a copy of this string with all ASCII lowercase letters changed to uppercase. All other characters are left unchanged.

See mw.ustring.upper() for a similar function in which all characters with lowercase to uppercase definitions in Unicode are converted.

string.uupper

string.uupper( s )

An alias for mw.ustring.upper().

Patterns

Note that Lua's patterns are similar to regular expressions, but are not identical. In particular, note the following differences from regular expressions and PCRE:

• The quoting character is percent (%), not backslash (\).

• Dot (.) always matches all characters, including newlines.

• No case-insensitive mode.

• No alternation (the | operator).

• Quantifiers (*, +, ?, and -) may only be applied to individual characters or character classes, not to capture groups.

• The only non-greedy quantifier is -, which is equivalent to PCRE's *? quantifier.

• No generalized finite quantifier (e.g. the {n,m} quantifier in PCRE).

• The only zero-width assertions are ^, $, and the %f[set] "frontier" pattern; assertions such as PCRE's \b or (?=···) are not present.

• Patterns themselves do not recognize character escapes such as \ddd. However, since patterns are strings these sort of escapes may be used in the string literals used to create the pattern-string.

Also note that a pattern cannot contain embedded zero bytes (ASCII NUL, "\0"). Use %z instead.

Also see Ustring patterns for a similar pattern-matching scheme using Unicode characters.

Character class

A character class is used to represent a set of characters. The following combinations are allowed in describing a character class:

x	(where x is not one of the magic characters ^$()%.[]*+-?) represents the character x itself.
.	(a dot) Represents all characters.
%a	Represents all ASCII letters.
%c	Represents all ASCII control characters.
%d	Represents all digits.
%l	Represents all ASCII lowercase letters.
%p	Represents all punctuation characters.
%s	Represents all ASCII space characters.
%u	Represents all ASCII uppercase letters.
%w	Represents all ASCII alphanumeric characters. Note it doesn't include the underscore character (_), contrarily to the usual class \w in regular expressions.
%x	Represents all hexadecimal digits.
%z	Represents ASCII NUL, the zero byte.
%A	All characters not in %a.
%C	All characters not in %c.
%D	All characters not in %d.
%L	All characters not in %l.
%P	All characters not in %p.
%S	All characters not in %s.
%U	All characters not in %u.
%W	All characters not in %w.
%X	All characters not in %x.
%Z	All characters not in %z.
%y	(where y is any non-alphanumeric character) represents the character y. This is the standard way to escape the magic characters. Any punctuation character (even the non magic) can be preceded by a '%' when used to represent itself in a pattern.
[set]	Represents the class which is the union of all characters in set. A range of characters can be specified by separating the end characters of the range with a '-'. All classes %y described above can also be used as components in set. All other characters in set represent themselves. For example, [%w_] (or [_%w]) represents all alphanumeric characters plus the underscore, and [0-7] represents the octal digits. To include literal '-' in the set, use '%-', so [0-7%l%-] represents the octal digits plus the lowercase letters plus the '-' character. The interaction between ranges and classes is not defined. Therefore, patterns like [%a-z] or [a-%%] have no meaning.
[^set]	Represents the complement of set, where set is interpreted as above.

Pattern items

A pattern item can be

• a single character class, which matches any single character in the class;

• a single character class followed by '*', which matches 0 or more repetitions of characters in the class. These repetition items will always match the longest possible sequence;

• a single character class followed by '+', which matches 1 or more repetitions of characters in the class. These repetition items will always match the longest possible sequence;

• a single character class followed by '-', which also matches 0 or more repetitions of characters in the class. Unlike '*', these repetition items will always match the shortest possible sequence;

• a single character class followed by '?', which matches 0 or 1 occurrence of a character in the class;

• %n, for n between 1 and 9; such item matches a substring equal to the n-th captured string (see below);

• %bxy, where x and y are two distinct characters; such item matches strings that start with x, end with y, and where the x and y are balanced. This means that, if one reads the string from left to right, counting +1 for an x and -1 for a y, the ending y is the first y where the count reaches 0. For instance, the item %b() matches expressions with balanced parentheses.

• %f[set], a frontier pattern; such item matches an empty string at any position such that the next character belongs to set and the previous character does not belong to set. The set set is interpreted as previously described. The beginning and the end of the subject are handled as if they were the character '\0'.

Note that frontier patterns were present but undocumented in Lua 5.1, and officially added to Lua in 5.2. The implementation in Lua 5.2.1 is unchanged from that in 5.1.0.

Pattern

A pattern is a sequence of pattern items.

A ^ at the beginning of a pattern anchors the match at the beginning of the subject string.

A $ at the end of a pattern anchors the match at the end of the subject string. At other positions, ^ and $ have no special meaning and represent themselves.

Captures

A pattern can contain sub-patterns enclosed in parentheses; they describe captures. When a match succeeds, the substrings of the subject string that match captures are stored ("captured") for future use. Captures are numbered according to their left parentheses. For instance, in the pattern (a*(.)%w(%s*)), the part of the string matching a*(.)%w(%s*) is stored as the first capture (and therefore has number 1); the character matching . is captured with number 2, and the part matching %s* has number 3.

Capture references can appear in the pattern string itself, and refer back to text that was captured earlier in the match. For example, ([a-z])%1 will match any pair of identical lowercase letters, while ([a-z])([a-z])([a-z])[a-z]%3%2%1 will match any 7-letter palindrome.

As a special case, the empty capture () captures the current string position (a number). For instance, if we apply the pattern "()aa()" on the string "flaaap", there will be two captures: 3 and 5.

Known limitations: Unlike Ustring library patterns, String library patterns may not contain more than 32 captures. If the pattern has more, then the String function will throw an error. Because the Ustring library has its own maximum of 10,000 bytes for patterns (unlike the String library), it is therefore impossible to use a pattern which exceeds both limits, as it will be incompatible with both libraries.

Table library

Most functions in the table library assume that the table represents a sequence.

The functions table.foreach(), table.foreachi(), and table.getn() may be available but are deprecated; use a for loop with pairs(), a for loop with ipairs(), or the length operator #, respectively. The function table.setn() is completely obsolete, however, and will throw an error if used.

table.concat

table.concat( table, sep, i, j )

Given an array where all elements are strings or numbers, returns table[i] .. sep .. table[i+1] ··· sep .. table[j].

The default value for sep is an empty string, the default for i is 1, and the default for j is the length of the table. If i is greater than j, it returns an empty string.

table.insert

table.insert( table, value )
table.insert( table, pos, value )

Inserts element value at position pos in table, shifting up other elements to open space, if necessary. The default value for pos is the length of the table plus 1, so that a call table.insert(t, x) inserts x at the end of table t.

Elements up to #table are shifted; see Length operator for caveats if the table is not a sequence.

Note: when using the pos parameter, value should not be nil. Attempting to insert an explicit nil value into the middle of a table will result in undefined behaviour, which may delete elements in the table unpredictably.

table.maxn

table.maxn( table )

Returns the largest positive numerical index of the given table, or zero if the table has no positive numerical indices.

To do this, it iterates over the whole table. This is roughly equivalent to

function table.maxn( table )
    local maxn, k = 0, nil
    repeat
        k = next( table, k )
        if type( k ) == 'number' and k > maxn then
            maxn = k
        end
    until not k
    return maxn
end

table.remove

table.remove( table, pos )

Removes from table the element at position pos, shifting down other elements to close the space, if necessary. Returns the value of the removed element. The default value for pos is the length of the table, so that a call table.remove( t ) removes the last element of table t.

Elements up to #table are shifted; see Length operator for caveats if the table is not a sequence.

table.sort

table.sort( table, comp )

Sorts table elements in a given order, in-place, from table[1] to table[#table].

If comp is given, then it must be a function that receives two table elements, and returns true when the first is less than the second (so that not comp(a[i+1],a[i]) will be true after the sort). If comp is not given, then the standard Lua operator < is used instead.

The sort algorithm is not stable; that is, elements considered equal by the given order may have their relative positions changed by the sort.

Scribuntoライブラリ

All Scribunto libraries are located in the table mw.

Base functions

mw.addWarning

mw.addWarning( text )

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

mw.allToString

mw.allToString( ... )

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

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.getCurrentFrame

mw.getCurrentFrame()

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

mw.incrementExpensiveFunctionCount

mw.incrementExpensiveFunctionCount()

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

mw.isSubsting

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

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.

mw.loadJsonData

mw.loadJsonData( page )

This is the same as mw.loadData() above, except it loads data from JSON pages rather than Lua tables. The JSON content must be an array or object. mw.text.jsonDecode() も参照してください。

mw.dumpObject

mw.dumpObject( object )

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

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.

mw.logObject

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

The frame object is the interface to the parameters passed to {{#invoke:}}, 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 {{#invoke:}}, and can also be obtained from mw.getCurrentFrame().

frame.args

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

{{#invoke:module|function|arg1|arg2|name=arg3}}

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: {{#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 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 ‎<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:callParserFunction

• 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:

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

-- {{#tag: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', args = { 'nowiki', 'some text' } }

-- {{#tag:ref|some text|name=foo|group=bar}}
frame:callParserFunction( '#tag', { 'ref',
    '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

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

Note the use of named arguments.

This is equivalent to a call to frame:callParserFunction() with function name 'msg' (see Help:Magic words#Transclusion modifiers) and with title prepended to args.

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 = { '|' } }
frame:callParserFunction{ 'msg', { 'template', '|' } }

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

frame:extensionTag

• 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' (see Help:Magic_words#Miscellaneous) and with name and content prepended to args.

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

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

frame:getParent

frame:getParent()

Called on the frame created by {{#invoke:}}, returns the frame for the page that called {{#invoke:}}. Called on that frame, returns nil.

For instance, if the template {{Example}} contains the code {{#invoke:ModuleName|FunctionName|A|B}}, and a page transcludes that template with the code {{Example|C|D}}, 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

frame:getTitle()

Returns the title associated with the frame as a string. For the frame created by {{#invoke:}}, this is the title of the module invoked.

frame:newChild

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 modules that call other modules whose name is defined by the caller (e.g. {{#invoke:params|concat_and_invoke}}), or in the debug console for testing functions that would normally be called by {{#invoke:}}. The number of frames that may be created at any one time is limited.

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, and returns the expanded text. 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.

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

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.

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 }

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

frame:argumentPairs()

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

Hash library

mw.hash.hashValue

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

mw.hash.listAlgorithms()

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

HTMLライブラリ

mw.html is a fluent interface for building complex HTML from Lua. On many Wikimedia wikis this was formerly implemented in Module:HtmlBuilder. A mw.html object can be created using mw.html.create.

関数が mw.html.name として文書化されている場合、グローバルな mw.html テーブルで利用可能です。一方、関数が mw.html:name や html:name として文書化されている場合、それらは mw.html オブジェクト (mw.html.create を参照) のメソッドとして利用可能です。

基本的な例は次のとおりです。

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 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

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

html:wikitext( ... )

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

Note that this stops at the first nil item.

Basic wikitext will get parsed, like HTML, links, bold, lists or tables. However, templates and parser functions won't be evaluated if they are passed directly to this function, unless they came from template parameters. Those will be rendered in plain text instead. To evaluate them, they'll have to be passed through frame:preprocess.

mw.html:newline

html:newline()

Appends a newline to the mw.html object. Useful when used before and after mw.html:wikitext(), when the wikitext contains lists or tables, whose syntax only has a special meaning when present at the start of a line.

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

Note that contrarily to other methods such as html:node(), this method doesn't return the current mw.html instance, but the mw.html instance of the newly inserted tag. Make sure to use html:done() to go up to the parent mw.html instance, or html:allDone() if you have nested tags on several levels.

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. 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

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. If a nil parameter is passed, this is a no-op.

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. 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

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

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.

Language library

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

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

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 (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

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

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

mw.language.getFallbacksFor

Fallback chains

mw.language.getFallbacksFor( code )

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

mw.language.isKnownLanguageTag

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

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

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

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

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 of 200 on the number of distinct language codes that may be used on a page. Exceeding this limit will result in errors.

mw.language:getCode

lang:getCode()

Returns the language code for this language object.

mw.language:toBcp47Code

lang:toBcp47Code()

Returns the standard BCP-47 language code for this language object. This is the code string which is appropriate to use in HTML, for example as the value of a lang attribute.

mw.language:getFallbackLanguages

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

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 )
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

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 {{#time:\n}}.
lang:formatDate( '\n' )

-- This is equivalent to {{#time:\n}}, not {{#time:\\n}}.
lang:formatDate( '\\n' )

-- This is equivalent to {{#time:\\n}}, not {{#time:\\\\n}}.
lang:formatDate( '\\\\n' )

mw.language:formatDuration

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

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

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

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

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

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

lang:getDir()

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

mw.language:getDirMark

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

lang:getDirMarkEntity( opposite )

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

mw.language:getDurationIntervals

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

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

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

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

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

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 "-".

Site library

mw.site.currentVersion

A string holding the current version of MediaWiki.

mw.site.scriptPath

The value of $wgScriptPath .

mw.site.server

The value of $wgServer .

mw.site.siteName

The value of $wgSitename .

mw.site.stylePath

The value of $wgStylePath .

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: 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.
• 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 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

mw.site.stats.pagesInNamespace( 名前空間 )

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

mw.site.stats.usersInGroup

mw.site.stats.usersInGroup( グループ )

Returns the number of users in the given group.

mw.site.interwikiMap

mw.site.interwikiMap( フィルター )

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

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( string )
mw.text.decode( string, 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   (the non-breaking space, U+00A0). Otherwise, the list of HTML5 named entities to recognize is loaded from PHP's get_html_translation_table function.

Known bugs: Approximately 600 of around 2,200 named entities in the HTML5 standard do not get decoded, even when decodeNamedEntities is used; this includes approximately 40 of around 250 entities which are also included in HTML4. This occurs because PHP's get_html_translation_table function returns only one mapping for each character, so for example → is not decoded since PHP returns only → as the mapping for →.

mw.text.encode

mw.text.encode( string )
mw.text.encode( string, charset )

Replaces characters in a string with HTML entities. Five characters are replaced with the appropriate named entities: <, >, &, " and the non-breaking space (U+00A0). 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 contains six characters: <, >, &, ", ' and the non-breaking space (U+00A0).

mw.text.jsonDecode

mw.text.jsonDecode( string )
mw.text.jsonDecode( string, 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

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

mw.text.killMarkers( string )

Removes all MediaWiki strip markers from a string.

mw.text.listToText

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

mw.text.nowiki( string )

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( string, 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, string will be split into individual characters.

Note that this function can be over 60 times slower than a reimplementation that is not Unicode-aware, such as the following:

function split(text, pattern, plain)
    local ret = {}
    local s, l = 1, string.len( text )
    while s do
    	local e, n = string.find( text, pattern, s, plain )
    	if not e then
    		ret[#ret+1] = string.sub ( text, s )
    		s = nil
    	elseif n < e then
    		-- Empty separator!
    		ret[#ret+1] = string.sub ( text, s, e )
    		if e < l then
    			s = e + 1
    		else
    			s = nil
    		end
    	else
    		ret[#ret+1] = e > s and string.sub( text, s, e - 1 ) or ''
    		s = n + 1
    	end
    end
    return ret
end

mw.text.gsplit

mw.text.gsplit( string, pattern, plain )

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

Note that this function can be over 60 times slower than a reimplementation that is not Unicode-aware, such as the following:

function gsplit( text, pattern, plain )
	local s, l = 1, string.len( text )
	return function ()
		if s then
			local e, n = string.find( text, pattern, s, plain )
			local ret
			if not e then
				ret = string.sub( text, s )
				s = nil
			elseif n < e then
				-- Empty separator!
				ret = string.sub( text, s, e )
				if e < l then
					s = e + 1
				else
					s = nil
				end
			else
				ret = e > s and string.sub( text, s, e - 1 ) or ''
				s = n + 1
			end
			return ret
		end
	end, nil, nil
end

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( string )
mw.text.trim( string, 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, %s, which is equivalent to "\t\r\n\f\v ".

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 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

mw.text.unstripNoWiki( string )

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

mw.text.unstrip

mw.text.unstrip( string )

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

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

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.

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

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 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

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.

Note also that functionality for interwiki titles is limited to interwiki / isExternal / isLocal and URL-related methods; other methods might not behave as expected.

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.

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.

• talkNsText: The text of the talk namespace for the page, or nil if this title cannot have a talk page. (added in MediaWiki 1.42.0-wmf.15, refs T180911)

• 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.

• categories: (since v1.43.0-wmf.18) The list of categories used on the page. 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.

• content or getContent(): Returns the (unparsed) content of the page, or nil if there is no page. The page will be recorded as a transclusion.

• pageLang: A language object for the title's page content language, which defaults to the wiki's content language. This is expensive.

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

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 file or fileExists fields records it as a "ファイルへのリンク".

File metadata

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

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

mw.uri.encode

mw.uri.encode( string, 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

mw.uri.decode( string, 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( string )

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, 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

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( string )

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( string )

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 length of a pattern, in bytes.

mw.ustring.maxStringLength

The maximum allowed length 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 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.

local value = mw.ustring.char( 0x41f, 0x440, 0x438, 0x432, 0x435, 0x442, 0x21 ) -- value is now 'Привет!'

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.

Known bug - When used with a pattern which can match the empty string, the function will get stuck in an infinite loop. For example, the following loop never terminates:

for capture in mw.ustring.gmatch( "foo bar", ".*" ) do
     -- block
end

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.

Known bugs: When repl is a table, it is possible to use numbers as keys instead of strings (e.g. to replace instances of "5" in a string, the value at key [5] or ["5"] would be used); as such, the output is not predictable if they have different (non-nil) values.

This is not an issue for string.gsub(), which ignores any numbers as keys.

mw.ustring.isutf8

mw.ustring.isutf8( string )

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

mw.ustring.len

mw.ustring.len( string )

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

mw.ustring.lower( string )

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( string, 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( string )

Converts the string to Normalization Form C (also known as Normalization Form Canonical Composition). Returns nil if the string is not valid UTF-8.

mw.ustring.toNFD

mw.ustring.toNFD( s )

Converts the string to Normalization Form D (also known as Normalization Form Canonical Decomposition). Returns nil if the string is not valid UTF-8.

mw.ustring.toNFKC

mw.ustring.toNFKC( s )

Converts the string to Normalization Form KC (also known as Normalization Form Compatibility Composition). Returns nil if the string is not valid UTF-8.

mw.ustring.toNFKD

mw.ustring.toNFKD( s )

Converts the string to Normalization Form KD (also known as Normalization Form Compatibility Decomposition). 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 "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, %W および %X 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.

Known limitations: Unlike String library patterns, Ustring library patterns have a maximum length of 10,000 bytes. If the pattern exceeds this length, then the Ustring function will throw an error. Because the String library has its own maximum of 32 captures (unlike the Ustring library), it is therefore impossible to use a pattern which exceeds both limits, as it will be incompatible with both libraries.

Note: 9 ASCII characters, $, +, <, =, >, ^, `, |, ~, can be matched by %p in the string library but not in the ustring library, as Unicode classifies them as Symbols rather than Punctuation.

Loadable libraries

These libraries are not included by default, but if needed may be loaded using require().

bit32

This emulation of the Lua 5.2 bit32 library may be loaded using:

 bit32 = require( 'bit32' )

The bit32 library provides bitwise operations on unsigned 32-bit integers. Input numbers are truncated to integers (in an unspecified manner) and reduced modulo 2³² so the value is in the range 0 to 2³²−1; return values are also in this range.

When bits are numbered (as in bit32.extract()), 0 is the least-significant bit (the one with value 2⁰) and 31 is the most-significant (the one with value 2³¹).

bit32.band

bit32.band( ... )

Returns the bitwise AND of its arguments: the result has a bit set only if that bit is set in all of the arguments.

If given zero arguments, the result has all bits set.

bit32.bnot

bit32.bnot( x )

Returns the bitwise complement of x.

bit32.bor

bit32.bor( ... )

Returns the bitwise OR of its arguments: the result has a bit set if that bit is set in any of the arguments.

If given zero arguments, the result has all bits clear.

bit32.btest

bit32.btest( ... )

Equivalent to bit32.band( ... ) ~= 0

bit32.bxor

bit32.bxor( ... )

Returns the bitwise XOR of its arguments: the result has a bit set if that bit is set in an odd number of the arguments.

If given zero arguments, the result has all bits clear.

bit32.extract

bit32.extract( n, field, width )

Extracts width bits from n, starting with bit field. Accessing bits outside of the range 0 to 31 is an error.

If not specified, the default for width is 1.

bit32.replace

bit32.replace( n, v, field, width )

Replaces width bits in n, starting with bit field, with the low width bits from v. Accessing bits outside of the range 0 to 31 is an error.

If not specified, the default for width is 1.

bit32.lshift

bit32.lshift( n, disp )

Returns the number n shifted disp bits to the left. This is a logical shift: inserted bits are 0. This is generally equivalent to multiplying by 2^disp.

Note that a displacement over 31 will result in 0.

bit32.rshift

bit32.rshift( n, disp )

Returns the number n shifted disp bits to the right. This is a logical shift: inserted bits are 0. This is generally equivalent to dividing by 2^disp.

Note that a displacement over 31 will result in 0.

bit32.arshift

bit32.arshift( n, disp )

Returns the number n shifted disp bits to the right. This is an arithmetic shift: if disp is positive, the inserted bits will be the same as bit 31 in the original number.

Note that a displacement over 31 will result in 0 or 4294967295.

bit32.lrotate

bit32.lrotate( n, disp )

Returns the number n rotated disp bits to the left.

Note that rotations are equivalent modulo 32: a rotation of 32 is the same as a rotation of 0, 33 is the same as 1, and so on.

bit32.rrotate

bit32.rrotate( n, disp )

Returns the number n rotated disp bits to the right.

Note that rotations are equivalent modulo 32: a rotation of 32 is the same as a rotation of 0, 33 is the same as 1, and so on.

libraryUtil

This library contains methods useful when implementing Scribunto libraries. It may be loaded using:

 libraryUtil = require( 'libraryUtil' )

libraryUtil.checkType

libraryUtil.checkType( name, argIdx, arg, expectType, nilOk )

Raises an error if type( arg ) does not match expectType. In addition, no error will be raised if arg is nil and nilOk is true.

name is the name of the calling function, and argIdx is the position of the argument in the argument list. These are used in formatting the error message.

libraryUtil.checkTypeMulti

libraryUtil.checkTypeMulti( name, argIdx, arg, expectTypes )

Raises an error if type( arg ) does not match any of the strings in the array expectTypes.

This is for arguments that have more than one valid type.

libraryUtil.checkTypeForIndex

libraryUtil.checkTypeForIndex( index, value, expectType )

Raises an error if type( value ) does not match expectType.

This is intended for use in implementing a __newindex metamethod.

libraryUtil.checkTypeForNamedArg

libraryUtil.checkTypeForNamedArg( name, argName, arg, expectType, nilOk )

Raises an error if type( arg ) does not match expectType. In addition, no error will be raised if arg is nil and nilOk is true.

This is intended to be used as an equivalent to libraryUtil.checkType() in methods called using Lua's "named argument" syntax, func{ name = value }.

libraryUtil.makeCheckSelfFunction

libraryUtil.makeCheckSelfFunction( libraryName, varName, selfObj, selfObjDesc )

This is intended for use in implementing "methods" on object tables that are intended to be called with the obj:method() syntax. It returns a function that should be called at the top of these methods with the self argument and the method name, which will raise an error if that self object is not selfObj.

This function will generally be used in a library's constructor function, something like this:

 function myLibrary.new()
     local obj = {}
     local checkSelf = libraryUtil.makeCheckSelfFunction( 'myLibrary', 'obj', obj, 'myLibrary object' )
 
     function obj:method()
         checkSelf( self, 'method' )
     end
 
     function obj:method2()
         checkSelf( self, 'method2' )
     end
 
     return obj
 end

luabit

The luabit library modules "bit" and "hex" may be loaded using:

 bit = require( 'luabit.bit' )
 hex = require( 'luabit.hex' )

Note that the bit32 library contains the same operations as "luabit.bit", and the operations in "luabit.hex" may be performed using string.format() and tonumber().

The luabit module "noki" is not available, as it is entirely useless in Scribunto. The luabit module "utf8" is also not available, as it was considered redundant to the Ustring library.

strict

The strict library is not a normal library; it causes an error to be raised whenever a new variable is used that is not explicitly scoped as a local variable (e.g., global variable assignment references). This functionality is typically enabled by loading at the top of a module using:

 require( 'strict' )

On many Wikimedia wikis this was formerly implemented in Module:No globals, which was replaced via phab:T209310. It is in part derived from strict.lua.

ustring

The pure-Lua backend to the Ustring library may be loaded using:

 ustring = require( 'ustring' )

In all cases the Ustring library (mw.ustring) should be used instead, as that replaces many of the slower and more memory-intensive operations with callbacks into PHP code.

拡張機能ライブラリ

Some MediaWiki extensions provide additional Scribunto libraries. These are also located in the table mw, usually in the table mw.ext, however, they are only present when certain extensions are installed (in addition to the Scribunto extension itself).

Such extensions use Scribunto provided hooks:

• ScribuntoExternalLibraries
• ScribuntoExternalLibraryPaths

Writing Scribunto libraries provides information on how such libraries can be developed to provide Lua interfaces for MediaWiki extensions.

mw.wikibase

Wikibase Client provides access to localizable structured data, most notably Wikidata. See docs_topics_lua.html and Extension:Wikibase Client/Lua .

mw.wikibase.lexeme

WikibaseLexeme provides access to Wikibase Lexeme entities. This is supported by Wikidata:Lexicographical data. See md_docs_2topics_2lua.html and Extension:WikibaseLexeme/Lua .

mw.wikibase.mediainfo

WikibaseMediaInfo provides access to Wikibase MediaInfo entities. WikibaseMediaInfo/Lua を参照してください。 This is supported by Structured Data on Commons. See Structured data/Lua.

mw.bcmath

BCmath provides arbitrary-precision arithmetic to Lua modules. See BCmath documentation via "LDoc" link at BCmath § Usage.

mw.smw

Semantic Scribunto provides native Scribunto support for the Semantic MediaWiki extension.

mw.ext.data

JsonConfig provides access to localizable tabular and map data. See JsonConfig/Tabular . Tabular Data and GeoJSON 地図データ is supported in the "Data:" namespace at Commons.

• mw.ext.data.get( pagename )

mw.ext.cargo

Cargo provides a means to query its data store from Lua. See Extension:Cargo/Other features#Lua support .

mw.ext.cattools

CategoryToolbox provides a means to check from Lua if a certain page belongs to a category. Is is experimental and not enabled on public Wikimedia wikis.

mw.ext.FlaggedRevs

FlaggedRevs provides a means to access the stability settings of a page from Lua.

mw.ext.TitleBlacklist

TitleBlacklist provides a means to test and obtain information about blacklisted page naming entries from Lua.

mw.ext.ParserFunctions

ParserFunctions provides a means from Lua to evaluate expressions in the same way as its PHP-based parser function #expr .

mw.ext.proofreadPage

Proofread Page provides access to Index and Page namespaces. Extension:Proofread Page/Lua reference を参照してください。 This is supported by Wikisource:ProofreadPage. Help:Extension:ProofreadPage を参照してください。

mw.ext.articlePlaceholder

ArticlePlaceholder provides a means to override default Wikibase renderings from Lua. Extension:ArticlePlaceholder/Module:AboutTopic を参照してください。

mw.ext.externalData

ExternalData provides a means to get structured data from Internet from Lua. Extension:External Data/Lua を参照してください。

mw.ext.UnlinkedWikibase

UnlinkedWikibase を参照してください。

• mw.ext.UnlinkedWikibase.getEntity( id )
• mw.ext.UnlinkedWikibase.query( sparql )

mw.ext.seo

WikiSEO provides a means to set SEO Data for the current page. See Extension:WikiSEO#Usage in lua modules.

mw.slots

WSSlots provides a number of Lua functions for working with MCR slots:

• mw.slots.slotContent(slotName, pageName)
• mw.slots.slotTemplates(slotName, pageName) (deprecated)
• mw.slots.slotContentModel(slotName, pageName)
• mw.slots.slotData(slotName, pageName)

標準のLuaとの差分

変更された関数

以下の関数は改造されました。

setfenv()

getfenv()

May not be available, depending on the configuration. If available, attempts to access parent environments will fail.

getmetatable()

Works on tables only to prevent unauthorized access to parent environments.

tostring()

Pointer addresses of tables and functions are not provided. This is to make memory corruption vulnerabilities more difficult to exploit.

pairs()

ipairs()

Support for the __pairs and __ipairs metamethods (added in Lua 5.2) has been added.

pcall()

xpcall()

Certain internal errors cannot be intercepted.

require()

Can fetch certain built-in modules distributed with Scribunto, as well as modules present in the Module namespace of the wiki. To fetch wiki modules, use the full page name including the namespace. Cannot otherwise access the local filesystem.

削除された関数とパッケージ

以下のパッケージはほとんど削除されました。リストされている関数のみが利用可能です。

package.*

Filesystem and C library access has been removed. Available functions and tables are:

package.loaded

package.preload

package.loaders

Loaders which access the local filesystem or load C libraries are not present. A loader for Module-namespace pages is added.

package.seeall()

os.*

There are some insecure functions in here, such as os.execute(), which can't be allowed. Available functions are:

os.clock()

os.date()

os.difftime()

os.time()

debug.*

Most of the functions are insecure. Available functions are:

debug.traceback()

以下の関数とパッケージは利用できません。

collectgarbage()

module()

coroutine.*

No application is known for us, so it has not been reviewed for security.

dofile()

loadfile()

io.*, file.*

Allows local filesystem access, which is insecure.

load()

loadstring()

These were omitted to allow for static analysis of the Lua source code. Also, allowing these would allow Lua code to be added directly to article and template pages, which was not desired for usability reasons.

print()

This was discussed on wikitech-l and it was decided that it should be omitted in favour of return values, to improve code quality. If necessary, mw.log() may be used to output information to the debug console.

string.dump()

May expose private data from parent environments.

Additional caveats

Referential data structures

Circular data structures and data structures where the same node may be reached by more than one path cannot be correctly sent to PHP.

Attempting to do so will cause undefined behavior. This includes (but is not limited to) returning such data structures from the module called by {{#invoke:}} and passing such data structures as parameters to Scribunto library functions that are implemented as callbacks into PHP.
Such data structures may be used freely within Lua, including as the return values of modules loaded with mw.loadData().

Writing Scribunto libraries

This information is useful to developers writing additional Scribunto libraries, whether for inclusion in Scribunto itself or for providing an interface for their own extensions.

A Scribunto library will generally consist of five parts:

• The PHP portion of the library.
• The Lua portion of the library.
• The PHP portion of the test cases.
• The Lua portion of the test cases.
• The documentation.

Existing libraries serve as a good example.

Library

The PHP portion of the library is a class that must extend Scribunto_LuaLibraryBase. See the documentation for that class for implementation details. In the Scribunto extension, this file should be placed in engines/LuaCommon/NameLibrary.php, and a mapping added to Scribunto_LuaEngine::$libraryClasses. Other extensions should use the ScribuntoExternalLibraries hook. In either case, the key should match the Lua module name ("mw.name" for libraries in Scribunto, or "mw.ext.name" for extension libraries).

The Lua portion of the library sets up the table containing the functions that can be called from Lua modules. In the Scribunto extension, the file should be placed in engines/LuaCommon/lualib/mw.name.lua. This file should generally include boilerplate something like this:

local object = {}
local php

function object.setupInterface( options )
    -- Remove setup function
    object.setupInterface = nil

    -- Copy the PHP callbacks to a local variable, and remove the global
    php = mw_interface
    mw_interface = nil

    -- Do any other setup here

    -- Install into the mw global
    mw = mw or {}
    mw.ext = mw.ext or {}
    mw.ext.NAME = object

    -- Indicate that we're loaded
    package.loaded['mw.ext.NAME'] = object
end

return object

The module in engines/LuaCommon/lualib/libraryUtil.lua (load this with local util = require 'libraryUtil') contains some functions that may be helpful.

Be sure to run the Scribunto test cases with your library loaded, even if your library doesn't itself provide any test cases. The standard test cases include tests for things like libraries adding unexpected global variables. Also, if the library is loaded with PHP, any upvalues that its Lua functions have will not be reset between #invoke's. Care must be taken to ensure that modules can't abuse this to transfer information between #invoke's.

Test cases

The Scribunto extension includes a base class for test cases, Scribunto_LuaEngineTestBase, which will run the tests against both the LuaSandbox and LuaStandalone engines. The library's test case should extend this class, and should not override static function suite(). In the Scribunto extension, the test case should be in tests/engines/LuaCommon/NameLibraryTest.php and added to the array in ScribuntoHooks::unitTestsList() (in common/Hooks.php); extensions should add the test case in their own UnitTestsList hook function, probably conditional on whether $wgAutoloadClasses['Scribunto_LuaEngineTestBase'] is set.

Most of the time, all that is needed to make the test case is this:

class ClassNameTest extends Scribunto_LuaEngineTestBase {
    protected static $moduleName = 'ClassNameTest';

    function getTestModules() {
         return parent::getTestModules() + array(
             'ClassNameTest' => __DIR__ . '/ClassNameTests.lua';
         );
    }
}

This will load the file ClassNameTests.lua as if it were the page "Module:ClassNameTests", expecting it to return an object with the following properties:

• count: Integer, number of tests
• provide( n ): Function that returns three values: n, the name of test n, and a string that is the expected output for test n.
• run( n ): Function that runs test n and returns one string.

If getTestModules() is declared as shown, "Module:TestFramework" is available which provides many useful helper methods. If this is used, ClassNameTests.lua would look something like this:

local testframework = require 'Module:TestFramework'

return testframework.getTestProvider( {
    -- Tests go here
} )

Each test is itself a table, with the following properties:

• name: The name of the test.
• func: The function to execute.
• args: Optional table of arguments to pass to the function.
• expect: Results to expect.
• type: Optional "type" of the test, default is "Normal".

The type controls the format of expect and how func is called. Included types are:

• Normal: expect is a table of return values, or a string if the test should raise an error. func is simply called.
• Iterator: expect is a table of tables of return values. func is called as with an iterated for loop, and each iteration's return values are accumulated.
• ToString: Like "Normal", except each return value is passed through tostring().

Test cases in another extension

There are (at least) two ways to run PHPUnit tests:

1. Run phpunit against core, allowing the tests/phpunit/suites/ExtensionsTestSuite.php to find the extension's tests using the UnitTestsList hook.

If your extension's test class names all contain a unique component (e.g. the extension's name), the --filter option may be used to run only your extension's tests.

1. Run phpunit against the extension directory, where it will pick up any file ending in "Test.php".

Either of these will work fine if Scribunto is loaded in LocalSettings.php. And it is easy for method #1 to work if Scribunto is not loaded, as the UnitTestsList hook can easily be written to avoid returning the Scribunto test when $wgAutoloadClasses[ 'Scribunto_LuaEngineTestBase' ] is not set.

But Jenkins uses method #2. For Jenkins to properly run the tests, you will need to add Scribunto as a dependency for your extension. See Gerrit change 56570 for an example of how this is done.

If for some reason you need the tests to be able to run using method #2 without Scribunto loaded, one workaround is to add this check to the top of your unit test file:

 if ( !isset( $GLOBALS['wgAutoloadClasses']['Scribunto_LuaEngineTestBase'] ) ) {
     return;
 }

説明文書

Modules included in Scribunto should include documentation in the Scribunto libraries section above. Extension libraries should include documentation in a subpage of their own extension page, and link to that documentation from the Extension libraries subsection above.

関連項目

• jp:Lua

ライセンス

このマニュアルはMITライセンスの下で利用可能なLua 5.1 reference manualから派生したものです。

{{mbox | type = notice | image = none | text = Copyright © 1994–2012 Lua.org, PUC-Rio.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

この派生マニュアルは同ライセンスの使用条件に基いて複製することが可能です。