数据模板和NBT相关

Author: Alumopper

docs/en/quickstart/02base/01variables.md

@@ -2,9 +2,9 @@
 lastUpdated: true
 ---
 
-# Variable 
+# Variable
 
-## Declaration of variables 
+## Declaration of variables
 
 Same as other languages, you can declare some variables in MCFPP for store, transfer and process data.
 

docs/en/quickstart/08template/01define-and-instantiate.md renamed to docs/en/quickstart/10template/01define-and-instantiate.md

@@ -0,0 +1,69 @@
+---
+lastUpdate: true
+---
+
+# NBT
+
+在Minecraft中，NBT最重要的数据类型之一。NBT作为一种树状结构的数据类型，可以存储各种各样的数据，例如整数、浮点数、字符串、数组、列表、复合数据等。在MCFPP中，NBT是一种内置的数据类型，可以直接使用。
+
+## NBT数据类型的基本使用
+
+在MCFPP中，NBT数据类型的类型标识符为`nbt`。你可以使用一般的SNBT语法来创建NBT数据，例如：
+
+```mcfpp
+nbt value1 = "Hello, World!";
+
+nbt number = 42;
+
+nbt list = [1,2,3];
+
+nbt uuid = [I;0,0,0,1]
+
+nbt itemStack = {
+    "Count": 1,
+    "Item": "minecraft:stone",
+    "tag": {
+        "display": {
+            "Name": "Stone"
+        }
+    }
+};
+```
+
+你可以使用`[]`索引来访问复杂NBT数据中的成员。例如：
+
+```mcfpp
+nbt itemStack = {
+    "Count": 1,
+    "Item": "minecraft:stone",
+    "tag": {
+        "display": {
+            "Name": "Stone"
+        }
+    }
+};
+
+print(itemStack["tag"]["display"]["Name"]);
+
+nbt list = [1,2,3];
+
+print(list[0]);
+```
+
+编译器不会检查索引是否合法。即使索引对应的数据不存在，编译器也将正常拼接NBT路径。在后续的`list`,`dict`,`map`类型中，也是同理的。
+
+除了一种情况，就是编译器知道这个nbt类型的值。此时nbt将会尝试检查数据是否合法，但是并不会报错，而是会给出警告。数据包依然会正常生成。
+
+## NBT数据类型的转换
+
+在MCFPP中，任何数据类型都能被转换为NBT。但是NBT并不能转换为任何数据类型。在编译过程中，编译器会尝试跟踪nbt变量的NBT类型，并由此判断是否能够转换为其他数据类型。
+
+```mcfpp
+int i = 5;
+nbt n = i;  #合法，隐式转换永远成功
+int p = (int)n; #合法，编译器已知n是一个int类型的NBT数据
+
+func test(nbt n){
+    int i = (int)n; #非法，编译器无法确定作为函数参数传入的n是否为int类型的数据
+}
+```

docs/en/quickstart/08template/02template-parameters.md renamed to docs/en/quickstart/10template/02template-parameters.md

@@ -0,0 +1,59 @@
+---
+lastUpdate: true
+---
+
+# 列表
+
+NBT支持列表这种基本数据类型，MCFPP将其抽象了出来，作为一种单独的类型提供。
+
+## 基本使用
+
+使用`list<type T>`类型标识符定义一个列表。其中类型参数`T`表示这个列表中存储的元素类型。
+
+```mcfpp
+list<int> l = []; #创建一个空列表
+l.add(1); #向列表中添加一个元素
+l.add(2); 
+l.add(3); 
+print(l); #输出[1,2,3]
+print(l[0]);    #输出1
+
+l.removeAt(1); #从列表中移除索引为1的元素
+```
+
+列表的传递为值传递，而不是引用传递。事实上，所有基于纯NBT的数据类型都是值传递。
+
+```mcfpp
+
+list<int> l = [1,2,3];
+list<int> l2 = l;
+l2.add(4);
+print(l); #输出[1,2,3]
+print(l2); #输出[1,2,3,4]
+```
+
+## 列表的操作
+
+MCFPP标准库提供了一系列的列表操作函数。
+
+| 函数名 | 参数 | 返回值 | 作用 |
+| --- | --- | --- | --- |
+| `add` | `T element` | `void` | 向列表中添加一个元素 |
+| `addAll` | `list<T> elements` | `void` | 向列表中添加一组元素 |
+| `insert` | `int index, T element` | `void` | 在指定位置插入一个元素 |
+| `removeAt` | `int index` | `void` | 移除指定位置的元素 |
+| `indexOf` | `T element` | `int` | 返回指定元素的索引 |
+| `lastIndexOf` | `T element` | `int` | 返回指定元素的最后一个索引 |
+| `contains` | `T element` | `bool` | 判断列表中是否包含指定元素 |
+| `clear` | `void` | `void` | 清空列表 |
+
+## 列表的遍历<Badge type="tip" text="未来特性" />
+
+使用`foreach`循环可以简单地遍历列表中的所有元素。
+
+```mcfpp
+list<int> l = [1,2,3];
+foreach(i in l){
+    print(i);
+}
+```

