「Dfinity」Candid常用文本语法指引

Why？

作为一名Dfinity Dapp后端开发者，我们在调试canister的时候经常会需要手动输入一些参数，但是经常会遇到输入格式不正确的情况，从而无法被canister正确获取。这个时候就需要看一下Candid文本语法的标准啦。

What？

PS:下文的类型均为candid定义的类型，虽然可以对应到Motoko的类型，但不是Motoko中的类型。

一、text类型

写法：

在text内容的两端用双引号括起来即可。

示例：

""
"Hello"
"Escaped characters: \n \r \t \\ \" \'"
"Unicode escapes: \u{2603} is ☃ and \u{221E} is ∞"
"Raw bytes (must be utf8): \E2\98\83 is also ☃"

二、blob类型

写法：

写成该形式：blob <text>，其中<text>部分是文本，内容是一系列utf8编码以及任意字符序列。

示例：

blob "\CA\FF\FE"

三、nat类型

写法：

直接书写即可。nat类型包含所有自然（非负）数字。它是无界的，可以表示任意的大数。on-wire编码是LEB128，因此小数字仍然可以高效表示。

示例：

1234
1_000_000
0xDEAD_BEEF

四、int类型

写法：

直接书写即可。整数类型包含所有整数。它是无界的，可以表示任意的小数或大数。on-wire编码是SLEB128，因此小数字仍然可以高效表示。

示例：

1234
-1234
+1234
1_000_000
-1_000_000
+1_000_000
0xDEAD_BEEF
-0xDEAD_BEEF
+0xDEAD_BEEF

五、natN和intN类型

写法：

nat8、nat16、nat32、nat64、int8、int16、int32和int64表示表示这么多位的数字，并可用于更“低级”的界面。

natN的范围是{0…2^N-1}，intN的范围是-2^(N-1)…2^(N-1)-1。

on-wire表示正好有那么多位长。因此，对于小值，nat比nat64更节省空间。

nat8、nat16、nat32、nat64与nat的文本语法相同。

int8、int16、int32、int64与int的文本语法相同。

我们可以使用类型注释来区分不同的整数类型。

Length	Signed	Unsigned
8-bit	i8	u8
16-bit	i16	u16
32-bit	i32	u32
64-bit	i64	u64

示例：

100 : nat8
-100 : int8
(42 : nat64)

六、float32和float64类型

写法：

float32和float64类型以单精度（32位）和双精度（64位）表示IEEE 754浮点数。

示例：

1245.678
+1245.678
-1_000_000.000_001
34e10
34E+10
34e-10
0xDEAD.BEEF
0xDEAD.BEEFP-10
0xDEAD.BEEFp+10

七、bool类型

写法：

直接书写即可。Bool类型是一种逻辑数据类型，只能具有true或假false值。

示例：

true
false

八、null类型

写法：

null类型是值null的类型，因此是所有opt t类型的子类型。使用variants构建枚举时，这也是惯用的选择。

示例：

null

九、vec t类型

写法：

书写形式：vet{1; 2; ...}

vec类型表示矢量（序列、列表、数组）。vec t类型的值包含零值或更多t类型的值序列。

在Motoko中代表[T]数组，在Rust中，vec record { KeyType; ValueType }还可以被“翻译”为BTreeMap和HashMap。

示例：

vec {}
vec { "john@doe.com"; "john.doe@example.com" };

十、opt t类型

写法：

书写形式：opt ... 或 null

opt类型可以嵌套（例如，opt opt text），值null和option null是不同的值。

示例：

null
opt true
opt 8
opt null
opt opt "test"

十一、record类型

写法：

书写形式：record{1; 2; ...}（元组） 或 record{n=t; ...}

PS:元组(tuple)类型是record类型的子类型。

示例：

record {}
record { first_name = "John"; second_name = "Doe" }
record { "name with spaces" = 42; "unicode, too: ☃" = true }
record { "a"; "tuple"; null }

十二、variant类型

写法：

书写形式：variant{n=t; ...}或variant{n1; n2}

示例：

variant { ok = 42 }
variant { "unicode, too: ☃" = true }
variant { fall }

十三、func(...) -> (...)类型

写法：

Candid旨在支持高阶用例，例如，服务可能会接收或提供对其他服务或其方法的引用，例如回调。Func类型是其中的核心：它表示函数的签名（参数和结果类型、注释），此类值是对具有该签名的函数的引用。

示例：

func "w7x7r-cok77-xa".hello
func "w7x7r-cok77-xa"."☃"
func "aaaaa-aa".create_canister

十四、service{...}类型

写法：

服务可能不仅要传递对单个函数（使用函数类型）的引用，还要传递对整个服务的引用。在这种情况下，Candid类型可用于声明此类服务的完整接口。

示例：

service "w7x7r-cok77-xa"
service "zwigo-aiaaa-aaaaa-qaa3a-cai"
service "aaaaa-aa"

十五、principal类型

写法：

书写形式：principal "..."

示例：

principal "w7x7r-cok77-xa"
principal "zwigo-aiaaa-aaaaa-qaa3a-cai"
principal "aaaaa-aa"