Skip to content

Commit 1d07cfe

Browse files
committed
Update docs
Signed-off-by: anqurvanillapy <anqurvanillapy@gmail.com>
1 parent 472e654 commit 1d07cfe

37 files changed

+346
-484
lines changed

blog/2023-05-05-open-sourcing.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ npm install -D rowscript@latest
1212

1313
目前,编译器仅提供了以下模块:
1414

15-
* 核心语法:RowScript 核心的构建模块,如函数类型(Pi Type)
16-
* 内置功能:在代码中可访问但未提供文档的构建模块
17-
* 预置库:无需导入即可访问、配有详尽文档的构建模块
18-
* 标准库:通过导入来访问、与编译器本体一起打包提供的构建模块
15+
* 核心语法:RowScript 核心的构建模块,如函数类型(Pi Type)
16+
* 内置功能:在代码中可访问但未提供文档的构建模块
17+
* 预置库:无需导入即可访问、配有详尽文档的构建模块
18+
* 标准库:通过导入来访问、与编译器本体一起打包提供的构建模块

docs/01-intro.md

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# 概述
2+
3+
RowScript 是一种新的 JavaScript 方言,旨在大大改善两类 web 开发者的使用体验:
4+
5+
* **应用程序开发者**:开发者应该使用强大的工具、框架和灵活的类型系统来编写他们的应用程序
6+
* **库开发者**:开发者应该能够以较少的 [类型体操] 来编写他们的库,这些类型体操通常是杂乱无章且晦涩难懂的
7+
8+
通过使用 RowScript 的工具和类型系统,允许您编写更具可扩展性和足以胜任各种任务的代码。
9+
10+
除此之外,RowScript 还包含了许多保守同时又激进的语言特性。总结成一句话就是:
11+
12+
:::tip
13+
14+
RowScript:“完成 TypeScript 没法做的事,砍掉 JavaScript 不必要的特性。”
15+
16+
:::
17+
18+
[类型体操]: https://github.com/type-challenges/type-challenges
19+
20+
## 新语言,旧语法
21+
22+
RowScript 虽然是一门新的语言,但是它使用了大量的 JavaScript/TypeScript 语法,极大地降低了用户的学习负担。
23+
24+
即使是 JS/TS 中没有的语言特性,RowScript 同样重新利用了许多 JS/TS 的关键词和部分语法,使新的特性看起来相对不那么生涩。
25+
26+
例如,RowScript 中关于接口(interface)的语法:
27+
28+
<!-- @formatter:off -->
29+
30+
```ts
31+
interface ToString {
32+
toString(v: ToString): string;
33+
}
34+
35+
function getString<T>(n: T): string
36+
where T instanceof ToString
37+
{
38+
n.toString()
39+
}
40+
```
41+
42+
<!-- @formatter:on -->
43+
44+
新的用户也能很快地猜到,函数 `getString` 要求接收一个类型 `T`,并且要求 `T` 实现了接口
45+
`ToString`,使得函数内部可使用 `toString``n` 进行字符串转换。
46+
47+
## JS 对象、类、函数
48+
49+
JS 中的对象(object)、类(class)和函数(function)往往会产生使用上的分歧。
50+
51+
用户可以用对象的风格封装数据与方法。
52+
53+
```js
54+
const a = {
55+
n: 42,
56+
getN() {
57+
return this.n;
58+
}
59+
};
60+
```
61+
62+
最原始的函数风格,也是一种选择。
63+
64+
```js
65+
function B(n) {
66+
this.n = n;
67+
this.getN = function () {
68+
return this.n;
69+
}
70+
}
71+
72+
const b = new B(42);
73+
```
74+
75+
较新的类的方式,是另一种新的选择。
76+
77+
```js
78+
class C {
79+
constructor(n) {
80+
this.n = n;
81+
}
82+
83+
getN() {
84+
return this.n;
85+
}
86+
}
87+
88+
const c = new C(42);
89+
```
90+
91+
但是这三者都有各自的细微不同,不能轻易的互换,更不可能在 JS 层面得到很好的统一。
92+
93+
RowScript 中支持对象和类,但两者在生成出来的 JavaScript 代码中只是简单的对象,没有其他任何添加剂。
94+
95+
```ts
96+
class D {
97+
n: number;
98+
99+
getN(): number {
100+
this.n
101+
}
102+
}
103+
104+
const d = new D(42);
105+
```
106+
107+
编译后的 JS 代码:
108+
109+
```js
110+
const d = {n: 42};
111+
```
112+
113+
## Void、Null、Undefined、Never、Any、Unknown
114+
115+
JS/TS 中有许许多多令人匪夷所思的类型:
116+
117+
* `void`
118+
* `null`
119+
* `undefined`
120+
* `never`
121+
* `any`
122+
* `unknown`
123+
124+
而在 RowScript 中,这些类型由以下两个特性达成了统一:
125+
126+
* `unit` 类型:统一 `void``null``undefined``never`(相信我,在用户层面,用户并不需要关心 `never` 类型)
127+
* 带有类型擦除(type erasure)的泛型:取代 `any``unknown`
128+
129+
举个例子,TypeScript 中的 `any` 可能出现在程序的边界中:
130+
131+
```ts
132+
declare function foo(v: any);
133+
```
134+
135+
在 RowScript 中,使用泛型函数即可:
136+
137+
```ts
138+
function foo<T>(v: T);
139+
```
140+
141+
在代码生成阶段,泛型 `T` 会被自动擦除。
142+
143+
## JS/TS 令人痛苦的 union 类型
144+
145+
在 TypeScript 中 *narrow* 一个 union 类型通常是很痛苦的事情,这是因为你总需要引入奇怪的分支判断:
146+
147+
```ts
148+
function printId(id: number | string) {
149+
if (typeof id === "string") {
150+
console.log("Phew, it's a string...");
151+
}
152+
}
153+
```
154+
155+
那如果假设在编译期间还是无法判断 `id` 的具体类型呢?那么我们又要开始手工制造一个有标签(tagged)的 union 类型:
156+
157+
```ts
158+
type StringID = {
159+
str: string;
160+
type: 'string_id';
161+
}
162+
163+
type NumberID = Omit<StringID, 'type'> & {
164+
n: number;
165+
type: 'number_id';
166+
}
167+
168+
type ID = StringID | NumberID;
169+
```
170+
171+
此时你会意识到,虽然 TS 已经提供了所谓的实用类型(utility types)降低了一些噪音,但是 `Omit`、不成文的 `type`
172+
成员作为规范、手动将小写的类型名字作为标签等等,过度的模板代码(boilerplate)依旧存在。
173+
174+
在 RowScript 中,枚举(enum)类型很好地解决了这个问题:
175+
176+
<!-- @formatter:off -->
177+
178+
```ts
179+
type ID = [ StringID(string) | NumberID(number) ];
180+
```
181+
182+
<!-- @formatter:on -->
183+
184+
RowScript 的枚举类型和 PureScript、Elm、Haskell 等函数式编程语言中的 ADT(algebraic data types)稍有不同,和 Rust
185+
的枚举类型也有差异,可在后续章节中深入探索枚举类型。
186+
187+
## JS/TS 对可变参数缺少类型支持
188+
189+
JS 中最常用的函数莫过于 `console.log`,但是这一函数在 TS 中有着令人尴尬的类型:
190+
191+
```ts
192+
declare function log(...data: any[]): void;
193+
```
194+
195+
虽然 TS 中拥有 [可变元组类型(variadic tuples)],但这个类型没法和可变参数(variadic)产生互动。
196+
197+
在 RowScript 中,可变参数通过泛型来实现,但是有一定的功能限制。RowScript 中的 `console.log` 类型:
198+
199+
```ts
200+
function log<Args>(...: Args);
201+
```
202+
203+
[可变元组类型(variadic tuples)]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-0.html#variadic-tuple-types
204+
205+
## 更多语言特性
206+
207+
除此之外,RowScript 还提供了如同行多态(row polymorphism)、静态反射(static reflection)、操作符重载、副作用类型(effect
208+
types)等等十分时髦的新特性,跟着这本指南继续往下探索吧!

