Skip to content

Commit e494e00

Browse files
committed
docs: improve and update README
1 parent 970bf4e commit e494e00

File tree

2 files changed

+18
-44
lines changed

2 files changed

+18
-44
lines changed

README-zh_CN.md

Lines changed: 2 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ yarn add dt-sql-parser
5353
<br/>
5454

5555
## 使用
56-
在开始使用前,需要先了解基本的使用方式`dt-sql-parser` 为不同类型的 SQL分别提供相应的 SQL Parser 类:
56+
在开始使用前,需要先了解基本用法`dt-sql-parser` 为不同类型的 SQL 分别提供相应的 SQL Parser 类:
5757
```javascript
5858
import { GenericSQL, FlinkSQL, SparkSQL, HiveSQL, PLSQL, PostgresSQL, TrinoSQL } from 'dt-sql-parser';
5959
```
@@ -65,8 +65,6 @@ const parser = new GenericSQL();
6565

6666
下文中的使用示例将使用 `GenericSQL`,其他 SQL 类型的 Parser 使用方式与`GenericSQL` 相同。
6767

68-
<br/>
69-
7068
### 语法校验(Syntax Validation)
7169
```javascript
7270
import { GenericSQL } from 'dt-sql-parser';
@@ -112,8 +110,6 @@ console.log(errors);
112110

113111
先实例化 Parser 对象,然后使用 `validate` 方法对 SQL 语句进行校验,如果校验失败,则返回一个包含 `error` 信息的数组。
114112

115-
<br/>
116-
117113
### 词法分析(Tokenizer)
118114

119115
必要场景下,可单独对 SQL 语句进行词法分析,获取所有的 Tokens 对象:
@@ -143,8 +139,6 @@ console.log(tokens)
143139
*/
144140
```
145141

146-
<br/>
147-
148142
### 访问者模式(Visitor)
149143

150144
使用 Visitor 模式访问 AST 中的指定节点
@@ -180,8 +174,6 @@ TableName user1
180174

181175
> 提示:使用 Visitor 模式时,节点的方法名称可以在对应 SQL 目录下的 Visitor 文件中查找
182176
183-
<br/>
184-
185177
### 监听器(Listener)
186178

