Skip to content

Commit 2afd9b3

Browse files
yexi-xfyexi-xf
committed
feat: 文档
1 parent 9e1915e commit 2afd9b3

34 files changed

+5826
-1
lines changed

‎docs/specification/basic.en.md

+731
Large diffs are not rendered by default.

‎docs/specification/basic.zh.md

+728
Large diffs are not rendered by default.

‎docs/specification/category/get.en.md

+81
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
title: Find Node
3+
order: 1
4+
---
5+
6+
All node acquisition operations will return a new AST instance. The instance may contain multiple AST node paths, such as `find()`, `siblings()`, etc. The instance returned by some APIs will only have one AST node path. , such as `next()`
7+
###AST.find(selector, options)
8+
9+
| Input parameters | | Description | Type | Default value |
10+
| --- | --- | --- | --- | --- |
11+
| `selector` | | Code selector, which can be code or can replace part of the code with wildcards | string | None |
12+
| `options` | `ignoreSequence` | Whether to ignore the sequence when matching <br>The case of ignoring the sequence: `{a:$_$}` matches `{b:1, a:2}`<br>It needs to be in strict order Matching cases: `function($_$, b){}` matches `function(a, b){}` | boolean | false |
13+
| | `parseOptions` | same as `parseOptions` of constructor | | |
14+
15+
When there is a `$_$` wildcard in the selector, there is a `match` attribute in the returned AST instance, that is, the AST node matched by `$_$`
16+
For example: `$('var a = 1').find('var $_$ = $_$')`, the resulting structure is:
17+
18+
<img style="width:800px; display:block" src="https://alp.alicdn.com/1614534004290-2222-1032.png"/>
19+
20+
21+
The corresponding `match` structure is:
22+
23+
````
24+
[{
25+
structure: { type: 'Identifier', name: 'a' ... } : Node,
26+
value: 'a'
27+
}, {
28+
structure: { type: 'NumericLiteral', value: 1 ... } : Node,
29+
value: '1'
30+
}]
31+
````
32+
33+
34+
35+
### .parent(level)
36+
get a parent node
37+
38+
| Input parameters | Description | Type | Default value |
39+
| --- | --- | --- | --- |
40+
| `level` | nth level parent element from inside to outside | number | 0 |
41+
42+
43+
44+
### .parents()
45+
get all parent sections
46+
47+
### .root()
48+
Get the root node, for js it is a node with `type` as 'File', for html it is a node with `nodeType` as 'document'
49+
Usually, after operating the AST, you need to get the root element and then output it
50+
51+
52+
### .siblings()
53+
Get all sibling nodes
54+
55+
### .prev()
56+
get previous node
57+
58+
### .prevAll()
59+
Get the sibling node before the current node
60+
61+
### .next()
62+
get the next node
63+
64+
### .nextAll()
65+
Get the sibling nodes after the current node
66+
67+
### .each(callback)
68+
Executes a function with each matched element as context.
69+
70+
| Input parameters | Description | Type | Default value |
71+
| --- | --- | --- | --- |
72+
| `callback` | The function to be executed for each matched element<br>When executing the function, it will pass the current node `node` and `index` to the function | function | none |
73+
74+
### .eq(index)
75+
Get the Nth AST object in the current chain operation
76+
77+
| Input parameters | Description | Type | Default value |
78+
| --- | --- | --- | --- |
79+
| `index` | The position of the AST object to be retrieved | number | 0 |
80+
81+
Translated with www.DeepL.com/Translator (free version)

‎docs/specification/category/get.zh.md

