@befe/demo-lino 0.0.1 → 0.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +16 -0
- package/README.md +11 -4
- package/docs/syntax.md +165 -0
- package/package.json +4 -2
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# 发版记录
|
|
2
|
+
|
|
3
|
+
本文件随包发布,记每一版改了什么;语法细节见 `docs/syntax.md`。
|
|
4
|
+
|
|
5
|
+
## 0.0.2
|
|
6
|
+
|
|
7
|
+
- 随包附带文档:`docs/syntax.md`(语法说明,示例由测试逐个核对)与本文件
|
|
8
|
+
- README 不再引用包外的文档,补外网安装方式
|
|
9
|
+
- 代码与 0.0.1 相同,语法行为不变
|
|
10
|
+
|
|
11
|
+
## 0.0.1
|
|
12
|
+
|
|
13
|
+
- 首版:lino 文本与 JSON 互转
|
|
14
|
+
- 库函数 `parse`、`stringify`,错误类 `ParseError`,类型 `LinoConf`、`LinoValue`、`StringifyOptions`、`LinoWarning`
|
|
15
|
+
- 命令 `lino to-json`、`lino from-json`、`lino check`
|
|
16
|
+
- 运行要求 bun >= 1.4.2;内网 registry 与 npmjs 都已发布
|
package/README.md
CHANGED
|
@@ -3,20 +3,26 @@
|
|
|
3
3
|
lino 配置格式的原型包:lino 文本与 JSON 互转的解析器、生成器,外加一个 `lino` 命令。
|
|
4
4
|
|
|
5
5
|
- `demo-` 前缀表示原型,语法还在对齐中
|
|
6
|
-
-
|
|
6
|
+
- 文档都随包发布,装包后在 `node_modules/@befe/demo-lino/` 下就能读
|
|
7
|
+
- `README.md`:安装、API、CLI、退出码、已知限制(本文件)
|
|
8
|
+
- `docs/syntax.md`:语法说明,每种写法配解析结果,示例由测试逐个核对
|
|
9
|
+
- `CHANGELOG.md`:每一版改了什么
|
|
7
10
|
|
|
8
11
|
## 安装
|
|
9
12
|
|
|
10
|
-
-
|
|
13
|
+
- 内网 registry 与 npmjs 都有发布;运行要求 bun(>= 1.4.2),包里直接是 `.ts` 源码,没有给 node 用的构建产物
|
|
11
14
|
- 安装
|
|
12
15
|
|
|
13
16
|
```sh
|
|
17
|
+
# 内网
|
|
14
18
|
bun add @befe/demo-lino --registry http://registry.npm.baidu-int.com
|
|
19
|
+
# 外网
|
|
20
|
+
bun add @befe/demo-lino --registry https://registry.npmjs.org
|
|
15
21
|
```
|
|
16
22
|
|
|
17
23
|
- 版本口径:`0.0.x` 不承诺兼容
|
|
18
24
|
- 按 semver,`^0.0.1` 只匹配 `0.0.1`,升级要手动改版本号
|
|
19
|
-
-
|
|
25
|
+
- 每次升级都先看 `CHANGELOG.md` 里的变化
|
|
20
26
|
- 使用方是 TypeScript 项目时,`tsconfig.json` 要用 `"moduleResolution": "Bundler"`
|
|
21
27
|
- 包里发的是 `.ts` 源码,包内相对 import 不带后缀(如 `./parse`)
|
|
22
28
|
- 用 `NodeNext` / `Node16` 会对这些 import 报 TS2835(要求写明 `.js` 后缀)
|
|
@@ -106,7 +112,8 @@ lino check --from-json conf.json
|
|
|
106
112
|
|
|
107
113
|
## 开发
|
|
108
114
|
|
|
109
|
-
- 目录:`src/` 是库,`bin/lino.ts` 是 CLI,`test/` 是测试与夹具,`bench/` 是基准;发包只带 `src/`、`bin/`、`README.md`
|
|
115
|
+
- 目录:`src/` 是库,`bin/lino.ts` 是 CLI,`docs/` 是随包文档,`test/` 是测试与夹具,`bench/` 是基准;发包只带 `src/`、`bin/`、`docs/`、`README.md`、`CHANGELOG.md`
|
|
116
|
+
- 改了 `docs/syntax.md` 的示例或语法实现,跑 `bun test test/docs.test.ts` 核对两边一致
|
|
110
117
|
- 常用命令
|
|
111
118
|
|
|
112
119
|
```sh
|
package/docs/syntax.md
ADDED
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
# lino 语法(0.0.1)
|
|
2
|
+
|
|
3
|
+
本文件随包发布,写的是 0.0.1 实际实现的行为。每个 `lino` 代码块后面紧跟的 `json` 代码块就是它解析出来的结果,测试 `test/docs.test.ts` 会逐对核对,文档与实现不会悄悄走样。
|
|
4
|
+
|
|
5
|
+
## 一行能是什么
|
|
6
|
+
|
|
7
|
+
- 行首符号决定这一行是什么,缩进决定层级
|
|
8
|
+
- `* 键: 值`:字符串字段,值原样
|
|
9
|
+
- `* 键 = 值`:类型字段,认数字、`true` / `false`、`null`、`[]`、`{}`、带引号的字符串
|
|
10
|
+
- `* 键:`:值在下一层;下面挂 `*` 是对象,挂 `-` / `+` 是多行文本,什么都不挂是空字符串
|
|
11
|
+
- `* $$xxx`:预设字段,解析时跳过
|
|
12
|
+
- `* // …`:注释,只在对象里有效
|
|
13
|
+
- `- xxx`、`+ xxx`:多行文本的行,只出现在 `* 键:` 下面
|
|
14
|
+
- 空行与只有空白的行:忽略
|
|
15
|
+
- 符号后面必须跟一个空格(或直接行尾),只吃掉这一个空格
|
|
16
|
+
|
|
17
|
+
```lino
|
|
18
|
+
* $$type
|
|
19
|
+
* name: Mary
|
|
20
|
+
* age = 12
|
|
21
|
+
* skills = []
|
|
22
|
+
* : dance
|
|
23
|
+
* : sing
|
|
24
|
+
* address:
|
|
25
|
+
* city: 杭州
|
|
26
|
+
* intro:
|
|
27
|
+
- 第一行
|
|
28
|
+
- 第二行
|
|
29
|
+
* empty = {}
|
|
30
|
+
* // 注释写在对象里
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
```json
|
|
34
|
+
{
|
|
35
|
+
"name": "Mary",
|
|
36
|
+
"age": 12,
|
|
37
|
+
"skills": ["dance", "sing"],
|
|
38
|
+
"address": { "city": "杭州" },
|
|
39
|
+
"intro": "- 第一行\n- 第二行",
|
|
40
|
+
"empty": {}
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## 字符串字段 `* 键: 值`
|
|
45
|
+
|
|
46
|
+
- 只按第一个 `:` 切,后面的冒号、`=`、`//`、引号都算值的内容,不用转义
|
|
47
|
+
- 值一律是字符串,不做类型推断:`age: 12` 得到 `"12"`
|
|
48
|
+
- 引号不会被剥掉;冒号后可以不带空格
|
|
49
|
+
- 已经有值的行下面再挂子项算错误
|
|
50
|
+
|
|
51
|
+
```lino
|
|
52
|
+
* url: http://x:9000
|
|
53
|
+
* says: "hi"
|
|
54
|
+
* age: 12
|
|
55
|
+
* name:Mary
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
```json
|
|
59
|
+
{ "url": "http://x:9000", "says": "\"hi\"", "age": "12", "name": "Mary" }
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## 类型字段 `* 键 = 值`
|
|
63
|
+
|
|
64
|
+
- 只认这些,认不出就报错,不会退回字符串
|
|
65
|
+
- 数字:整数、小数、指数(`1e3`)、负数
|
|
66
|
+
- `true` / `false`(只认小写)、`null`
|
|
67
|
+
- `[]` 数组、`{}` 空对象
|
|
68
|
+
- 带引号的字符串:首尾同一对 `"` 或 `'`,剥引号并解转义 `\"` `\'` `\\` `\n` `\t`
|
|
69
|
+
- 带引号的写法只在必要时用,比如值首尾有空白
|
|
70
|
+
|
|
71
|
+
```lino
|
|
72
|
+
* port = 80
|
|
73
|
+
* ratio = 1.5e3
|
|
74
|
+
* offset = -2
|
|
75
|
+
* debug = false
|
|
76
|
+
* removed = null
|
|
77
|
+
* padded = " a "
|
|
78
|
+
* quoted = 'it\'s'
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
```json
|
|
82
|
+
{ "port": 80, "ratio": 1500, "offset": -2, "debug": false, "removed": null, "padded": " a ", "quoted": "it's" }
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## 数组 `* 键 = []`
|
|
86
|
+
|
|
87
|
+
- 子项缩进一层,一项一行,键位留空
|
|
88
|
+
- `* : 值`:字符串项,原样
|
|
89
|
+
- `* = 值`:数字、布尔、`null`、带引号的字符串
|
|
90
|
+
- `* = []`:嵌套数组,下面再挂子项
|
|
91
|
+
- `* :` 下面挂 `* 键: 值`:对象项;`* = {}`:空对象项
|
|
92
|
+
- 数字项必须写 `=`:`* : 12` 读回来是字符串 `"12"`
|
|
93
|
+
- 数组里不能写注释:`* // x` 会报错,`* : // x` 是字符串 `"// x"`
|
|
94
|
+
|
|
95
|
+
```lino
|
|
96
|
+
* items = []
|
|
97
|
+
* : web
|
|
98
|
+
* = 1
|
|
99
|
+
* = true
|
|
100
|
+
* = []
|
|
101
|
+
* : nested
|
|
102
|
+
* :
|
|
103
|
+
* name: obj
|
|
104
|
+
* = {}
|
|
105
|
+
* none = []
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
```json
|
|
109
|
+
{ "items": ["web", 1, true, ["nested"], { "name": "obj" }, {}], "none": [] }
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## 对象与缩进
|
|
113
|
+
|
|
114
|
+
- 对象写 `* 键:`,下面缩进一层挂字段;没有字段的空对象才写 `= {}`
|
|
115
|
+
- 缩进必须是偶数个空格,同一层宽度一致,子层比父层深;行首的 tab 按两格算
|
|
116
|
+
- 层数不限
|
|
117
|
+
|
|
118
|
+
```lino
|
|
119
|
+
* server:
|
|
120
|
+
* host: 0.0.0.0
|
|
121
|
+
* port = 8080
|
|
122
|
+
* tls:
|
|
123
|
+
* enabled = false
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
```json
|
|
127
|
+
{ "server": { "host": "0.0.0.0", "port": 8080, "tls": { "enabled": false } } }
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
## 多行文本 `-` / `+`
|
|
131
|
+
|
|
132
|
+
- 用法:`* 键:` 下面挂 `-` 行和 `+` 行,行与行之间用 `\n` 连起来
|
|
133
|
+
- `-` 是大纲行:`- ` 连符号一起进值
|
|
134
|
+
- `+` 是续行:只有文本进值,`+ ` 不进
|
|
135
|
+
- 层级按缩进算,以第一行的缩进为基准,每两格一层,每层在值里补两个空格
|
|
136
|
+
- 块里有 `-` 时,`+` 行在层级缩进外再补两格,文字与 `- ` 后面的内容对齐
|
|
137
|
+
- 整块都是 `+` 时不补任何缩进,就是普通的多行文本
|
|
138
|
+
- 多条 `-` 不构成数组,数组必须写 `= []`
|
|
139
|
+
|
|
140
|
+
```lino
|
|
141
|
+
* outline:
|
|
142
|
+
- 第一层
|
|
143
|
+
- 第二层
|
|
144
|
+
+ 第二层的续行
|
|
145
|
+
* plain:
|
|
146
|
+
+ 第一行
|
|
147
|
+
+ 第二行
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
```json
|
|
151
|
+
{ "outline": "- 第一层\n - 第二层\n 第二层的续行", "plain": "第一行\n第二行" }
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
## 报错
|
|
155
|
+
|
|
156
|
+
- 不合语法时 `parse` 抛 `ParseError`,CLI 打 `解析失败:…` 并退出 1;只报第一处错误
|
|
157
|
+
- 常见报错(`message` 原文)
|
|
158
|
+
- `第 3 行:缩进必须是偶数个空格,这里是 1 个`
|
|
159
|
+
- `第 2 行:认不出这一行:…`:行首不是 `*` / `-` / `+`,或符号后没有空格
|
|
160
|
+
- `第 1 行:这一项已经有值「demo」,下面不能再挂子项`
|
|
161
|
+
- `第 1 行:= 后面只认数字 / true / false / null / [] / {} / 带引号的字符串:abc`
|
|
162
|
+
- `第 3 行:数组项要写成「* : 值」或「* = 值」:…`
|
|
163
|
+
- `第 2 行:同一层的缩进必须一致:…`
|
|
164
|
+
- `第 4 行:没有 : 或 = 分隔符:…`
|
|
165
|
+
- 已知限制见 `README.md` 的「已知限制」一节
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@befe/demo-lino",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.2",
|
|
4
4
|
"description": "lino 配置格式原型:lino 文本与 JSON 互转的解析器、生成器和 lino 命令行",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"exports": {
|
|
@@ -15,7 +15,9 @@
|
|
|
15
15
|
"files": [
|
|
16
16
|
"src",
|
|
17
17
|
"bin",
|
|
18
|
-
"
|
|
18
|
+
"docs",
|
|
19
|
+
"README.md",
|
|
20
|
+
"CHANGELOG.md"
|
|
19
21
|
],
|
|
20
22
|
"scripts": {
|
|
21
23
|
"typecheck": "tsc --noEmit",
|