docs/getting-started.md renamed to docs/02-getting-started.md

Lines changed: 7 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,4 @@
1-
---
2-
sidebar_position: 2
3-
---
4-
5-
# 入门指南
1+
# 安装与上手
62

73
## 创建工作文件夹
84

@@ -22,21 +18,19 @@ npm init
2218
npm install -D rowscript
2319
```
2420

25-
就这样完成了
21+
这样就完成了
2622

27-
* 不需要 config.json 或其他文件
28-
* 无需向 package.json 文件添加新字段以免影响其结构
23+
* 不需要 `config.json` 或其他文件
24+
* 无需向 `package.json` 文件添加新字段以免影响其结构
2925

3026
它的运行就是如此简洁,所有的默认配置均适用,无需额外调整。
3127

3228
## 你好... 世界?
3329

34-
创建一个名为 `hello.rows` 的文件:
30+
创建一个名为 `hello.rows` 的文件,内容为
3531

3632
```ts
37-
import console;
38-
39-
console::log("Hello, world!");
33+
console.log("Hello, world!");
4034
```
4135

4236
运行编译器:
@@ -54,4 +48,4 @@ $ node ./dist/index.mjs
5448
Hello, world!
5549
```
5650

57-
啊哈,你只用了 5 分钟就掌握了这门语言⏰!
51+
啊哈,你只用了 5 分钟就掌握了这门语言 ⏰!

