From 79178692abfeec5efb4d82734f09b22bf7c7a400 Mon Sep 17 00:00:00 2001 From: Alumopper <609255325@qq.com> Date: Tue, 28 May 2024 22:49:37 +0800 Subject: [PATCH] =?UTF-8?q?=E8=8B=B1=E6=96=87=E7=9B=AE=E5=BD=95=E6=A1=86?= =?UTF-8?q?=E6=9E=B6=E5=BB=BA=E7=AB=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/.vitepress/sidebar.ts | 86 +++++++++++ docs/en/index.md | 2 +- .../quickstart/01project/01create-project.md | 1 + docs/en/quickstart/01project/02config-file.md | 1 + .../02base/01variables.md} | 0 .../02base/02comments.md} | 0 .../quickstart/02base/03logic-statements.md | 103 +++++++++++++ docs/en/quickstart/02base/04top-statements.md | 27 ++++ docs/en/quickstart/03namespace/01namespace.md | 37 +++++ .../04function/01define-and-call.md | 65 ++++++++ .../quickstart/04function/02static-params.md | 19 +++ .../04function/03inline-function.md | 44 ++++++ .../04function/04compiletime-function.md | 0 .../05class/01define-and-instantiate.md | 58 +++++++ docs/en/quickstart/05class/02member.md | 74 +++++++++ .../05class/03inheritance-abstract.md | 49 ++++++ .../06interface/01define-and-implement.md | 53 +++++++ .../en/quickstart/07generic/01concrete_var.md | 30 ++++ .../07generic/02generic_function.md | 48 ++++++ .../quickstart/07generic/03generic_class.md | 68 +++++++++ .../08template/01define-and-instantiate.md | 3 + .../08template/02template-parameters.md | 1 + .../quickstart/09library/01import-and-use.md | 1 + .../quickstart/09library/02export-library.md | 1 + docs/en/quickstart/10mni/01mni-framework.md | 62 ++++++++ .../10mni/02mni-framework-implementation.md | 143 ++++++++++++++++++ docs/en/quickstart/10mni/03javavar.md | 51 +++++++ .../11gradle/01gradle-configuration.md | 0 docs/en/quickstart/index.md | 9 ++ docs/zh/quickstart/index.md | 9 -- 30 files changed, 1035 insertions(+), 10 deletions(-) create mode 100644 docs/en/quickstart/01project/01create-project.md create mode 100644 docs/en/quickstart/01project/02config-file.md rename docs/en/{02base-01variables.md => quickstart/02base/01variables.md} (100%) rename docs/en/{02base-02comments => quickstart/02base/02comments.md} (100%) create mode 100644 docs/en/quickstart/02base/03logic-statements.md create mode 100644 docs/en/quickstart/02base/04top-statements.md create mode 100644 docs/en/quickstart/03namespace/01namespace.md create mode 100644 docs/en/quickstart/04function/01define-and-call.md create mode 100644 docs/en/quickstart/04function/02static-params.md create mode 100644 docs/en/quickstart/04function/03inline-function.md create mode 100644 docs/en/quickstart/04function/04compiletime-function.md create mode 100644 docs/en/quickstart/05class/01define-and-instantiate.md create mode 100644 docs/en/quickstart/05class/02member.md create mode 100644 docs/en/quickstart/05class/03inheritance-abstract.md create mode 100644 docs/en/quickstart/06interface/01define-and-implement.md create mode 100644 docs/en/quickstart/07generic/01concrete_var.md create mode 100644 docs/en/quickstart/07generic/02generic_function.md create mode 100644 docs/en/quickstart/07generic/03generic_class.md create mode 100644 docs/en/quickstart/08template/01define-and-instantiate.md create mode 100644 docs/en/quickstart/08template/02template-parameters.md create mode 100644 docs/en/quickstart/09library/01import-and-use.md create mode 100644 docs/en/quickstart/09library/02export-library.md create mode 100644 docs/en/quickstart/10mni/01mni-framework.md create mode 100644 docs/en/quickstart/10mni/02mni-framework-implementation.md create mode 100644 docs/en/quickstart/10mni/03javavar.md create mode 100644 docs/en/quickstart/11gradle/01gradle-configuration.md create mode 100644 docs/en/quickstart/index.md delete mode 100644 docs/zh/quickstart/index.md diff --git a/docs/.vitepress/sidebar.ts b/docs/.vitepress/sidebar.ts index 82861d5..93a084d 100644 --- a/docs/.vitepress/sidebar.ts +++ b/docs/.vitepress/sidebar.ts @@ -52,6 +52,9 @@ export const sidebar : DefaultTheme.Sidebar = { { text: "泛型", items: [ + {"text": "编译确定量", link: "/zh/quickstart/07generic/01concrete_var"}, + {"text": "泛型函数", link: "/zh/quickstart/07generic/02generic_function"}, + {"text": "泛型类", link: "/zh/quickstart/07generic/03generic_class"} ] }, { @@ -82,5 +85,88 @@ export const sidebar : DefaultTheme.Sidebar = { { text: "Gradle配置和使用", link: "/zh/quickstart/11gradle/01gradle-configuration" } ] } + ], + "/en/quickstart/":[ + { + text: "Project Configure", + items: [ + { text: "Create Project", link: "/en/quickstart/01project/01create-project" }, + { text: "Configuration File", link: "/en/quickstart/01project/02config-file" } + ] + }, + { + text: "Basic Syntax", + items: [ + { text: "Variable", link: "/en/quickstart/02base/01variables" }, + { text: "Comments", link: "/en/quickstart/02base/02comments" }, + { text: "Logic Statement", link: "/en/quickstart/02base/03logic-statements" }, + { text: "Top Statement", link: "/en/quickstart/02base/04top-statements" } + ] + }, + { + text: "Namespace", + items: [ + { text: "Namespace", link: "/en/quickstart/03namespace/01namespace" } + ] + }, + { + text: "Function", + items: [ + { text: "Definition and Calling", link: "/en/quickstart/04function/01define-and-call" }, + { text: "Static Parameter", link: "/en/quickstart/04function/02static-params" }, + { text: "Inline Function", link: "/en/quickstart/04function/03inline-function" }, + { text: "Compile-time Function", link: "/en/quickstart/04function/04compiletime-function" } + ] + }, + { + text: "Class", + items: [ + { text: "Define and instantiate", link: "/en/quickstart/05class/01define-and-instantiate" }, + { text: "Class Field", link: "/en/quickstart/05class/02member" }, + { text: "Inheritance and Abstract", link: "/en/quickstart/05class/03inheritance-abstract" } + ] + }, + { + text: "Interface", + items: [ + { text: "Define and Implement", link: "/en/quickstart/06interface/01define-and-implement" } + ] + }, + { + text: "Generic", + items: [ + {"text": "Concrete Var", link: "/en/quickstart/07generic/01concrete_var"}, + {"text": "Generic Function", link: "/en/quickstart/07generic/02generic_function"}, + {"text": "Generic Class", link: "/en/quickstart/07generic/03generic_class"} + ] + }, + { + text: "Template", + items: [ + { text: "Define and instantiate", link: "/en/quickstart/08template/01define-and-instantiate" }, + { text: "Template Parameter", link: "/en/quickstart/08template/02template-parameters" } + ] + }, + { + text: "Libary", + items: [ + { text: "Import and Use", link: "/en/quickstart/09library/01import-and-use" }, + { text: "Export", link: "/en/quickstart/09library/02export-library" } + ] + }, + { + text: "MNI Framework", + items: [ + { text: "Introduce", link: "/en/quickstart/10mni/01mni-framework" }, + { text: "Implementation", link: "/en/quickstart/10mni/02mni-framework-implementation" }, + { text: "Use var and function in Java", link: "/en/quickstart/10mni/03javavar" }, + ] + }, + { + text: "Develop with Gradle", + items: [ + { text: "Configure and use gradle", link: "/en/quickstart/11gradle/01gradle-configuration" } + ] + } ] } diff --git a/docs/en/index.md b/docs/en/index.md index ed44907..5e36610 100644 --- a/docs/en/index.md +++ b/docs/en/index.md @@ -9,7 +9,7 @@ hero: actions: - theme: brand text: QuickStart - link: /zh/quickstart/index + link: /en/quickstart/index - theme: alt text: Overview link: /en/overview diff --git a/docs/en/quickstart/01project/01create-project.md b/docs/en/quickstart/01project/01create-project.md new file mode 100644 index 0000000..30404ce --- /dev/null +++ b/docs/en/quickstart/01project/01create-project.md @@ -0,0 +1 @@ +TODO \ No newline at end of file diff --git a/docs/en/quickstart/01project/02config-file.md b/docs/en/quickstart/01project/02config-file.md new file mode 100644 index 0000000..30404ce --- /dev/null +++ b/docs/en/quickstart/01project/02config-file.md @@ -0,0 +1 @@ +TODO \ No newline at end of file diff --git a/docs/en/02base-01variables.md b/docs/en/quickstart/02base/01variables.md similarity index 100% rename from docs/en/02base-01variables.md rename to docs/en/quickstart/02base/01variables.md diff --git a/docs/en/02base-02comments b/docs/en/quickstart/02base/02comments.md similarity index 100% rename from docs/en/02base-02comments rename to docs/en/quickstart/02base/02comments.md diff --git a/docs/en/quickstart/02base/03logic-statements.md b/docs/en/quickstart/02base/03logic-statements.md new file mode 100644 index 0000000..140ec9d --- /dev/null +++ b/docs/en/quickstart/02base/03logic-statements.md @@ -0,0 +1,103 @@ +--- +lastUpdated: true +--- + +# 逻辑语句 + +::: tip +MCFPP中的逻辑语句和C/Java中的逻辑语句完全一致。如果你对其他语言足够熟悉，你可以跳过这一节。 +::: + +## if语句 + +`if`语句是一种条件语句，它用来判断一个条件是否成立。如果条件成立，那么`if`语句中的代码块将会被执行。`if`语句的语法如下： + +```mcfpp +if (condition){ + #code +} +``` + +`condition`是一个布尔表达式，它的值为`true`或`false`。如果`condition`的值为`true`，那么`#code`中的代码块将会被执行。 + +`if`语句还可以和`else`语句一起使用，`else`语句用来在`if`语句的条件不成立时执行代码块。`if-else`语句的语法如下： + +```mcfpp +if (condition){ + #code1 +}else{ + #code2 +} +``` + +`condition`是一个布尔表达式，它的值为`true`或`false`。如果`condition`的值为`true`，那么`#code1`中的代码块将会被执行；否则，`#code2`中的代码块将会被执行。 + +可以使用`else if`语句用来在`if`语句的条件不成立时判断另一个条件。`if-else if-else`语句的语法如下： + +```mcfpp +if (condition1){ + #code1 +}else if (condition2){ + #code2 +}else{ + #code3 +} +``` + +## while语句和do-while语句 + +`while`语句是一种循环语句，它用来重复执行一个代码块，直到条件不成立。`while`语句的语法如下： + +```mcfpp +while (condition){ + #code +} +``` + +`condition`是一个布尔表达式。如果`condition`的值为`true`，那么则执行`#code`代表的代码块。此后，再次判断`condition`的值，如果`condition`的值为`true`，那么`#code`代表代码块将会被执行；如此循环，直到`condition`的值为`false`。 + +`do-while`语句和`while`类似，但是无论条件是否成立，它都会先执行因此循环体中的语句，而后再判断条件来决定是否继续进行。`do-while`语句的语法如下： + +```mcfpp +do{ + #code +}while (condition); +``` + +## for语句 + +`for`语句是循环的一种稍复杂的版本，它的语法如下： + +```mcfpp +for (forinit; condition; forupdate){ + #code +} +``` + +`forinit`是一个初始化表达式，它用来初始化循环变量。`condition`是一个布尔表达式，它用来判断循环是否继续。`forupdate`是一个更新表达式，它用来更新循环变量。`#code`代表了循环体，即循环体中的代码。在运行的时候，`for`语句的执行过程如下： + +1. 执行`forinit`，初始化循环变量。 +2. 判断`condition`的值，如果`condition`的值为`true`，则执行`#code`代表的代码块，然后执行`forupdate`，更新循环变量，再次判断`condition`的值。 +3. 如果`condition`的值为`false`，则退出循环。 + +`for`循环中，`forinit`声明的变量只在`for`循环中有效。 + +## break和continue语句 + +`break`语句用来跳出整个循环，`continue`语句用来跳过本次循环。例如： + +```mcfpp +for (int i = 0; i < 10; i++){ + if (i == 5){ + break; + } + if (i == 3){ + continue; + } + #code +} +``` + +在上面的例子中，当`i`的值为`5`时，`break`语句会跳出整个循环；当`i`的值为`3`时，`continue`语句会跳过本次循环，直接进行下一次循环。因此，i在每次循环中的变化为：`0`，`1`，`2`，`4`，`5`，最后跳出循环。 + +`break`和`continue`语句只能在循环中使用。 diff --git a/docs/en/quickstart/02base/04top-statements.md b/docs/en/quickstart/02base/04top-statements.md new file mode 100644 index 0000000..93e972a --- /dev/null +++ b/docs/en/quickstart/02base/04top-statements.md @@ -0,0 +1,27 @@ +--- +lastUpdated: true +--- + +# 顶层语句 + +在MCFPP中，允许在文件的开始直接编写语句而无需额外定义函数，即顶层语句。顶层语句处于一个隐式的函数中，这个函数每个文件有且只有一个，且不能被外部调用。它的返回值类型为`void`。 + +```mcfpp +print("Top statement"); + +func main(){ + print("Function"); +} +``` + +在编译后，会生成两个函数——分别对应main函数以及顶层语句对应的默认函数。 + +顶层语句只能在文件的开始编写，即在函数定义或类定义之前。顶层语句可以调用文件中声明的其他函数和类 + +```mcfpp +main(); + +func main(){ + print("Function"); +} +``` diff --git a/docs/en/quickstart/03namespace/01namespace.md b/docs/en/quickstart/03namespace/01namespace.md new file mode 100644 index 0000000..621dbf6 --- /dev/null +++ b/docs/en/quickstart/03namespace/01namespace.md @@ -0,0 +1,37 @@ +--- +lastUpdate: true +--- + +# 命名空间 + +MCFPP中的命名空间和MC中的命名空间是同一种东西。这也意味着，命名空间只能是小写字母、数字，点和下划线的组合。 + +你可以在文件中声明一个命名空间，这样文件中的所有函数和变量都会被放置在这个命名空间中。例如： + +```mcfpp +namespace test; + +func test(){ # test:test函数 + print(i); +} +``` + +一个文件中只能声明一次命名空间。 + +同样的，你也可以在项目配置文件中声明这个命名空间。 + +```json +{ + "file":[ + "*" + "D:/workspace/mcfpp/project/*" + ], + "version":"1.19.4", + "include":[ + "D:/workspace/mcfpp/another_project.json" + ], + "targetPath":"./out", + //工程的默认命名空间。可选，默认为default // [!code focus] + "namespace":"mcfpp" // [!code focus] +} +``` diff --git a/docs/en/quickstart/04function/01define-and-call.md b/docs/en/quickstart/04function/01define-and-call.md new file mode 100644 index 0000000..cf1ac31 --- /dev/null +++ b/docs/en/quickstart/04function/01define-and-call.md @@ -0,0 +1,65 @@ +--- +lastUpdate: true +--- + +# 定义和调用 + +MCFPP函数的定义方式和C/Java有较大的区别，而更加接近于Python的语法。 + +## 函数定义 + +MCFPP中，函数的定义语法如下： + +```mcfpp +func functionName(parameter1, parameter2, ...) -> returnType{ + #函数体 +} +``` + +`func`是函数的关键字，`functionName`是函数的标识符或者说名字，而紧随其后的`parameter1, parameter2, ...`则是函数的参数列表，`returnType`是可选的，即函数的返回类型。函数体则是由`{}`包裹的一系列语句。下面是一个实际的例子： + +```mcfpp +func add(int a, int b) -> int{ + return a + b; +} +``` + +这个函数的名字是`add`，它有两个整数类型的参数`a`和`b`，返回值也是一个整数类型。这个函数的作用是把两个参数相加并返回结果。 + +## return + +`return`和Minecraft中的`return`命令作用相同，都是用于返回函数的返回值。它的语法即为`return expression;`，其中`expression`是一个表达式，它的值就是函数的返回值。 + +如果一个函数定义了返回值类型，那么它的每一个分支都必须有`return`语句，即函数必定返回一个值。且`return`语句返回的值必须和函数的返回值类型相同，或者是返回值类型的子类型。 + +如果一个函数没有定义返回值类型，那么默认为`void`，即不会返回任何值。这个时候，`return`语句仍然是可用的，但是它的语法变为`return;`，即不带任何表达式。它将会起到立刻终止函数运行的作用。 + +## 函数的调用 + +MCFPP中，函数的调用语法和C/Java一样，即`functionName(parameter1, parameter2, ...);`。其中，`functionName`是函数的名字，`parameter1, parameter2, ...`是要传递给函数的参数。下面是一个实际的例子： + +```mcfpp +func test(){ + print(add(1, 2)); #上面定义的add函数 +} +``` + +这个例子中，`test`函数调用了`add`函数，并传递了两个参数`1`和`2`。`add`函数返回了`3`，因此`test`函数将会打印出`3`。 + +## 函数的传参 + +函数中，对参数的修改不会影响到函数外部的变量。例如： + +```mcfpp +func test(int a){ + a = 5; +} + +void main(){ + int a = 0; + test(a); + print(a); #输出0 +} +``` + +在这个例子中，`test`函数对传入的参数`a`进行了修改，但是`main`函数中的`a`并没有受到影响。 diff --git a/docs/en/quickstart/04function/02static-params.md b/docs/en/quickstart/04function/02static-params.md new file mode 100644 index 0000000..9d66799 --- /dev/null +++ b/docs/en/quickstart/04function/02static-params.md @@ -0,0 +1,19 @@ +--- +lastUpdate: true +--- + +# static关键字 + +`static`关键字用于声明一个静态参数。静态参数表示，在参数传递的过程中，是传递的参数本身而不是参数的值，因此在函数中对参数的修改会影响外部的变量。例如： + +```mcfpp +func test(static int a){ + a = 5; +} + +void main(){ + int a = 0; + test(a); + print(a); #输出5 +} +``` diff --git a/docs/en/quickstart/04function/03inline-function.md b/docs/en/quickstart/04function/03inline-function.md new file mode 100644 index 0000000..5691b83 --- /dev/null +++ b/docs/en/quickstart/04function/03inline-function.md @@ -0,0 +1,44 @@ +--- +lastUpdate: true +--- + +# 内联函数 + +MCFPP中，可以使用`inline`关键字来声明一个内联函数。编译器会在调用内联函数的地方直接将函数的代码插入，而不是通过函数调用的方式来执行。这样可以减少函数调用的开销，提高程序的运行效率。 + +## 内联函数的声明 + +内联函数的声明语法如下： + +```mcfpp +inline func functionName(parameter1, parameter2, ...) -> returnType{ + #函数体 +} +``` + +## 内联函数的调用过程 + +在调用内联函数的地方，编译器会直接将内联函数的代码插入，而不是通过函数调用的方式来执行。例如下面的例子： + +```mcfpp +inline func add(int a, int b) -> int{ + return a + b; +} + +func main(){ + print(add(1, 2)); +} +``` + +编译的时候，上述代码会相当于： + +```mcfpp +func main(){ + int a = 1; + int b = 2; + int ret = a + b; + print(ret); +} +``` + +这同时意味着，在内联函数中，对变量的修改会影响到函数外部的变量。 diff --git a/docs/en/quickstart/04function/04compiletime-function.md b/docs/en/quickstart/04function/04compiletime-function.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/en/quickstart/05class/01define-and-instantiate.md b/docs/en/quickstart/05class/01define-and-instantiate.md new file mode 100644 index 0000000..56c1cd8 --- /dev/null +++ b/docs/en/quickstart/05class/01define-and-instantiate.md @@ -0,0 +1,58 @@ +--- +lastUpdate: true +--- + +# 类的定义和实例化 + +```mcfpp +class Person{ + string name; + int age; + string sex; + + constructor(string name, int age){ + this.name = name; + this.age = age; + } + + func setName(string name){ + this.name = name; + } + + func toString() -> string{ + return "Name: " + this.name + ", Age: " + this.age; + } +} +``` + + +## 类的定义 + +作为一个面向对象的编程语言，MCFPP有完善的面向对象的语法和功能。它的语法和Java/C#的语法非常相似，所以，如果你有相关的基础的话，你应该可以很轻松地上手。 + +在MCFPP中，可以使用`class`关键字来声明一个类： + +```mcfpp +class ClassName{ + #类体 + #... +} +``` + +其中，`ClassName`是类的名字。在MCFPP中，类的名字必须以大写字母开头。而紧随其后的花括号中的内容则是类体，包含了类的成员变量和成员函数，以及它的构造方法等等。是吧，和Java/C#是一样的。 + +## 类的实例化 + +一般情况下，你可以使用`ClassName(参数列表)`来创建一个对象的实例。比如本篇开头的示例`Person`类可以用`Person p = Person("Alumopper",16)`来创建。在MCFPP中，你并不需要`new`关键字。它被省略掉了。 + +## 类的初始化器 + +在创建类的时候，你可以使用类初始化器来对类的某些成员变量初始化，例如对于上文中的`Person`，有： + +```mcfpp +Person p = Person("Alumopper",16){ + sex = "女" +}; +``` + +这样，`p`的`sex`成员变量就被初始化为`"女"`了。 \ No newline at end of file diff --git a/docs/en/quickstart/05class/02member.md b/docs/en/quickstart/05class/02member.md new file mode 100644 index 0000000..a530b62 --- /dev/null +++ b/docs/en/quickstart/05class/02member.md @@ -0,0 +1,74 @@ +--- +lastUpdate: true +--- + +# 类的成员 + +和Java类似，在MCFPP中，类的成员包括属性和方法。属性是类的数据成员，用来存储对象的数据；方法是类的函数成员，用来操作对象的数据。类的成员可以通过`.`操作符来访问。 + +## 属性 + +属性是类的数据成员，用来存储对象的数据。属性的定义语法如下： + +```mcfpp +class A{ + int a; + int b = 5; +} +``` + +上述代码定义了一个类`A`，它有两个属性`a`和`b`。`a`是一个整数类型的属性，没有初始化；`b`是一个整数类型的属性，初始化为`5`。 + +## 方法 + +方法是类的函数成员，用来操作对象的数据。方法的定义语法如下： + +```mcfpp +class A{ + void test(){ + print("Hello, World!"); + } +} +``` + +在方法中使用`this`关键字可以访问对象的属性。例如： + +```mcfpp +class A{ + int a; + void setA(int a){ + this.a = a; + } +} +``` + +## 访问控制 + +MCFPP中，类的成员可以使用`public`、`protected`、`private`关键字来控制访问权限。默认情况下，类的成员是`private`的。 + +- `public`：公有的，可以被外部访问。 +- `protected`：受保护的，可以被子类访问。 +- `private`：私有的，只能在类的内部访问。 + +```mcfpp +class A{ + public int a; + protected int b; + private int c; +} + +class B: A{ + void test(){ + a = 1; #合法 + b = 2; #合法 + c = 3; #编译错误 + } +} + +func test(){ + A obj = new A(); + obj.a = 1; #合法 + obj.b = 2; #编译错误 + obj.c = 3; #编译错误 +} +``` diff --git a/docs/en/quickstart/05class/03inheritance-abstract.md b/docs/en/quickstart/05class/03inheritance-abstract.md new file mode 100644 index 0000000..fe59ad4 --- /dev/null +++ b/docs/en/quickstart/05class/03inheritance-abstract.md @@ -0,0 +1,49 @@ +--- +lastUpdate: true +--- + +# 继承和抽象 + +MCFPP中，类支持继承和抽象。继承是指一个类可以派生出一个或多个子类，子类可以继承父类的属性和方法。抽象是指一个类可以定义抽象方法，子类必须实现这些抽象方法。 + +## 继承 + +继承是指一个类可以派生出一个或多个子类，子类可以继承父类的属性和方法。继承的语法如下： + +```mcfpp +class Parent{ + protect int a; + func test(){ + print("Parent"); + print(a); + } +} + +class Child: Parent{ + int b; + override func test(){ + print("Child"); + print(super.a); + } +} +``` + +使用`:`关键字可以声明一个类继承自另一个类。利用`super`关键字，子类可以访问父类的属性和方法。使用`protected`关键字可以声明受保护的属性，子类可以访问父类的受保护属性。使用`override`关键字可以重写父类的方法。 + +## 抽象 + +一个类可以定义抽象方法，子类必须实现这些抽象方法。抽象方法没有方法体，只有方法签名。抽象方法的定义语法如下： + +```mcfpp +abstract class A{ + abstract func test(); +} + +class B: A{ + override func test(){ + print("Hello, World!"); + } +} +``` + +使用`abstract`关键字可以声明一个抽象类或一个抽象方法。抽象类的子类必须实现抽象方法，否则会编译错误。 \ No newline at end of file diff --git a/docs/en/quickstart/06interface/01define-and-implement.md b/docs/en/quickstart/06interface/01define-and-implement.md new file mode 100644 index 0000000..eb2375d --- /dev/null +++ b/docs/en/quickstart/06interface/01define-and-implement.md @@ -0,0 +1,53 @@ +--- +lastUpdate: true +--- + +# 定义和实现接口 + +MCFPP中，可以使用`interface`关键字来声明一个接口。接口是一种抽象的数据类型，它定义了一组方法的签名，但没有具体的实现。类可以实现一个或多个接口，从而保证类具有接口中定义的方法。 + +## 接口的声明 + +接口的声明语法如下： + +```mcfpp +interface InterfaceName{ + func methodName(parameterList) -> returnType; + func methodName(parameterList) -> returnType; + ... +} +``` + +接口中的方法只有方法签名，没有方法体。接口中的方法可以有多个，每个方法之间使用分号`;`分隔。接口中的方法一定都是抽象方法，但是不需要额外使用`abstract`关键字来声明 + +## 接口的实现 + +接口不能被实例化，但可以被类实现。 + +类可以实现一个或多个接口。实现接口的类必须实现接口中定义的所有方法。实现接口的语法如下： + +```mcfpp +class ClassName: Interface1, Interface2, ...{ + #类的属性和方法 + ... + override func methodName(parameterList) -> returnType{ + #方法体 + } +} +``` + +## 接口的继承 + +接口也可以继承自其他接口。继承接口的语法如下： + +```mcfpp +interface Interface1{ + func method1() -> void; +} + +interface Interface2: Interface1{ + func method2() -> void; +} +``` + +如果一个类实现了一个继承了其他接口的接口，那么这个类必须实现接口以及其继承接口中定义的全部方法。 diff --git a/docs/en/quickstart/07generic/01concrete_var.md b/docs/en/quickstart/07generic/01concrete_var.md new file mode 100644 index 0000000..898125b --- /dev/null +++ b/docs/en/quickstart/07generic/01concrete_var.md @@ -0,0 +1,30 @@ +--- +lastUpdate: true +--- + +# 编译确定量 + +在编译过程中，编译器会对一些编译器可以确定的变量进行优化，例如 + +```mcfpp +int i = 5; +int j = 5; + +print(i + j); +``` + +这个时候，编译器就会知道`i`和`j`的值，因此可以直接计算出`i+j`的值为10，而且在print函数中，也可以直接输出10，而不用再转换为记分板的原始JSON文本了。 + +这种变量，在MCFPP中叫做编译确定量（`Concrete Var`）。编译确定量和普通变量是可以相互转换的，例如： + +```mcfpp +int i = 5; +dynamic j; +i = j; +``` + +在这个例子中，虽然开始的时候编译器能追踪i的值，但是在后面的代码中，i的值被赋值为j，而j被关键字`dynamic`修饰，表示这个变量在声明的时候是不确定的，因此编译器就会丢失对i的值的追踪。 + +同理，如果一个普通变量，被赋值为了一个确定的值，或者被赋值为一个编译确定量，那么编译器就能够获取这个变量的值，这个变量也就因此成为了编译确定量。 + +值得注意的是，编译器永远不会追踪类的成员变量。即使类的成员变量被赋值为一个确定的值，编译器仍然会将它作为普通变量进行处理。 diff --git a/docs/en/quickstart/07generic/02generic_function.md b/docs/en/quickstart/07generic/02generic_function.md new file mode 100644 index 0000000..21b88b8 --- /dev/null +++ b/docs/en/quickstart/07generic/02generic_function.md @@ -0,0 +1,48 @@ +--- +lastUpdate: true +--- + +# 泛型函数 + +## 泛型参数 + +我们之前说了编译确定量的概念。在mcfpp中，可以声明一个函数需要一些编译确定量作为参数。需要使用`<>`来包围编译确定量的参数列表，从而和普通的参数区分开。在调用的时候，也要使用`<>`来包围编译确定量的参数。 + +```mcfpp + +func test{ + print(i); +} + +func main(){ + test<5>(); + test<6>(); +} + +``` + +在上面的例子中，`test`函数接受一个编译确定量`i`作为参数，然后打印出这个参数。在`main`函数中，我们调用了两次`test`函数，分别传递了`5`和`6`作为参数。这样，`test`函数就会打印出`5`和`6`。 + +值得注意的是，编译器会在编译的时候，不会立刻将`test`函数编译，而是会等到要调用的时候，再将`test`函数的代码进行编译，并分别替换`i`为`5`和`6`。这样，`test`函数就会有两个版本，分别打印出`5`和`6`。而在编译好的数据包中，也只会包含编译后的`test`函数，不会包含原来的`test`函数。 + +## 类型参数 + +有一种特殊的变量，叫做类型变量。类型变量永远只能是编译时确定量，因此永远是编译器已知的。如果尝试让编译器丢失对类型变量的追踪，那么编译器会报错。 + +使用`type`关键字对类型变量进行声明。例如： + +```mcfpp +type t = int; +``` + +此时，t就代表了int变量。但是这个时候，你还不能将t直接用于`t qwq = 1`这种变量声明，因为`t`并没有被注册入编译器的类型缓存中。只有当编译器作为函数的泛型参数被传入时，你才可以在这个函数中，使用这个类型变量进行变量声明。 + +```mcfpp +func test(T i){ + print(qwq); +} + +func main(){ + test(1); +} +``` diff --git a/docs/en/quickstart/07generic/03generic_class.md b/docs/en/quickstart/07generic/03generic_class.md new file mode 100644 index 0000000..b40644e --- /dev/null +++ b/docs/en/quickstart/07generic/03generic_class.md @@ -0,0 +1,68 @@ +--- +lastUpdate: true +--- + +# 泛型类 + +和函数一样，类也可以拥有只读参数列表。这样子的类被成为泛型类。同时，只读参数列表还给泛型类带来了一些特殊的性质。 + +## 泛型类的声明 + +泛型参数在声明类的时候，在类的标识符后面，使用`<>`包裹泛型参数。 + +```mcfpp +class ClassName{ + #类的属性和方法 + ... +} +``` + +在上面的例子中，`T`是泛型参数。和函数一样，在类的内部，可以使用`T`来声明变量，这样，这个变量的类型就是泛型参数`T`。 + +```mcfpp +class ClassName{ + T value; + + public ClassName(T value){ + this.value = value; + } + + func getValue() -> T{ + return this.value; + } +} + +func main(){ + ClassName c = ClassName(5); #创建泛型类的对象 + print(c.getValue()); #输出5 +} +``` + +和泛型函数一样，在编译过程中，并不会立刻编译泛型类，而是会在实例化的过程中，根据传入的泛型参数，即时编译这个泛型类。同样的，在生成的数据包中也只会包含编译生成的类，不会包含泛型的原始类型。 + +从上面的例子中也可以注意到，在实例化泛型类的过程中，如果显示声明了泛型类型，那么在实例化的时候，就不需要再传入泛型参数了。 + +## 泛型类的重载 + +由于泛型类含有泛型参数，那么当然也能进行重载。根据泛型参数的不同，编译器会将其视作不同的类。 + +```mcfpp +class Test{ + func print(){ + print(this.i); + } +} + +class Test{ + func print(){ + print(this.i + this.j); + } +} + +func main(){ + var test = Test<5>(); + var test2 = Test<5, 6>(); + test.print(); + test2.print(); +} +``` diff --git a/docs/en/quickstart/08template/01define-and-instantiate.md b/docs/en/quickstart/08template/01define-and-instantiate.md new file mode 100644 index 0000000..d09cd81 --- /dev/null +++ b/docs/en/quickstart/08template/01define-and-instantiate.md @@ -0,0 +1,3 @@ +TODO + +但是第十章是写了的！ \ No newline at end of file diff --git a/docs/en/quickstart/08template/02template-parameters.md b/docs/en/quickstart/08template/02template-parameters.md new file mode 100644 index 0000000..30404ce --- /dev/null +++ b/docs/en/quickstart/08template/02template-parameters.md @@ -0,0 +1 @@ +TODO \ No newline at end of file diff --git a/docs/en/quickstart/09library/01import-and-use.md b/docs/en/quickstart/09library/01import-and-use.md new file mode 100644 index 0000000..30404ce --- /dev/null +++ b/docs/en/quickstart/09library/01import-and-use.md @@ -0,0 +1 @@ +TODO \ No newline at end of file diff --git a/docs/en/quickstart/09library/02export-library.md b/docs/en/quickstart/09library/02export-library.md new file mode 100644 index 0000000..30404ce --- /dev/null +++ b/docs/en/quickstart/09library/02export-library.md @@ -0,0 +1 @@ +TODO \ No newline at end of file diff --git a/docs/en/quickstart/10mni/01mni-framework.md b/docs/en/quickstart/10mni/01mni-framework.md new file mode 100644 index 0000000..8670cf8 --- /dev/null +++ b/docs/en/quickstart/10mni/01mni-framework.md @@ -0,0 +1,62 @@ +--- +lastUpdate: true +--- + +# MNI框架 + +MNI框架（Minecraft Native Implement Framework）是MCFPP提供的一个在编译过程中与JVM虚拟机交互的逻辑。MNI允许开发者在mcfpp中调用Java方法，或者使用Java实现MCFPP函数的功能。MNI和Java中的JNI较为类似，但是比JNI更加简洁易用。 + +在MCFPP中，有大量的函数都是通过MNI实现的，例如`print`函数。下面是一个例子，展示`print`函数利用MNI的实现过程。 + +```mcfpp +#定义print函数以及它的重载 +func print(int i) = top.mcfpp.lang.System.print; +func print(any a) = top.mcfpp.lang.System.print; +``` + +```java +//print函数在java中的具体实现 +package top.mcfpp.lang; + +//略去import函数 + +public class System extends MNIMethodContainer { + + @NotNull + @Override + public Function4[], Var[], CanSelectMember, ValueWrapper>, java.lang.Void> getMNIMethod(@NotNull String name) { + return methods.get(name); + } + + static HashMap[], Var[], CanSelectMember, ValueWrapper>, java.lang.Void>> methods; + + static { + methods = new HashMap<>(); + //实现print函数 + methods.put("print", (vars, vars2, canSelectMember, varValueWrapper) -> { + //只会有一个参数哦 + var value = vars2[0]; + if (value instanceof MCInt) print((MCInt) value); + else print(value); + return null; + }); + } + + @InsertCommand + public static void print(@NotNull MCInt var) { + if (var instanceof MCIntConcrete varC) { + //是确定的，直接输出数值 + Function.Companion.addCommand("tellraw @a " + varC.getValue()); + }else { + Function.Companion.addCommand("tellraw @a " + new JsonTextNumber(var).toJson()); + } + } + + @InsertCommand + public static void print(@NotNull Var var){ + Function.Companion.addCommand("tellraw @a " + "\"" +var + "\""); + } +} +``` + +在接下来的章节中，我们将会详细介绍MNI框架的使用方法。 diff --git a/docs/en/quickstart/10mni/02mni-framework-implementation.md b/docs/en/quickstart/10mni/02mni-framework-implementation.md new file mode 100644 index 0000000..6d9a89d --- /dev/null +++ b/docs/en/quickstart/10mni/02mni-framework-implementation.md @@ -0,0 +1,143 @@ +--- +lastUpdate: true +--- + +# MNI函数 + +## 声明 + +如果我们想要声明一个函数的具体实现逻辑是由Java代码实现的，我们就需要将它声明为**Native函数**。Native函数的声明格式如下： + +```mcfpp +func 函数名(参数列表) = Java类名.函数名; +``` + +例如我们刚刚例子中提到的`print`函数，它的声明是： + +```mcfpp +func print(int i) = top.mcfpp.lang.System.print; +``` + +它表示，print函数拥有一个int类型的参数，同时它的逻辑交给了`top.mcfpp.lang.System`类的`print`函数来实现。注意这里的类名需要是完全限定名，需要包含包名，否则编译器将无法找到这个类。 + +## 实现 + +`System`类被称为**MNI实现类**，`print`函数的具体逻辑就是在这个类中实现的。MNI的实现类必须继承`MNIMethodContainer`类： + +```kotlin +package top.mcfpp.model.function + +typealias MNIMethod = (Array?>, Array?>, CanSelectMember?, ValueWrapper>) -> Void + +abstract class MNIMethodContainer{ + + abstract fun getMNIMethod(name: String): MNIMethod + +} +``` + +其中，定义了一个名为`getMNIMethod`的抽象方法，它的参数是一个函数名，即在之前声明native方法的时候，在等号后面的部分，类名.函数名中的函数名。方法需要根据传入的函数名，返回一个`MNIMethod`函数。 + +而`MNIMethod`是一个lambda函数类型，它接受四个参数： + +* `Array?> readonlyArgs`：传入函数的泛型参数数组。参数的顺序和定义一致。 + +* `Array?> normalArgs`：传入函数的普通参数数组。参数的顺序和定义一致。 + +* `CanSelectMember? caller`：这个函数的调用者。比如对于`a.test()`，变量`a`就是调用者。如果调用者不存在，比如对于全局函数，那么这个参数就是`null` + +* `ValueWrapper> returnVar`：这个参数即为函数的返回值。它的成员变量`value`即为函数的返回值对应的变量，可以通过修改value达到返回某个值的目的。如果函数没有返回值，可以不用管这个参数。 + +在MNI调用执行Native函数的过程中，将会自动调用`getMNIMethod`方法，根据函数名获取到对应的函数，传入上述四个参数，然后执行这个函数。 + +一般来说，我们会在MNI实现类中定义一个静态的`HashMap`，用于存储所有的MNI函数。这个`HashMap`的key是函数名，value是对应的`MNIMethod`函数。在`getMNIMethod`方法中，我们只需要根据传入的函数名，从`HashMap`中获取到对应的函数即可，例如对于`System`类，我们的实现是这样的： + +```java +package top.mcfpp.lang; + +//略去import函数 + +public class System extends MNIMethodContainer { + + @NotNull + @Override + public Function4[], Var[], CanSelectMember, ValueWrapper>, java.lang.Void> getMNIMethod(@NotNull String name) { + return methods.get(name); + } + + static HashMap[], Var[], CanSelectMember, ValueWrapper>, java.lang.Void>> methods; + + static { + methods = new HashMap<>(); + //实现print函数 + methods.put("print", (vars, vars2, canSelectMember, varValueWrapper) -> { + //具体逻辑在这里实现 + }); + } +} +``` + +其中，我们在`System`类中定义了一个`HashMap`，并在静态代码块中初始化了`print`函数的实现。现在，我们来具体实现这个函数。 + +```java + //... + + static { + //... + //实现print函数 + methods.put("print", (vars, vars2, canSelectMember, varValueWrapper) -> { + //只会有一个参数哦 + var value = vars2[0]; + if (value instanceof MCInt) print((MCInt) value); + else print(value); + return null; + }); + } + + @InsertCommand + public static void print(@NotNull MCInt var) { + if (var instanceof MCIntConcrete varC) { + //是确定的，直接输出数值 + Function.Companion.addCommand("tellraw @a " + varC.getValue()); + }else { + Function.Companion.addCommand("tellraw @a " + new JsonTextNumber(var).toJson()); + } + } + + @InsertCommand + public static void print(@NotNull Var var){ + Function.Companion.addCommand("tellraw @a " + "\"" +var + "\""); + } + + //... +``` + +首先，我们获取到了传入`print`的参数。由于`print`函数只有一个普通参数，因此我们直接使用`var2[0]`就可以获取到这个传入的参数了。此后，我们使用`instanceof`关键字判断这个参数的类型，如果是`MCInt`类型，那么我们就调用`print(MCInt var)`函数。在不同类型对应的函数中，我们再进行具体的实现。 + +:::tip +`Function.addCommand`函数用于向当前正在编译的mcf函数的末尾添加一条命令 +::: + +## 调用 + +在MCFPP中，我们可以直接调用MNI函数，就像调用普通函数一样。例如： + +```mcfpp +print(5); +``` + +但是MNI函数和普通函数一个非常重要的区别就是，MNI是在编译期执行的。在编译到此函数的时候，将会执行这个函数。也就是说，MNI函数的执行和逻辑语句无关，MNI函数也不会出现在数据包中。 + +例如： + +```mcfpp +if(b){ + print(7); +}else{ + print(8); +} +``` + +编译器编译的时候是从上往下编译的，并且编译过程中不会在意逻辑语句。因此，无论`b`的值是什么，编译器始终都会先后遇到`print(7)`和`print(8)`，并且执行这两个函数。因此，数据包中始终会有`tellraw @a 7`和`tellraw @a 8`这两条命令。 + +当然，由于if的两个分支会对应两个不同的函数，因此`tellraw @a 7`和`tellraw @a 8`会分别出现在两个函数中。但是若调用的MNI函数的实现不同，那么可能会出现更多意想不到的情况。因此在使用MNI函数的时候，应当额外注意这一点。 diff --git a/docs/en/quickstart/10mni/03javavar.md b/docs/en/quickstart/10mni/03javavar.md new file mode 100644 index 0000000..4b24780 --- /dev/null +++ b/docs/en/quickstart/10mni/03javavar.md @@ -0,0 +1,51 @@ +--- +lastUpdate: true +--- + +# JavaVar + +在MCFPP中有一个相当特殊的变量类型，即`JavaVar`。它只能被MNI函数返回，不能被直接创建。`JavaVar`也只存在于编译过程中，它表示了编译过程中的一个Java变量，同样也属于MNI框架的一部分。 + +`JavaVar`变量仅可通过MNI的返回值获取。例如我们有MNI函数实现如下： + +```mcfpp +func getJavaVar() = top.mcfpp.lang.JavaVar.getJavaVar; +``` + +```java +import java.util.Random; + +//... +method.add("getJavaVar", (readonlyArgs, normalArgs, caller, returnVar) -> { + returnVar.value = new JavaVar(new Random()); //返回一个随机数生成器 + return null; +}); +//... +``` + +这个MNI函数将会返回一个`JavaVar`变量，它的值是`Random`类的一个实例。接下来，我们可以在mcfpp中调用这个函数： + +```mcfpp +var random = getJavaVar(); +``` + +现在，random是一个JavaVar类型的变量，它的值是`Random`类的一个实例。接下来，我们可以去调用它的各种方法： + +```mcfpp +#调用方法 +var nextInt = random.nextInt(100); +``` + +调用`JavaVar`类型变量的成员方法得到的变量仍然是`JavaVar`类型的变量。得益于MCFPP和Java/Kotlin语法的极大相似，我们可以几乎无缝在MCFPP中调用Java/Kotlin的方法。 + +同样，在适当的情况下，编译器会完成部分类型的MCFPP变量和Java变量之间的自动转换。 + +```mcfpp +int qwq = 100; #MCFPP变量 + +var nextInt = random.nextInt(qwq); #MCFPP变量自动转换为Java变量，并传入Java方法中 + +int nextMCFPPInt = nextInt; #Java变量自动转换为MCFPP变量 +``` + +这样的转换有一个前提，也就是，MCFPP变量必须是已知的，才能被自动转换为对应的Java变量，否则将会转换为为`Var`类，即所有MCFPP变量在编译器中的基类。当然，如果Java方法默认需要一个`Var`类型的参数，编译器就不会执行自动转换。 diff --git a/docs/en/quickstart/11gradle/01gradle-configuration.md b/docs/en/quickstart/11gradle/01gradle-configuration.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/en/quickstart/index.md b/docs/en/quickstart/index.md new file mode 100644 index 0000000..2cc25e1 --- /dev/null +++ b/docs/en/quickstart/index.md @@ -0,0 +1,9 @@ +--- +lastUpdated: true +--- + +# Quickstart + +Welcome to the syntax documentation of the mcfpp programming language. The document aims to provide a comprehensive overview of the MCFPP language, covering its basic syntax, data types, control structures, function definitions, class definitions, MNI framework, and other important features. Click on the right navigation bar to start your MCFPP journey! + +Some documents may be marked as TODO, don't worry, these are the features we haven't designed well yet! In the near future, we will supplement these contents. \ No newline at end of file diff --git a/docs/zh/quickstart/index.md b/docs/zh/quickstart/index.md deleted file mode 100644 index 5372d3c..0000000 --- a/docs/zh/quickstart/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -lastUpdated: true ---- - -# 快速开始 - -欢迎阅读 mcfpp 编程语言的语法文档。文档旨在提供MCFPP语言的全面概述，涵盖其基本语法、数据类型、控制结构、函数定义、类定义和MNI框架及其他重要特性。点击右侧的导航栏，开始你的MCFPP之旅吧！ - -一些文档可能被标记为TODO，别着急，这些是我们还没有做好的功能设计！在不久的将来，我们会补充这些内容。