+105
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
title: 获取节点
3+
order: 1
4+
---
5+
6+
所有的节点获取操作都会返回一个新的AST实例，实例中可能挂了多个AST节点路径，如通过`find()`、`siblings()`获取的实例，也有某些api返回的实例只存在一个AST节点路径，如`next()`
7+
### AST.find(selector, options)
8+
9+
| 入参 | | 说明 | 类型 | 默认值 |
10+
| --- | --- | --- | --- | --- |
11+
| `selector【必传】` | | 代码选择器，可以是代码，也可以将代码中的部分内容替换为通配符 | string <br> array | 无 |
12+
| `options` | `ignoreSequence` | 匹配时是否忽略顺序<br>忽略顺序的情况：`{a:$_$}`匹配`{b:1, a:2}`<br>需要严格按照顺序匹配的情况：`function($_$, b){}` 匹配`function(a, b){}` | boolean | false |
13+
| | `parseOptions` | 同构造函数的`parseOptions` | | |
14+
15+
#### 对于match的解释
16+
当selector中存在 `$_$` 通配符时，返回的AST实例中存在 `match` 属性，也就是被 `$_$` 匹配到的AST节点
17+
如：`$('var a = 1').find('var $_$1 = $_$2')`，得到的结构为：
18+
19+
<img style="width:800px; display:block" src="https://alp.alicdn.com/1619218197857-1876-1154.png"/>
20+
21+
22+
其中对应的 `match` 结构为：
23+
24+
```
25+
{
26+
1:[{
27+
node: { type: 'Identifier', name: 'a' ... },
28+
value: 'a'
29+
}],
30+
2: [{
31+
node: { type: 'NumericLiteral', value: 1 ... },
32+
value: '1'
33+
}]
34+
}
35+
```
36+
37+
`$_$1` 匹配到的在 `match[1]` 中，`$_$2` 匹配到的结果在 `match[2]` 中
38+
39+
#### vue sfc的特殊处理
40+
vue single file component同时包含template和script，转换时需要区分处理，做法如下：
41+
42+
```javascript
43+
$(input, { parseOptions: { language: 'vue' } })
44+
.find('<template></template>')
45+
...... // 对template的处理
46+
.root() // 拿到sfc根节点
47+
.find(`<script></script>`)
48+
...... // 对script的处理
49+
.root()
50+
.generate()
51+
```
52+
53+
54+
### .parent(level)
55+
获取某个父节点
56+
57+
| 入参 | 说明 | 类型 | 默认值 |
58+
| --- | --- | --- | --- |
59+
| `level` | 自内向外第n层父元素 | number | 0 |
60+
61+
62+
63+
### .parents()
64+
获取所有父节
65+
66+
### .root()
67+
获取根节点
68+
- 对于js来说根节点是`type`为'File'的节点
69+
- 对于html来说根节点是`nodeType`为'document'的节点
70+
- 对于vue来说 `root()`返回的是完整的sfc节点
71+
- 在template内部操作之后想要获取template的根节点，则调用：`.root('template')`
72+
- 在script内部操作之后想要获取template的根节点，则调用：`.root('script')`
73+
示例如下：
74+
75+
通常对AST进行操作之后需要调用root之后再generate，才是完整的转换后代码
76+
77+
78+
### .siblings()
79+
获取所有兄弟节点
80+
81+
### .prev()
82+
获取前一个节点
83+
84+
### .prevAll()
85+
获取当前节点之前的同级节点
86+
87+
### .next()
88+
获取后一个节点
89+
90+
### .nextAll()
91+
获取当前节点之后的同级节点
92+
93+
### .each(callback)
94+
以每一个匹配的元素作为上下文来执行一个函数。
95+
96+
| 入参 | 说明 | 类型 | 默认值 |
97+
| --- | --- | --- | --- |
98+
| `callback` | 对于每个匹配的元素所要执行的函数<br>执行函数时，会给函数传递当前节点`node`和`index` | function | 无 |
99+
100+
### .eq(index)
101+
获取当前链式操作中第N个AST对象
102+
103+
| 入参 | 说明 | 类型 | 默认值 |
104+
| --- | --- | --- | --- |
105+
| `index` | 需要获取的AST对象的位置 | number | 0 |

‎docs/specification/category/instance.en.md

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
title: AST Instance
3+
order: 0
4+
---
5+
6+
Call `$()` to construct a piece of code or an ast node as an instance of GoGoCode's AST instance
7+
8+
### $(code, options)
9+
10+
| Parameters | | Description | Type | Example |
11+
| --- | --- | --- | --- | --- |
12+
| `code` | | The code or AST node to be instantiated | string NodePath Node | `'var a = 1'` |
13+
| `options` | `parseOptions` | When parsing js, it is exactly the same as the options of babel/parse<br>When parsing html and vue, you need to pass in language | object | `{ plugins: ['jsx'] }`<br > ` { language: 'html' } ` <br> ` { language: 'vue' } ` |
14+
| | `astFragment` | ast node to be inserted into the code | Node | `{ content: astNode }` |
15+
| | `isProgram` | Whether to return the complete ast<br>js The outermost node of the complete ast is of type File <br>html complete ast is of type document | Boolean | Default is true |
16+
```typescript
17+
$('var a = 1');
18+
19+
$(astNode);
20+
21+
$('<div></div>', {
22+
parseOption: { plugins: ['jsx'] },
23+
});
24+
25+
$(`Alert.show({content: $content$ , type: $type$ })`, {
26+
astFragment: {
27+
content: contentNode,
28+
type: typeNode,
29+
},
30+
});
31+
```
32+
33+
### $.loadFile(path, options)
34+
35+
Same role as the constructor, the first input can be a file path, directly construct the contents of the file to AST instance.
36+
37+
### AST instance Detail
38+
39+
The AST instance contains all chain-callable APIs, which will be described in the next section.
40+
41+
Now let's introduce two concepts, `Node` and `NodePath`
42+
43+
#### Node
44+
45+
A separate AST node with the following structure, with different statements corresponding to different types and attributes
46+
47+
<img style="width:500px; display:block" src="https://alp.alicdn.com/1612753991244-1062-596.jpg"/>
48+
49+
#### NodePath
50+
51+
Current ast node structure and its path information
52+
53+
#### Attributes on AST instance
54+
55+
- 0-n
56+
57+
An AST instance can store multiple ast elements, obtained by integer index
58+
59+
| Parameters | | Description |
60+
| -------------- | -------- | -------------------------------------------------------- |
61+
| `nodePath` | `node` | ast node |
62+
| `parent` | the parent of the ast node |
63+
| `parseOptions` | | The parsing parameters passed in when constructing the AST instance |
64+
| `match` | | the nodes in the complete node that are matched by the wildcard |
65+
| `node` | node structure, same as node |
66+
| `value` | The simplified node structure, or the string value if the node is a string type |
67+
68+
- node
69+
70+
Get the first ast node on an AST instance
71+
72+
- match
73+
74+
Get the node matched by the wildcard in the first ast node on the AST instance, as explained in `.find()`

