From 1d07cfe8ba133989f8a27374cd3cec989c6990ba Mon Sep 17 00:00:00 2001 From: anqurvanillapy Date: Wed, 12 Jun 2024 00:19:27 +0800 Subject: [PATCH] Update docs Signed-off-by: anqurvanillapy --- blog/2023-05-05-open-sourcing.md | 8 +- docs/01-intro.md | 208 ++++++++++++++++++ ...tting-started.md => 02-getting-started.md} | 20 +- docs/03-definitions.md | 54 +++++ docs/04-variables.md | 1 + docs/05-control.md | 1 + docs/06-everyday-types.md | 45 ++++ docs/handbook/_category_.json | 4 - docs/handbook/enum.md | 5 - docs/handbook/fn.md | 53 ----- docs/handbook/object.md | 5 - docs/handbook/oop.md | 5 - docs/handbook/primitives.md | 44 ---- docs/intro.md | 14 -- docs/roadmap.md | 5 - docs/why/_category_.json | 4 - docs/why/general.md | 41 ---- docs/why/research.md | 11 - docusaurus.config.js | 6 +- .../current/01-intro.md | 7 + .../current/current.json | 8 - .../current/getting-started.md | 57 ----- .../current/handbook/_category_.json | 4 - .../current/handbook/enum.md | 5 - .../current/handbook/fn.md | 56 ----- .../current/handbook/object.md | 5 - .../current/handbook/oop.md | 5 - .../current/handbook/primitives.md | 47 ---- .../current/intro.md | 15 -- .../current/roadmap.md | 5 - .../current/why/_category_.json | 4 - .../current/why/general.md | 47 ---- .../current/why/research.md | 11 - .../homepageFeatures.json | 6 +- .../docusaurus-theme-classic/footer.json | 4 + .../homepageFeatures.json | 6 +- .../docusaurus-theme-classic/footer.json | 4 + 37 files changed, 346 insertions(+), 484 deletions(-) create mode 100644 docs/01-intro.md rename docs/{getting-started.md => 02-getting-started.md} (62%) create mode 100644 docs/03-definitions.md create mode 100644 docs/04-variables.md create mode 100644 docs/05-control.md create mode 100644 docs/06-everyday-types.md delete mode 100644 docs/handbook/_category_.json delete mode 100644 docs/handbook/enum.md delete mode 100644 docs/handbook/fn.md delete mode 100644 docs/handbook/object.md delete mode 100644 docs/handbook/oop.md delete mode 100644 docs/handbook/primitives.md delete mode 100644 docs/intro.md delete mode 100644 docs/roadmap.md delete mode 100644 docs/why/_category_.json delete mode 100644 docs/why/general.md delete mode 100644 docs/why/research.md create mode 100644 i18n/en-us/docusaurus-plugin-content-docs/current/01-intro.md delete mode 100644 i18n/en-us/docusaurus-plugin-content-docs/current/getting-started.md delete mode 100644 i18n/en-us/docusaurus-plugin-content-docs/current/handbook/_category_.json delete mode 100644 i18n/en-us/docusaurus-plugin-content-docs/current/handbook/enum.md delete mode 100644 i18n/en-us/docusaurus-plugin-content-docs/current/handbook/fn.md delete mode 100644 i18n/en-us/docusaurus-plugin-content-docs/current/handbook/object.md delete mode 100644 i18n/en-us/docusaurus-plugin-content-docs/current/handbook/oop.md delete mode 100644 i18n/en-us/docusaurus-plugin-content-docs/current/handbook/primitives.md delete mode 100644 i18n/en-us/docusaurus-plugin-content-docs/current/intro.md delete mode 100644 i18n/en-us/docusaurus-plugin-content-docs/current/roadmap.md delete mode 100644 i18n/en-us/docusaurus-plugin-content-docs/current/why/_category_.json delete mode 100644 i18n/en-us/docusaurus-plugin-content-docs/current/why/general.md delete mode 100644 i18n/en-us/docusaurus-plugin-content-docs/current/why/research.md diff --git a/blog/2023-05-05-open-sourcing.md b/blog/2023-05-05-open-sourcing.md index 3e13b2e..1c4cc74 100644 --- a/blog/2023-05-05-open-sourcing.md +++ b/blog/2023-05-05-open-sourcing.md @@ -12,7 +12,7 @@ npm install -D rowscript@latest 目前，编译器仅提供了以下模块： -* 核心语法：RowScript 核心的构建模块，如函数类型（Pi Type）。 -* 内置功能：在代码中可访问但未提供文档的构建模块。 -* 预置库：无需导入即可访问、配有详尽文档的构建模块。 -* 标准库：通过导入来访问、与编译器本体一起打包提供的构建模块。 \ No newline at end of file +* 核心语法：RowScript 核心的构建模块，如函数类型（Pi Type） +* 内置功能：在代码中可访问但未提供文档的构建模块 +* 预置库：无需导入即可访问、配有详尽文档的构建模块 +* 标准库：通过导入来访问、与编译器本体一起打包提供的构建模块 diff --git a/docs/01-intro.md b/docs/01-intro.md new file mode 100644 index 0000000..0f0dccb --- /dev/null +++ b/docs/01-intro.md @@ -0,0 +1,208 @@ +# 概述 + +RowScript 是一种新的 JavaScript 方言，旨在大大改善两类 web 开发者的使用体验： + +* **应用程序开发者**：开发者应该使用强大的工具、框架和灵活的类型系统来编写他们的应用程序 +* **库开发者**：开发者应该能够以较少的 [类型体操] 来编写他们的库，这些类型体操通常是杂乱无章且晦涩难懂的 + +通过使用 RowScript 的工具和类型系统，允许您编写更具可扩展性和足以胜任各种任务的代码。 + +除此之外，RowScript 还包含了许多保守同时又激进的语言特性。总结成一句话就是： + +:::tip + +RowScript：“完成 TypeScript 没法做的事，砍掉 JavaScript 不必要的特性。” + +::: + +[类型体操]: https://github.com/type-challenges/type-challenges + +## 新语言，旧语法 + +RowScript 虽然是一门新的语言，但是它使用了大量的 JavaScript/TypeScript 语法，极大地降低了用户的学习负担。 + +即使是 JS/TS 中没有的语言特性，RowScript 同样重新利用了许多 JS/TS 的关键词和部分语法，使新的特性看起来相对不那么生涩。 + +例如，RowScript 中关于接口（interface）的语法： + + + +```ts +interface ToString { + toString(v: ToString): string; +} + +function getString(n: T): string +where T instanceof ToString +{ + n.toString() +} +``` + + + +新的用户也能很快地猜到，函数 `getString` 要求接收一个类型 `T`，并且要求 `T` 实现了接口 +`ToString`，使得函数内部可使用 `toString` 对 `n` 进行字符串转换。 + +## JS 对象、类、函数 + +JS 中的对象（object）、类（class）和函数（function）往往会产生使用上的分歧。 + +用户可以用对象的风格封装数据与方法。 + +```js +const a = { + n: 42, + getN() { + return this.n; + } +}; +``` + +最原始的函数风格，也是一种选择。 + +```js +function B(n) { + this.n = n; + this.getN = function () { + return this.n; + } +} + +const b = new B(42); +``` + +较新的类的方式，是另一种新的选择。 + +```js +class C { + constructor(n) { + this.n = n; + } + + getN() { + return this.n; + } +} + +const c = new C(42); +``` + +但是这三者都有各自的细微不同，不能轻易的互换，更不可能在 JS 层面得到很好的统一。 + +RowScript 中支持对象和类，但两者在生成出来的 JavaScript 代码中只是简单的对象，没有其他任何添加剂。 + +```ts +class D { + n: number; + + getN(): number { + this.n + } +} + +const d = new D(42); +``` + +编译后的 JS 代码： + +```js +const d = {n: 42}; +``` + +## Void、Null、Undefined、Never、Any、Unknown + +JS/TS 中有许许多多令人匪夷所思的类型： + +* `void` +* `null` +* `undefined` +* `never` +* `any` +* `unknown` + +而在 RowScript 中，这些类型由以下两个特性达成了统一： + +* `unit` 类型：统一 `void`、`null`、`undefined` 和 `never`（相信我，在用户层面，用户并不需要关心 `never` 类型） +* 带有类型擦除（type erasure）的泛型：取代 `any` 和 `unknown` + +举个例子，TypeScript 中的 `any` 可能出现在程序的边界中： + +```ts +declare function foo(v: any); +``` + +在 RowScript 中，使用泛型函数即可： + +```ts +function foo(v: T); +``` + +在代码生成阶段，泛型 `T` 会被自动擦除。 + +## JS/TS 令人痛苦的 union 类型 + +在 TypeScript 中 *narrow* 一个 union 类型通常是很痛苦的事情，这是因为你总需要引入奇怪的分支判断： + +```ts +function printId(id: number | string) { + if (typeof id === "string") { + console.log("Phew, it's a string..."); + } +} +``` + +那如果假设在编译期间还是无法判断 `id` 的具体类型呢？那么我们又要开始手工制造一个有标签（tagged）的 union 类型： + +```ts +type StringID = { + str: string; + type: 'string_id'; +} + +type NumberID = Omit & { + n: number; + type: 'number_id'; +} + +type ID = StringID | NumberID; +``` + +此时你会意识到，虽然 TS 已经提供了所谓的实用类型（utility types）降低了一些噪音，但是 `Omit`、不成文的 `type` +成员作为规范、手动将小写的类型名字作为标签等等，过度的模板代码（boilerplate）依旧存在。 + +在 RowScript 中，枚举（enum）类型很好地解决了这个问题： + + + +```ts +type ID = [ StringID(string) | NumberID(number) ]; +``` + + + +RowScript 的枚举类型和 PureScript、Elm、Haskell 等函数式编程语言中的 ADT（algebraic data types）稍有不同，和 Rust +的枚举类型也有差异，可在后续章节中深入探索枚举类型。 + +## JS/TS 对可变参数缺少类型支持 + +JS 中最常用的函数莫过于 `console.log`，但是这一函数在 TS 中有着令人尴尬的类型： + +```ts +declare function log(...data: any[]): void; +``` + +虽然 TS 中拥有 [可变元组类型（variadic tuples）]，但这个类型没法和可变参数（variadic）产生互动。 + +在 RowScript 中，可变参数通过泛型来实现，但是有一定的功能限制。RowScript 中的 `console.log` 类型： + +```ts +function log(...: Args); +``` + +[可变元组类型（variadic tuples）]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-0.html#variadic-tuple-types + +## 更多语言特性 + +除此之外，RowScript 还提供了如同行多态（row polymorphism）、静态反射（static reflection）、操作符重载、副作用类型（effect +types）等等十分时髦的新特性，跟着这本指南继续往下探索吧！ diff --git a/docs/getting-started.md b/docs/02-getting-started.md similarity index 62% rename from docs/getting-started.md rename to docs/02-getting-started.md index 7f9ad3d..47457f4 100644 --- a/docs/getting-started.md +++ b/docs/02-getting-started.md @@ -1,8 +1,4 @@ ---- -sidebar_position: 2 ---- - -# 入门指南 +# 安装与上手 ## 创建工作文件夹 @@ -22,21 +18,19 @@ npm init npm install -D rowscript ``` -就这样完成了！ +这样就完成了！ -* 不需要 config.json 或其他文件。 -* 无需向 package.json 文件添加新字段以免影响其结构。 +* 不需要 `config.json` 或其他文件 +* 无需向 `package.json` 文件添加新字段以免影响其结构 它的运行就是如此简洁，所有的默认配置均适用，无需额外调整。 ## 你好... 世界? -创建一个名为 `hello.rows` 的文件： +创建一个名为 `hello.rows` 的文件，内容为： ```ts -import console; - -console::log("Hello, world!"); +console.log("Hello, world!"); ``` 运行编译器： @@ -54,4 +48,4 @@ $ node ./dist/index.mjs Hello, world! ``` -啊哈，你只用了 5 分钟就掌握了这门语言⏰！ \ No newline at end of file +啊哈，你只用了 5 分钟就掌握了这门语言 ⏰！ diff --git a/docs/03-definitions.md b/docs/03-definitions.md new file mode 100644 index 0000000..9a67258 --- /dev/null +++ b/docs/03-definitions.md @@ -0,0 +1,54 @@ +# 定义 + +类似 JavaScript，一个 RowScript 程序的顶部包含任意数量的定义（definitions）。 + +## 函数定义 + +RowScript 中的函数定义（functions）与 JS/TS 相似。 + +```ts +function f() { +} +``` + +你需要明确指定函数定义的返回类型，如果不明确指定返回类型，将不会进行任何类型推断，而是认为函数返回的是 `unit` 类型。 + +```ts +function f0() { // ❌ invalid + 42 +} + +function f1(): number { // ✅ okay + 42 +} +``` + +用户不需要在函数的最后加上 `return` 语句。如果省略返回值，系统自动将其视为 `unit` 类型。 + +```ts +function f0(): number { + 42 +} + +function f1(): unit { + const n = f0(); +} +``` + +### 函数类型和表达式 + +可以使用 *箭头函数* 创建函数表达式，这与 TypeScript 中的非常相似。 + +```ts +const f: (x: number) => number = x => x; +``` + +### 泛型函数 + +函数定义可以是泛型的，如同 TypeScript。 + +```ts +function id(x: T): T { + x +} +``` diff --git a/docs/04-variables.md b/docs/04-variables.md new file mode 100644 index 0000000..d970c49 --- /dev/null +++ b/docs/04-variables.md @@ -0,0 +1 @@ +# 变量 diff --git a/docs/05-control.md b/docs/05-control.md new file mode 100644 index 0000000..08d6360 --- /dev/null +++ b/docs/05-control.md @@ -0,0 +1 @@ +# 控制流 diff --git a/docs/06-everyday-types.md b/docs/06-everyday-types.md new file mode 100644 index 0000000..eee5373 --- /dev/null +++ b/docs/06-everyday-types.md @@ -0,0 +1,45 @@ +# 常用类型 + +## 基本类型 + +RowScript 支持并兼容以下 JavaScript 基本类型： + +* [`string`], 例如 `"hello"` +* [`number`], 例如 `42` +* [`boolean`], 即 `false` 和 `true` +* [`bigint`], 例如 `42n` + +[`string`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String + +[`number`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number + +[`boolean`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean + +[`bigint`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt + +## 内置操作符 + +RowScript 不支持一些在 JavaScript 中著名的 [“感谢发明了 JavaScript”] 梗、功能过于“强大”的操作符。比如，`+`/`-` +操作符仅适用于类型相同的参数。 + +```js +1 + 2 // ✅ + +1 + "123" // ❌ +``` + +[“感谢发明了 JavaScript”]: https://www.reddit.com/r/ProgrammerHumor/comments/8srix1/thanks_brendan_for_giving_us_the_javascript + +## Unit 类型 + +在 RowScript 中，我们决定不采用 `null`、`undefined` 和 +`void`，原因是它们一旦混合使用便容易引发混乱。作为替代，我们引入了一种名为 `unit` 的新基本类型。这种类型与 `void` +类似，不过区别在于您实际上可以声明一个此类型的变量，这一特性让它独树一帜。 + +可以使用 `()` 创建 unit 类型的值，我们称之为“unit value”。 + +```ts +const a: unit = (); +``` + +在将代码编译到 JavaScript 时，unit value 会被转换为 `undefined` 以保证兼容性。 diff --git a/docs/handbook/_category_.json b/docs/handbook/_category_.json deleted file mode 100644 index 7edde40..0000000 --- a/docs/handbook/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Handbook", - "position": 3 -} diff --git a/docs/handbook/enum.md b/docs/handbook/enum.md deleted file mode 100644 index 4c5ba59..0000000 --- a/docs/handbook/enum.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 4 ---- - -# 枚举类型 diff --git a/docs/handbook/fn.md b/docs/handbook/fn.md deleted file mode 100644 index 99bf71d..0000000 --- a/docs/handbook/fn.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -sidebar_position: 2 ---- - -# 函数 - -## 函数定义 - -RowScript 中的函数定义与 JavaScript / TypeScript 中的类似。 - -```ts -function f() { - return -} -``` - -用户需要在函数的最后加上 `return` 语句，这个关键字虽然略显多余，但却是必须的，以明确函数的返回类型。如果省略返回值和类型，系统将自动将其视为 `unit` 类型。 - -```ts -function f(): unit { - return () -} -``` - -你需要明确指定函数定义的返回类型，如果不明确指定返回类型，将不会进行任何类型推断。 - -```ts -function f0() { // ❌ invalid - return 42 -} - -function f1(): number { // ✅ okay - return 42 -} -``` - -## 函数类型和表达式 - -可以使用 *箭头函数* 创建函数表达式，这与 TypeScript 中的非常相似。但是，函数的类型使用不同的箭头符号 -> 来与函数表达式区分开来。 - -```plaintext -const f: (x: number) -> number = x => x; -``` - -## 泛型函数 - -函数定义可以是泛型的，如同 TypeScript。 - -```ts -function id(x: T): T { - return x -} -``` diff --git a/docs/handbook/object.md b/docs/handbook/object.md deleted file mode 100644 index 87c0206..0000000 --- a/docs/handbook/object.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 3 ---- - -# 对象类型 diff --git a/docs/handbook/oop.md b/docs/handbook/oop.md deleted file mode 100644 index e232e98..0000000 --- a/docs/handbook/oop.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 5 ---- - -# 面向对象编程 diff --git a/docs/handbook/primitives.md b/docs/handbook/primitives.md deleted file mode 100644 index a5b6864..0000000 --- a/docs/handbook/primitives.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -sidebar_position: 1 ---- - -# 基本类型 - -RowScript 支持并兼容以下 JavaScript 基本类型： - -* [`string`], 例如 `"hello"` -* [`number`], 例如 `42` -* [`boolean`], 即 `false` 和 `true` -* [`bigint`], 例如 `42n` - -[`string`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String - -[`number`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number - -[`boolean`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean - -[`bigint`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt - -## 内置操作符 - -RowScript 不支持一些在 JavaScript 中著名的（["thanks for inventing JavaScript"]）、功能过于「强大」的操作符。比如，+/- 操作符仅适用于类型相同的参数。 - -```js -1 + 2 // ✅ - -1 + "123" // ❌ -``` - -["thanks for inventing JavaScript"]: https://www.reddit.com/r/ProgrammerHumor/comments/8srix1/thanks_brendan_for_giving_us_the_javascript - -## Unit 类型 - -在 RowScript 中，我们决定不采用 `null`、`undefined` 和 `void`，原因是它们一旦混合使用便容易引发混乱。作为替代，我们引入了一种名为 `Unit` 的新基本类型。这种类型与 `void` 类似，不过区别在于您实际上可以声明一个此类型的变量，这一特性让它独树一帜。 - -可以使用 `()` 创建 Unit 类型的值，我们称之为 "Unit value"。 - -```ts -const a: unit = (); -``` - -在将代码编译到 JavaScript 时，`Unit` 会被转换为 `undefined` 以保证兼容性。 \ No newline at end of file diff --git a/docs/intro.md b/docs/intro.md deleted file mode 100644 index f5ed8e8..0000000 --- a/docs/intro.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -sidebar_position: 1 ---- - -# 概述 - -RowScript 是一种新的 JavaScript 方言，旨在大大改善两类 Web 开发者的使用体验： - -* 应用程序开发者：开发者应该使用强大的工具、框架和灵活的类型系统来编写他们的应用程序。 -* 库（轮子）开发者：开发者应该能够以较少的类型体操来编写他们的库，这些类型体操通常是杂乱无章且非平凡。 - -通过使用 RowScript 的工具和类型系统，允许您编写更具扩展性和可伸缩性的代码。 - -[类型体操]: https://github.com/type-challenges/type-challenges \ No newline at end of file diff --git a/docs/roadmap.md b/docs/roadmap.md deleted file mode 100644 index a5134ad..0000000 --- a/docs/roadmap.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 5 ---- - -# 发展规划 diff --git a/docs/why/_category_.json b/docs/why/_category_.json deleted file mode 100644 index 9cb7656..0000000 --- a/docs/why/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Why RowScript?", - "position": 4 -} diff --git a/docs/why/general.md b/docs/why/general.md deleted file mode 100644 index c7b028f..0000000 --- a/docs/why/general.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -sidebar_position: 1 ---- - -# 总体思想 - -有几个初衷激励我们发明了 RowScript。 - -## Totality - -> Total type theory really is adequate for general-purpose programming. -> -> -- Jon Sterling, [Make Three To Throw Away], WITS '22 - -在编译过程中，通过彻底地 (`By totality`) 执行所有可能的计算，结合依值类型系统，我们能够将这些计算结果转化为实用的类型信息。这一机制使得库作者能够构建更优秀的框架，减少对技巧和变通方法的依赖。最重要的是，它提供了良好且交互式的**类型调试支持**。 - -[Make Three To Throw Away]: https://www.jonmsterling.com/slides/sterling-2022-wits.pdf - -## Universal Scripting - -> It makes sense to think of JavaScript as the universal scripting language. -> -> -- Ryan Dahl, [JavaScript Containers] - -JavaScript 因其无处不在的特性，我们首选将代码编译到 JavaScript，而非 WebAssembly，这是因为我们相信，在现代编程语言工具的支持下，这种通用语言的强大潜力。 :) - -[JavaScript Containers]: https://tinyclouds.org/javascript_containers - -## Row Polymorphism - -> Row polymorphism can be a typed solution to JavaScript's prototype-based design. -> -> -- [玩火 (niltok)], from a group talk in 2021 - -在最初，我们尝试用 [row polymorphism] （行多态） 来模拟一些有趣的 JavaScript 代码，这也是 "**Row**Script" 名称的起源。我们进一步发展了行多态特性和更多有趣的东西，使得类型系统健壮且多样化。 - -值得注意的是，RowScript 中的行多态与 PureScript 中的行多态特性不同。在这里，行可以用来创建**可扩展的枚举类型**。 - -[玩火 (niltok)]: https://github.com/niltok -[row polymorphism]: https://en.wikipedia.org/wiki/Row_polymorphism -[that in PureScript]: https://github.com/purescript/documentation/blob/master/language/Types.md#rows diff --git a/docs/why/research.md b/docs/why/research.md deleted file mode 100644 index 261ac0f..0000000 --- a/docs/why/research.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_position: 2 ---- - -# 研究资料 - -:::caution - -这里涉及到一些学术性研究的资料，可能会非常硬核。 - -::: diff --git a/docusaurus.config.js b/docusaurus.config.js index 90cf49f..7d940c4 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -84,6 +84,10 @@ const config = { { title: "Community", items: [ + { + label: "Discussions", + href: "https://github.com/rowscript/rowscript/discussions", + }, { label: "Stack Overflow", href: "https://stackoverflow.com/questions/tagged/rowscript", @@ -104,7 +108,7 @@ const config = { ], }, ], - copyright: `Copyright © ${new Date().getFullYear()} RowScript. Built with Docusaurus.`, + copyright: `"Copyright © ${new Date().getFullYear()} RowScript. Built with Docusaurus.`, }, prism: { theme: prism.themes.github, diff --git a/i18n/en-us/docusaurus-plugin-content-docs/current/01-intro.md b/i18n/en-us/docusaurus-plugin-content-docs/current/01-intro.md new file mode 100644 index 0000000..857be1b --- /dev/null +++ b/i18n/en-us/docusaurus-plugin-content-docs/current/01-intro.md @@ -0,0 +1,7 @@ +# Overview + +:::caution + +English documentation is still WIP. + +::: diff --git a/i18n/en-us/docusaurus-plugin-content-docs/current/current.json b/i18n/en-us/docusaurus-plugin-content-docs/current/current.json index e1618a2..dd30528 100644 --- a/i18n/en-us/docusaurus-plugin-content-docs/current/current.json +++ b/i18n/en-us/docusaurus-plugin-content-docs/current/current.json @@ -2,13 +2,5 @@ "version.label": { "message": "Next", "description": "The label for version current" - }, - "sidebar.tourSidebar.category.Handbook": { - "message": "Handbook", - "description": "The label for category Handbook in sidebar tourSidebar" - }, - "sidebar.tourSidebar.category.Why RowScript?": { - "message": "Why RowScript?", - "description": "The label for category Why RowScript? in sidebar tourSidebar" } } diff --git a/i18n/en-us/docusaurus-plugin-content-docs/current/getting-started.md b/i18n/en-us/docusaurus-plugin-content-docs/current/getting-started.md deleted file mode 100644 index 04facbe..0000000 --- a/i18n/en-us/docusaurus-plugin-content-docs/current/getting-started.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Getting Started - -## Create a Workspace - -RowScript adopts `npm` ecosystem, so `npm init` is all you need. - -```bash -mkdir demo/ -cd demo/ -npm init -``` - -## Install RowScript - -Run the following command: - -```bash -npm install -D rowscript -``` - -And, that's it! - -* No `*config.json` or other files needed -* No new fields should be added to `package.json` file to mess up its schema - -It just works, default configurations are all fine. - -## Hello... World? - -Create a file called `hello.rows`: - -```ts -import console; - -console::log("Hello, world!"); -``` - -Run the compiler: - -```bash -npx rowscript -``` - -And the generated JS code would show up at a subdirectory `./dist/`. - -Run it with `node`: - -```bash -$ node ./dist/index.mjs -Hello, world! -``` - -Ah ha, you just mastered this language in 5 minutes ⏰! diff --git a/i18n/en-us/docusaurus-plugin-content-docs/current/handbook/_category_.json b/i18n/en-us/docusaurus-plugin-content-docs/current/handbook/_category_.json deleted file mode 100644 index 7edde40..0000000 --- a/i18n/en-us/docusaurus-plugin-content-docs/current/handbook/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Handbook", - "position": 3 -} diff --git a/i18n/en-us/docusaurus-plugin-content-docs/current/handbook/enum.md b/i18n/en-us/docusaurus-plugin-content-docs/current/handbook/enum.md deleted file mode 100644 index 3b543ab..0000000 --- a/i18n/en-us/docusaurus-plugin-content-docs/current/handbook/enum.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 4 ---- - -# Enum Types diff --git a/i18n/en-us/docusaurus-plugin-content-docs/current/handbook/fn.md b/i18n/en-us/docusaurus-plugin-content-docs/current/handbook/fn.md deleted file mode 100644 index b9a77a7..0000000 --- a/i18n/en-us/docusaurus-plugin-content-docs/current/handbook/fn.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Functions - -## Function Definitions - -Function definitions in RowScript look similar to ones in JavaScript/TypeScript. - -```ts -function f() { - return -} -``` - -Users need to write `return` as the last expression of the function, a slightly noisy but necessary keyword to indicate -what to return. If the return value and type are omitted, they are desugared into a unit value and the unit type. - -```ts -function f(): unit { - return () -} -``` - -However, you need to explicitly specify the return type of the function definition, omitting it will not bring in any -type inference. - -```ts -function f0() { // ❌ invalid - return 42 -} - -function f1(): number { // ✅ okay - return 42 -} -``` - -## Function Types and Expressions - -Function expressions could be created using *arrow functions*, quite like the ones in TypeScript. But the type of -functions adopt a different arrow symbol `->` to disambiguate itself from function expressions. - -```plaintext -const f: (x: number) -> number = x => x; -``` - -## Generic Functions - -Function definitions could be generic, as in TypeScript. - -```ts -function id(x: T): T { - return x -} -``` diff --git a/i18n/en-us/docusaurus-plugin-content-docs/current/handbook/object.md b/i18n/en-us/docusaurus-plugin-content-docs/current/handbook/object.md deleted file mode 100644 index f63e05b..0000000 --- a/i18n/en-us/docusaurus-plugin-content-docs/current/handbook/object.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 3 ---- - -# Object Types diff --git a/i18n/en-us/docusaurus-plugin-content-docs/current/handbook/oop.md b/i18n/en-us/docusaurus-plugin-content-docs/current/handbook/oop.md deleted file mode 100644 index 3988122..0000000 --- a/i18n/en-us/docusaurus-plugin-content-docs/current/handbook/oop.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 5 ---- - -# OOP diff --git a/i18n/en-us/docusaurus-plugin-content-docs/current/handbook/primitives.md b/i18n/en-us/docusaurus-plugin-content-docs/current/handbook/primitives.md deleted file mode 100644 index 66969a4..0000000 --- a/i18n/en-us/docusaurus-plugin-content-docs/current/handbook/primitives.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Primitive Types - -Following JavaScript primitive types are supported and compatible in RowScript: - -* [`string`], e.g. `"hello"` -* [`number`], e.g. `42` -* [`boolean`], i.e. `false` and `true` -* [`bigint`], e.g. `42n` - -[`string`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String - -[`number`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number - -[`boolean`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean - -[`bigint`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt - -## Builtin Operators - -Some of the famous ["thanks for inventing JavaScript"] overpowered operators are not allowed in RowScript. Operators -like `+`/`-` are only effective on arguments with the same type. - -```js -1 + 2 // ✅ - -1 + "123" // ❌ -``` - -["thanks for inventing JavaScript"]: https://www.reddit.com/r/ProgrammerHumor/comments/8srix1/thanks_brendan_for_giving_us_the_javascript - -## Unit - -There are **no** `null`, `undefined` and `void` in RowScript, due to the mess when they work together. Instead, we use a -new primitive type `unit`. It's quite like `void`, but you can actually define a variable with this type, which makes it -different. - -Values of type `unit` could be created using `()`, we call it "unit value". - -```ts -const a: unit = (); -``` - -Note that upon code generation, unit values would be translated into `undefined` for compatibility. diff --git a/i18n/en-us/docusaurus-plugin-content-docs/current/intro.md b/i18n/en-us/docusaurus-plugin-content-docs/current/intro.md deleted file mode 100644 index 94f15a0..0000000 --- a/i18n/en-us/docusaurus-plugin-content-docs/current/intro.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Overview - -RowScript is a new JavaScript dialect that aims to greatly improve the ergonomics for **2 types of web developers**: - -* **Application writers**: Users should write their apps with powerful tools, frameworks **and** a versatile type system -* **Library writers**: Users should write their libraries with less [type challenges], which are generally cluttering and - non-trivial - -With RowScript, you can write more extensible and scalable code using its tool and type system. - -[type challenges]: https://github.com/type-challenges/type-challenges diff --git a/i18n/en-us/docusaurus-plugin-content-docs/current/roadmap.md b/i18n/en-us/docusaurus-plugin-content-docs/current/roadmap.md deleted file mode 100644 index c65def5..0000000 --- a/i18n/en-us/docusaurus-plugin-content-docs/current/roadmap.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 5 ---- - -# Roadmap diff --git a/i18n/en-us/docusaurus-plugin-content-docs/current/why/_category_.json b/i18n/en-us/docusaurus-plugin-content-docs/current/why/_category_.json deleted file mode 100644 index 9cb7656..0000000 --- a/i18n/en-us/docusaurus-plugin-content-docs/current/why/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Why RowScript?", - "position": 4 -} diff --git a/i18n/en-us/docusaurus-plugin-content-docs/current/why/general.md b/i18n/en-us/docusaurus-plugin-content-docs/current/why/general.md deleted file mode 100644 index 7a57f07..0000000 --- a/i18n/en-us/docusaurus-plugin-content-docs/current/why/general.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -sidebar_position: 1 ---- - -# General Ideas - -There are several ideas that initially fuel our motivation to create RowScript, well, essentially just some quotes. - -## Totality - -> Total type theory really is adequate for general-purpose programming. -> -> -- Jon Sterling, [Make Three To Throw Away], WITS '22 - -By totality, every possible computation will be performed during compilation, and thanks to a dependent type system, -those computation results could feed as some useful type information. This enables our library writers to make better -frameworks, with less tricks and hacks, and most importantly, with a good and interactive **type debugging support**. - -[Make Three To Throw Away]: https://www.jonmsterling.com/slides/sterling-2022-wits.pdf - -## Universal Scripting - -> It makes sense to think of JavaScript as the universal scripting language. -> -> -- Ryan Dahl, [JavaScript Containers] - -JavaScript is everywhere, we target our code generation into it first instead of WebAssembly, since we believe in the -powerfulness of this universal language, unless it's aided by modern language tools. :) - -[JavaScript Containers]: https://tinyclouds.org/javascript_containers - -## Row Polymorphism - -> Row polymorphism can be a typed solution to JavaScript's prototype-based design. -> -> -- [玩火 (niltok)], from a group talk in 2021 - -At the very beginning, we tried experimenting with [row polymorphism] to model some interesting JavaScript code, that's -also the origin of the name "**Row**Script". We further developed the row polymorphic feature and more interesting stuff -to make the type system robust and versatile. - -It's worth noting that row polymorphism in RowScript is different from [that in PureScript]. Here, rows could be used to -create **extensible enumeration types**. - -[玩火 (niltok)]: https://github.com/niltok -[row polymorphism]: https://en.wikipedia.org/wiki/Row_polymorphism -[that in PureScript]: https://github.com/purescript/documentation/blob/master/language/Types.md#rows diff --git a/i18n/en-us/docusaurus-plugin-content-docs/current/why/research.md b/i18n/en-us/docusaurus-plugin-content-docs/current/why/research.md deleted file mode 100644 index ac138e5..0000000 --- a/i18n/en-us/docusaurus-plugin-content-docs/current/why/research.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Research Ideas - -:::caution - -Some academic stuff going on here, this page ought to contain hardcore content. - -::: diff --git a/i18n/en-us/docusaurus-plugin-content-pages/homepageFeatures.json b/i18n/en-us/docusaurus-plugin-content-pages/homepageFeatures.json index 1f20093..62c6cc7 100644 --- a/i18n/en-us/docusaurus-plugin-content-pages/homepageFeatures.json +++ b/i18n/en-us/docusaurus-plugin-content-pages/homepageFeatures.json @@ -1,14 +1,14 @@ { "friendlySyntax": { "title": "Friendly Syntax", - "description": "RowScript reuses most of the JavaScript syntax for friendliness, also influenced by other languages like TypeScript, Python and Rust." + "description": "RowScript reuses most of the JavaScript syntax for friendliness, also influenced by other languages like TypeScript, Rust and Python." }, "powerfulTypeSystem": { "title": "Super Powerful Type System", - "description": "Language features like dependent types, tagged union, OOP, interfaces (or \"traits\" in Rust, \"typeclasses\" in Haskell) and more are all supported." + "description": "Language features like dependent types, OOP, traits and more are all supported." }, "fastCompile": { "title": "Fast to Compile", "description": "RowScript compiler is written in Rust programming language and shipped via native binaries, it's stunningly fast." } -} \ No newline at end of file +} diff --git a/i18n/en-us/docusaurus-theme-classic/footer.json b/i18n/en-us/docusaurus-theme-classic/footer.json index e306dfb..c58cca7 100644 --- a/i18n/en-us/docusaurus-theme-classic/footer.json +++ b/i18n/en-us/docusaurus-theme-classic/footer.json @@ -15,6 +15,10 @@ "message": "Tour", "description": "The label of footer link with label=Tour linking to /docs/intro" }, + "link.item.label.Discussions": { + "message": "Discussions", + "description": "The label of footer link with label=Discussions linking to GitHub Discussions" + }, "link.item.label.Stack Overflow": { "message": "Stack Overflow", "description": "The label of footer link with label=Stack Overflow linking to https://stackoverflow.com/questions/tagged/rowscript" diff --git a/i18n/zh-cn/docusaurus-plugin-content-pages/homepageFeatures.json b/i18n/zh-cn/docusaurus-plugin-content-pages/homepageFeatures.json index 067fb9c..f5d53d1 100644 --- a/i18n/zh-cn/docusaurus-plugin-content-pages/homepageFeatures.json +++ b/i18n/zh-cn/docusaurus-plugin-content-pages/homepageFeatures.json @@ -1,14 +1,14 @@ { "friendlySyntax": { "title": "友好语法", - "description": "RowScript 大量借鉴了 JavaScript 的语法，使其更加友好，同时也受到了 TypeScript、Python 和 Rust 等其他语言的影响。" + "description": "RowScript 大量借鉴了 JavaScript 的语法，使其更加友好，同时也受到了 TypeScript、Rust 和 Python 等其他语言的影响。" }, "powerfulTypeSystem": { "title": "健壮的类型系统", - "description": "RowScript 支持包括依值类型、面向对象编程、接口（或在 Rust 中称为 \"Trait\"，在 Haskell 中称为 \"TypeClass\"）等多种前沿语言特性。" + "description": "RowScript 支持包括 dependent types、OOP、traits 等多种前沿语言特性。" }, "fastCompile": { "title": "快速编译", - "description": "RowScript 的编译器使用 Rust 语言编写，并通过原生二进制文件发布，拥有飞快的编译速度。" + "description": "RowScript 的编译器使用 Rust 语言编写，并通过原生二进制文件发布，拥有飞快的编译速度。" } } diff --git a/i18n/zh-cn/docusaurus-theme-classic/footer.json b/i18n/zh-cn/docusaurus-theme-classic/footer.json index 16d6dcb..9e7f493 100644 --- a/i18n/zh-cn/docusaurus-theme-classic/footer.json +++ b/i18n/zh-cn/docusaurus-theme-classic/footer.json @@ -15,6 +15,10 @@ "message": "指南", "description": "The label of footer link with label=Tour linking to /docs/intro" }, + "link.item.label.Discussions": { + "message": "讨论", + "description": "The label of footer link with label=Discussions linking to GitHub Discussions" + }, "link.item.label.Stack Overflow": { "message": "Stack Overflow", "description": "The label of footer link with label=Stack Overflow linking to https://stackoverflow.com/questions/tagged/rowscript"