docs/en/quickstart/10mni/01mni-framework.md renamed to docs/en/quickstart/11mni/01mni-framework.md

@@ -0,0 +1,48 @@
+---
+lastUpdate: true
+---
+
+# 字典
+
+字典类型对应MCFPP中的复合标签类型。它是一个键值对的集合，键必须为字符串类型，而值可以是任意类型。
+
+## 基本使用
+
+使用`dict`类型标识符定义字典类型的变量。使用复合标签来为字典进行赋值。
+
+```mcfpp
+dict playerData = {
+    "Alumopper" : {
+        "level" : 1,
+        "exp" : 0
+    },
+    "Xiao2" : {
+        "level" : 2,
+        "exp" : 100
+    },
+    "CR_019" : {
+        "level" : 3,
+        "exp" : 200
+    }
+}
+
+print(playerData["Alumopper"]["level"]); #输出1
+
+print(playerData["CR_017"]);    #非法，但是不报错
+
+playerData["CR_017"] = {
+    "level" : 4,
+    "exp" : 300
+};  # 添加一个新的键值对
+
+```
+
+## 字典的操作
+
+字典不能被遍历，也不能获取关于键值的列表。MCFPP提供了一些基本的字典操作。
+
+| 函数名 | 参数 | 返回值 | 作用 |
+| --- | --- | --- | --- |
+| `containsKey` | `string key` | `bool` | 判断字典中是否包含指定键 |
+| `merge` | `dict dict` | `void` | 合并两个字典 |
+| `remove` | `string key` | `void` | 移除指定键的键值对 |

docs/en/quickstart/10mni/02mni-framework-implementation.md renamed to docs/en/quickstart/11mni/02mni-framework-implementation.md