docs/03-definitions.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# 定义
2+
3+
类似 JavaScript,一个 RowScript 程序的顶部包含任意数量的定义(definitions)。
4+
5+
## 函数定义
6+
7+
RowScript 中的函数定义(functions)与 JS/TS 相似。
8+
9+
```ts
10+
function f() {
11+
}
12+
```
13+
14+
你需要明确指定函数定义的返回类型,如果不明确指定返回类型,将不会进行任何类型推断,而是认为函数返回的是 `unit` 类型。
15+
16+
```ts
17+
function f0() { // ❌ invalid
18+
42
19+
}
20+
21+
function f1(): number { // ✅ okay
22+
42
23+
}
24+
```
25+
26+
用户不需要在函数的最后加上 `return` 语句。如果省略返回值,系统自动将其视为 `unit` 类型。
27+
28+
```ts
29+
function f0(): number {
30+
42
31+
}
32+
33+
function f1(): unit {
34+
const n = f0();
35+
}
36+
```
37+
38+
### 函数类型和表达式
39+
40+
可以使用 *箭头函数* 创建函数表达式,这与 TypeScript 中的非常相似。
41+
42+
```ts
43+
const f: (x: number) => number = x => x;
44+
```
45+
46+
### 泛型函数
47+
48+
函数定义可以是泛型的,如同 TypeScript。
49+
50+
```ts
51+
function id<T>(x: T): T {
52+
x
53+
}
54+
```

docs/04-variables.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# 变量

docs/05-control.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# 控制流

docs/06-everyday-types.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# 常用类型
2+
3+
## 基本类型
4+
5+
RowScript 支持并兼容以下 JavaScript 基本类型:
6+
7+
* [`string`], 例如 `"hello"`
8+
* [`number`], 例如 `42`
9+
* [`boolean`], 即 `false``true`
10+
* [`bigint`], 例如 `42n`
11+
12+
[`string`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String
13+
14+
[`number`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number
15+
16+
[`boolean`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean
17+
18+
[`bigint`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt
19+
20+
## 内置操作符
21+
22+
RowScript 不支持一些在 JavaScript 中著名的 [“感谢发明了 JavaScript”] 梗、功能过于“强大”的操作符。比如,`+`/`-`
23+
操作符仅适用于类型相同的参数。
24+
25+
```js
26+
1 + 2 //
27+
28+
1 + "123" //
29+
```
30+
31+
[“感谢发明了 JavaScript”]: https://www.reddit.com/r/ProgrammerHumor/comments/8srix1/thanks_brendan_for_giving_us_the_javascript
32+
33+
## Unit 类型
34+
35+
在 RowScript 中,我们决定不采用 `null``undefined`
36+
`void`,原因是它们一旦混合使用便容易引发混乱。作为替代,我们引入了一种名为 `unit` 的新基本类型。这种类型与 `void`
37+
类似,不过区别在于您实际上可以声明一个此类型的变量,这一特性让它独树一帜。
38+
39+
可以使用 `()` 创建 unit 类型的值,我们称之为“unit value”。
40+
41+
```ts
42+
const a: unit = ();
43+
```
44+
45+
在将代码编译到 JavaScript 时,unit value 会被转换为 `undefined` 以保证兼容性。

docs/handbook/_category_.json

Lines changed: 0 additions & 4 deletions
This file was deleted.

docs/handbook/enum.md

Lines changed: 0 additions & 5 deletions
This file was deleted.

0 commit comments

Comments
 (0)