187179
Listener 模式,利用 [ANTLR4](https://github.com/antlr/antlr4) 提供的 `ParseTreeWalker` 对象遍历 AST,进入各个节点时调用对应的方法。
@@ -215,8 +207,6 @@ TableName user1
215207

216208
> 提示:使用 Listener 模式时,节点的方法名称可以在对应 SQL 目录下的 Listener 文件中查找
217209
218-
<br/>
219-
220210
### SQL 按语句切割
221211
`FlinkSQL` 为例:
222212
```javascript
@@ -251,9 +241,7 @@ console.log(sqlSlices)
251241

252242
```
253243

254-
<br/>
255-
256-
### 自动补全(Auto Complete)
244+
### 自动补全(Code Completion)
257245
在 sql 的指定位置上获取自动补全信息,以 `FlinkSQL` 为例:
258246

259247
调用 `getSuggestionAtCaretPosition` 方法,传入 sql 内容和需要自动补全的位置的行列号。
@@ -312,8 +300,6 @@ console.log(sqlSlices)
312300
```
313301
语法相关自动补全信息返回一个数组,数组中每一项代表该位置可以填写什么语法,比如上例中的输出结果代表该位置可以填写**表名**或者**视图名称**。其中 `syntaxContextType` 是可以补全的语法类型,`wordRanges` 则是已经填写的内容。
314302
315-
<br/>
316-
317303
### 其他 API
318304
319305
- `createLexer` 创建一个 Antlr4 Lexer 实例并返回;

README.md

Lines changed: 16 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ English | [简体中文](./README-zh_CN.md)
1515

1616
dt-sql-parser is a **SQL Parser** project built with [ANTLR4](https://github.com/antlr/antlr4), and it's mainly for the **BigData** domain. The [ANTLR4](https://github.com/antlr/antlr4) generated the basic Parser, Visitor, and Listener, so it's easy to complete the **syntax validation**, **tokenizer**, **traverse** the AST, and so on features.
1717

18-
Besides, it provides some helper methods, like **split** SQL, and **Auto-Complete**.
18+
Additionally, it provides auxiliary functions such as SQL splitting and Auto-Complete.
1919

2020
**Supported SQL**:
2121

@@ -27,7 +27,7 @@ Besides, it provides some helper methods, like **split** SQL, and **Auto-Complet
2727
- PostgreSQL
2828
- Trino SQL
2929

30-
**Supported helper methods**
30+
**Supported auxiliary methods**
3131

3232
| SQL Type | SQL Split | Auto-Complete |
3333
| ----------- | -------- | -------- |
@@ -63,19 +63,18 @@ yarn add dt-sql-parser
6363
<br/>
6464

6565
## Usage
66-
Before you get started, you need to understand the basics of how to use it. `dt-sql-parser` provides SQL parser classes for different types of supported SQL:
66+
We recommend learning the Fundamentals usage before continuing. The dt-sql-parser library provides SQL Parser classes for different types of SQL.
6767
```javascript
6868
import { GenericSQL, FlinkSQL, SparkSQL, HiveSQL, PLSQL, PostgresSQL, TrinoSQL } from 'dt-sql-parser';
6969
```
7070

71-
Before using syntax validation, autocompletion, and other method, you need to instantiate the Parser of the corresponding SQL type, taking `GenericSQL` as an example:
71+
Before employing syntax validation, code completion, and other features, it is necessary to instantiate the Parser of the relevant SQL type.
72+
For instance, one can consider using `GenericSQL` as an example:
7273
```javascript
7374
const parser = new GenericSQL();
7475
```
7576

76-
The usage examples below will use `GenericSQL`, and Parser for other SQL types will be used in the same way as `GenericSQL`.
77-
78-
<br/>
77+
The following usage examples will utilize the `GenericSQL`, and the Parser for other SQL types will be employed in a similar manner as `GenericSQL`.
7978

8079
### Syntax Validation
8180
```javascript
@@ -123,8 +122,6 @@ Output:
123122
We instanced a Parser object, and use the **validate** method to check the SQL syntax, if failed
124123
returns an array object includes **error** message.
125124

126-
<br/>
127-
128125
### Tokenizer
129126

130127
Get all **tokens** by the Parser:
@@ -154,8 +151,6 @@ console.log(tokens)
154151
*/
155152
```
156153

157-
<br/>
158-
159154
### Visitor
160155

161156
Traverse the tree node by the Visitor:
@@ -192,8 +187,6 @@ TableName user1
192187

193188
> Tips: The node's method name can be found in the Visitor file under the corresponding SQL directory
194189
195-
<br/>
196-
197190
### Listener
198191

199192
Access the specified node in the AST by the Listener
@@ -228,9 +221,7 @@ TableName user1
228221

229222
> Tips: The node's method name can be found in the Listener file under the corresponding SQL directory
230223
231-
<br/>
232-
233-
### Split sql by statement
224+
### Splitting SQL statements
234225
Take `FlinkSQL` as an example:
235226
```javascript
236227
import { FlinkSQL } from 'dt-sql-parser';
@@ -264,13 +255,12 @@ console.log(sqlSlices)
264255

265256
```
266257

267-
<br/>
258+
### Code Completion
259+
Obtaining autocomplete information at a specified position in SQL.
260+
We can refer to the example of using `FlinkSQL`.
268261

269-
### Auto Complete
270-
Get the autocomplete information in the specified position of sql, using `FlinkSQL` as an example:
271-
272-
Call the `getSuggestionAtCaretPosition` method, passing in the SQL content and the row and column numbers of the position that need to be autocompleted.
273-
+ Get a list of keyword candidates
262+
Invoke the `getSuggestionAtCaretPosition` method, pass the SQL content and the row and column numbers indicating the position where auto-completion is desired.
263+
+ keyword candidates list
274264

275265
```javascript
276266
import { FlinkSQL } from 'dt-sql-parser';
@@ -284,7 +274,7 @@ Call the `getSuggestionAtCaretPosition` method, passing in the SQL content and t
284274
[ 'CATALOG', 'FUNCTION', 'TEMPORARY', 'VIEW', 'DATABASE', 'TABLE' ]
285275
*/
286276
```
287-
+ Gets syntax-related autocompletion information
277+
+ Obtaining information related to grammar completion
288278
```javascript
289279
const parser = new FlinkSQL();
290280
const sql = 'SELECT * FROM tb';
@@ -323,14 +313,12 @@ Call the `getSuggestionAtCaretPosition` method, passing in the SQL content and t
323313
]
324314
*/
325315
```
326-
Syntax-related autocomplete information returns an array, and each item in the array represents what syntax can be filled in at that position, such as the output result in the above example represents that the position can be filled in **table name** or **view name**. The `syntaxContextType` is a syntax type that can be completed, and `wordRanges` is what has been filled in.
327-
328-
<br/>
316+
The grammar-related autocomplete information returns an array, where each item represents what grammar can be filled in at that position. For example, the output in the above example represents that the position can be filled with either a **table name** or **a view name**. In this case, `syntaxContextType` represents the type of grammar that can be completed, and `wordRanges` represents the content that has already been filled.
329317
330318
### Other API
331319
332-
- `createLexer` Create an instance of Antlr4 Lexer and return;
333-
- `createParser` Create an instance of Antlr4 parser and return;
320+
- `createLexer` Create an instance of Antlr4 Lexer and return it;
321+
- `createParser` Create an instance of Antlr4 parser and return it;
334322
- `parse` Parses the input SQL and returns the parse tree;
335323
336324
<br/>

0 commit comments

Comments
 (0)