‎docs/specification/category/instance.zh.md

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: AST实例
3+
order: 0
4+
---
5+
6+
调用 `$()` 即可将一段代码或一个 ast 节点构造为 GoGoCode 的核心 AST 实例。支持 js（包括 jsx）、html、vue
7+
8+
### $(code, options)
9+
10+
| 入参 | | 说明 | 类型 | 举例 |
11+
| --- | --- | --- | --- | --- |
12+
| `code` | | 需要被实例化的代码或AST节点 | string NodePath Node | `'var a = 1'` |
13+
| `options` | `parseOptions` | 解析js时，它与babel/parse的options完全一致<br>解析html、vue时需要传入language | object | `{ plugins: ['jsx'] }`<br> ` { language: 'html' } ` <br> ` { language: 'vue' } ` |
14+
| | `astFragment` | 需要插入到代码中的ast节点 | Node | `{ content: astNode }` |
15+
| | `isProgram` | 是否需要返回完整ast<br>js的完整ast最外层节点是File类型<br>html完整ast是document类型 | Boolean | 默认为true | |
16+
17+
```typescript
18+
$('var a = 1');
19+
20+
$(astNode);
21+
22+
$('<div></div>', {
23+
parseOption: { plugins: ['jsx'] },
24+
});
25+
26+
$(`function demo() { $_$content$_$ }`, {
27+
astFragment: {
28+
content: $('var a = 1', { isProgram: false }).node,
29+
},
30+
});
31+
```
32+
33+
### $.loadFile(path, options)
34+
35+
36+
37+
与构造函数作用相同，第一个入参可以是文件路径，直接将文件内容实例化
38+
39+
40+
41+
### AST 实例详细介绍
42+
43+
44+
45+
AST 实例包含所有可链式调用的 API，将在下一节一一介绍
46+
47+
先介绍两个概念，`Node`和`NodePath`
48+
49+
50+
51+
#### Node
52+
53+
独立的 ast 节点，结构如下，不同的语句对应不同的 type 和属性。所有的代码转换都是靠对某个 Node 中属性的修改
54+
<img style="width:500px; display:block" src="https://alp.alicdn.com/1612753991244-1062-596.jpg"/>
55+
56+
57+
58+
#### NodePath
59+
60+
包含当前 ast 节点结构及其路径信息，一般不需要直接操作
61+
62+
63+
64+
#### AST 实例上的属性
65+
66+
- 0-n
67+
一个 AST 实例可以挂多个 ast NodePath，通过整数索引获取
68+
69+
| 参数 | | 说明 |
70+
| -------------- | -------- | -------------------------------------------------------- |
71+
| `nodePath` | `node` | ast 节点 |
72+
| | `parent` | ast 节点的父节点 |
73+
| `parseOptions` | | 构造 AST 实例时传入的解析参数 |
74+
| `match` | | 完整节点中被通配符匹配到的节点 |
75+
| | `node` | 节点结构，同 node |
76+
| | `value` | 简化后的节点结构，如果节点是字符串类型，则直接是字符串值 |
77+
78+
- length
79+
80+
返回匹配到 Nodepath 的个数
81+
82+
- node
83+
84+
获取 AST 实例上的第一个 ast 节点
85+
86+
- match
87+
88+
获取 AST 实例上的第一个 ast 节点中被通配符匹配到的节点，match 的具体解释见`.find()`

0 commit comments

Comments
 (0)