@@ -0,0 +1,94 @@
+---
+lastUpdate: true
+---
+
+# MAP
+
+为了弥补Minecraft原版NBT中复合标签在操作上的不便利，MCFPP封装了一种新的数据结构：`map`。`map`是一种键值对的数据结构，它的键只能是字符串，而值只能是同一种类型。
+
+## 基本使用
+
+使用`map<type T>`来声明一个`map`。和`dict`一样，在`map`中，可以使用`[]`来访问键值对。
+
+```mcfpp
+map<int> m = {
+    "a": 1,
+    "b": 2,
+    "c": 3
+};
+
+print(m["a"]); #输出1
+
+m["d"] = 4; #添加一个新的键值对
+```
+
+## map的操作
+
+MCFPP标准库提供了一系列的`map`操作函数。
+
+| 函数名 | 参数 | 返回值 | 作用 |
+| --- | --- | --- | --- |
+| `clear` | `void` | `void` | 清空`map` |
+| `containsKey` | `string key` | `bool` | 判断`map`中是否包含指定键 |
+| `containsValue` | `T value` | `bool` | 判断`map`中是否包含指定值 |
+| `isEmpty` | `void` | `bool` | 判断`map`是否为空 |
+| `getKeys` | `void` | `list<string>` | 获取`map`中所有的键 |
+| `getValues` | `void` | `list<T>` | 获取`map`中所有的值 |
+| `remove` | `string key` | `void` | 移除指定键的键值对 |
+| `merge` | `map<T> map` | `void` | 合并两个`map` |
+| `size` | `void` | `int` | 获取`map`的大小 |
+
+## map的遍历<Badge type="tip" text="未来特性" />
+
+使用`foreach`循环可以简单地遍历`map`中的所有键值对。
+
+```mcfpp
+map<int> m = {
+    "a": 1,
+    "b": 2,
+    "c": 3
+};
+
+foreach(k, v in m){
+    print(k + ": " + v);
+}
+
+foreach(k in m.getKeys()){
+    print(k + ": " + m[k]);
+}
+
+foreach(v in m.getValues()){
+    print(v);
+}
+```
+
+:::tip Tip
+和`dict`仅由复合标签组成相比，`map`的结构更为复杂。通常来说，一个`map`由三个部分组成，即一个键的列表，一个值的列表，以及键值构成的复合标签。这种结构意味着，在写入的时候，`map`的开销将会比`dict`更高。但是这种结构同样也为`map`带来了更多的功能。
+
+具体来说，以下面的代码为例：
+
+```mcfpp
+map m = {};
+
+m["qwq"] = "pwp";
+m["owo"] = "uwu";
+m["nya"] = "meow";
+```
+
+在存储的时候，`map`的结构如下：
+
+```js
+namespace.stack_frame:[
+    {
+        m:{
+            key:["qwq","owo","nya"],        //键列表
+            value:["pwp","uwu","meow"],     //值列表
+            data:{
+                "qwq":"pwp","owo":"uwu","nya":"meow"    //键值对，相当于一个dict
+            }    
+        }
+    }
+]
+```
+
+:::

docs/en/quickstart/10mni/03javavar.md renamed to docs/en/quickstart/11mni/03javavar.md

@@ -0,0 +1,57 @@
+---
+lastUpdate: true
+---
+
+# 数据模板
+
+数据模板（Data Template）是一种类似于类的数据结构。数据模板完全基于NBT数据结构，但是和普通的NBT不同的是，数据模板规定了NBT的结构，或者说规定了NBT中有哪些成员，因此编译器能够在访问数据结构成员的时候进行检查。
+
+## 定义
+
+使用`data`关键字来定义一个数据模板。例如：
+
+```mcfpp
+# 定义
+data Test{
+    int a;  # 一个整数
+    nbt b;  # 任意的NBT值
+}
+
+func main(){
+    # 创建对象
+    Test t = Test();
+    t.a = 5;
+    t.b = {
+        "key": "value"
+    };
+
+    # 或者直接写入值
+    Test t2 = {
+        "a": 5,
+        "b": {
+            "key": "value"
+        }
+    };
+}
+```
+
+使用`.`来访问一个数据模板中的成员。
+
+```mcfpp
+print(t.a);
+print(t.b);
+```
+
+和类一样，你可以在数据模板中定义一些方法。
+
+```mcfpp
+data Test{
+    int a;
+    nbt b;
+
+    func print(){
+        print(this.a);
+        print(this.b);
+    }
+}
+```

docs/en/quickstart/11gradle/01gradle-configuration.md renamed to docs/en/quickstart/12gradle/01gradle-configuration.md

@@ -0,0 +1,43 @@
+---
+lastUpdate: true
+---
+
+# 数据模板的嵌套
+
+如果一个数据模板中，有另一个数据模板类型的变量作为成员，那么就可以实现数据模板的嵌套。
+
+## 基本使用
+
+```mcfpp
+data A{
+    int valueA;
+}
+
+data B{
+    int valueB;
+    A dataA;
+}
+
+func main(){
+    //创建对象
+    B b = B();
+    A a = A();
+    a.valueA = 5;
+    b.valueB = 5;
+    b.dataA = A();
+
+    //或者直接赋值
+    B qwq = {
+        "valueB": 5,
+        "dataA": {
+            "valueA": 5
+        }
+    };
+
+    //访问
+    print(b.valueB);
+    print(b.dataA.valueA);
+}
+```
+
+当然，使用自身类型作为数据模板的成员是不被允许的。