シグニチャの読み方
Mithrilは他のフレームワークのような具象クラスを提供していません。Mithrilでは与えられたシグニチャと一致するPlain Old JavaScript Object (POJO) を操作するメソッド群を提供しています。
シグニチャはそのPOJOの静的型を説明するためのものです。関数の場合はそのパラメータと、返り値、あとはそれぞれの型が該当します。オブジェクトや配列の場合は期待するデータ構造やメンバーおよび型です。
本ドキュメントにおけるメソッドシグニチャは、次に上げるようなJavaの文法にいくつか追加したような表記を使います:
返り値の型 メソッド名(パラメータ型1 パラメータ1, パラメータ型2 パラメータ2)
追加オプションのパラメータ
角括弧はオプションのパラメータを表します。次のサンプルでは, param2 and param3 can both be omitted, but passing a value to param2 is required if also passing a value to param3:
String test(String arg1 [, String arg2 [, String arg3]])
//正しい関数呼び出しのサンプル
test("first");
test("first", "second");
test("first", "second", "third");
型プレースホルダー
The word void is used as a type when a function does not return a value (i.e. undefined):
void test()
console.log(test()); // undefined
The word any is used as a type if there are no type restrictions on a parameter:
void test(any value)
//examples of valid function calls
test("hello");
test(1);
test(["hello", "world"]);
Arrays
Arrays use Generics syntax to denote the expected type of array members:
void test(Array<String> values)
//example of a valid function call
test(["first", "second"]);
Objects as Key-Value Maps
Objects also use Generics syntax when they are meant to be used as a key-value map. Keys are always strings and, in key-value maps, can have any name.
void test(Object<Number> values)
//example of a valid function call
test({first: 1, second: 2});
Objects as Class Interfaces
Objects that require specific keys are denoted using curly brace syntax:
void test(Object {String first, Number second} value)
//example of a valid function call
test({first: "first", second: 2});
Type Aliasing
Some types are aliases of more complex types. For example, in the example below, we created an alias called ComplexType for the type from the previous example
void test(ComplexType value)
where:
ComplexType :: Object {String first, Number second}
//example of a valid function call
test({first: "first", second: 2})
Mixin Types
Curly brace syntax can also appear on other base types to denote that the value contains static members. For example, in the example below, a value of type ComplexType is a string, but it also has a boolean property called flag:
ComplexType :: String { Boolean flag }
//an example
var a = aComplexTypeValue
typeof a == "string" // true
"flag" in a // true
a.flag = true
In the following example, a value of type ComplexType is a function, with a property called label
ComplexType :: void test() { String label }
//an example
var a = aComplexTypeValue
typeof a == "function" // true
"label" in a // true
a.label = "first"
Polymorphic Types
When multiple (but not all) types are accepted, the pipe | is used to delimit the list of valid types
void test(Children children, Value value)
where:
Children :: Array<String text | Number number>
Value :: String | Number
//examples of valid function calls
test(["test", 2], "second")
test([1, 2, 3], "second")
test([1, "test", 3], 2)
Pipe syntax within Object curly brace syntax means that, for a specific key, name has specific type requirements.
In the example below, the value parameter should be a key-value map. This map may contain a key called config, whose value should be a function.
void test(Object { any | void config(DOMElement) } value)
//example of a valid function call
test({ first: "first", config: function(element) { /*do stuff*/ } })
Nullable Types
A question mark ? after a type denotes that a value can be either of that type or undefined.
XMLHttpRequest? config()
In the example above, the config function is expected to return either an instance of the XMLHttpRequest object or undefined
Splat
An ellipsis ... means that an array argument can instead be a list of arguments
VirtualElement m(String selector [, Attributes attributes] [, Children... children])
In the example above, we can define children as an array:
m("div", {title: "foo"}, ["child 1", "child 2", "child 3"])
And we also define it as a list of arguments (note that lack of square brackets)
m("div", {title: "foo"}, "child 1", "child 2", "child 3")