Skip to content

Commit

Permalink
docs: improve and update README
Browse files Browse the repository at this point in the history
  • Loading branch information
HaydenOrz committed Oct 20, 2023
1 parent 970bf4e commit e494e00
Show file tree
Hide file tree
Showing 2 changed files with 18 additions and 44 deletions.
18 changes: 2 additions & 16 deletions README-zh_CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ yarn add dt-sql-parser
<br/>

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

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

<br/>

### 语法校验(Syntax Validation)
```javascript
import { GenericSQL } from 'dt-sql-parser';
Expand Down Expand Up @@ -112,8 +110,6 @@ console.log(errors);

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

<br/>

### 词法分析(Tokenizer)

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

<br/>

### 访问者模式(Visitor)

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

> 提示:使用 Visitor 模式时,节点的方法名称可以在对应 SQL 目录下的 Visitor 文件中查找
<br/>

### 监听器(Listener)

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

> 提示:使用 Listener 模式时,节点的方法名称可以在对应 SQL 目录下的 Listener 文件中查找
<br/>

### SQL 按语句切割
`FlinkSQL` 为例:
```javascript
Expand Down Expand Up @@ -251,9 +241,7 @@ console.log(sqlSlices)

```

<br/>

### 自动补全(Auto Complete)
### 自动补全(Code Completion)
在 sql 的指定位置上获取自动补全信息,以 `FlinkSQL` 为例:

调用 `getSuggestionAtCaretPosition` 方法,传入 sql 内容和需要自动补全的位置的行列号。
Expand Down Expand Up @@ -312,8 +300,6 @@ console.log(sqlSlices)
```
语法相关自动补全信息返回一个数组,数组中每一项代表该位置可以填写什么语法,比如上例中的输出结果代表该位置可以填写**表名**或者**视图名称**。其中 `syntaxContextType` 是可以补全的语法类型,`wordRanges` 则是已经填写的内容。
<br/>
### 其他 API
- `createLexer` 创建一个 Antlr4 Lexer 实例并返回;
Expand Down
44 changes: 16 additions & 28 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ English | [简体中文](./README-zh_CN.md)

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.

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

**Supported SQL**:

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

**Supported helper methods**
**Supported auxiliary methods**

| SQL Type | SQL Split | Auto-Complete |
| ----------- | -------- | -------- |
Expand Down Expand Up @@ -63,19 +63,18 @@ yarn add dt-sql-parser
<br/>

## Usage
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:
We recommend learning the Fundamentals usage before continuing. The dt-sql-parser library provides SQL Parser classes for different types of SQL.
```javascript
import { GenericSQL, FlinkSQL, SparkSQL, HiveSQL, PLSQL, PostgresSQL, TrinoSQL } from 'dt-sql-parser';
```

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

The usage examples below will use `GenericSQL`, and Parser for other SQL types will be used in the same way as `GenericSQL`.

<br/>
The following usage examples will utilize the `GenericSQL`, and the Parser for other SQL types will be employed in a similar manner as `GenericSQL`.

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

<br/>

### Tokenizer

Get all **tokens** by the Parser:
Expand Down Expand Up @@ -154,8 +151,6 @@ console.log(tokens)
*/
```

<br/>

### Visitor

Traverse the tree node by the Visitor:
Expand Down Expand Up @@ -192,8 +187,6 @@ TableName user1

> Tips: The node's method name can be found in the Visitor file under the corresponding SQL directory
<br/>

### Listener

Access the specified node in the AST by the Listener
Expand Down Expand Up @@ -228,9 +221,7 @@ TableName user1

> Tips: The node's method name can be found in the Listener file under the corresponding SQL directory
<br/>

### Split sql by statement
### Splitting SQL statements
Take `FlinkSQL` as an example:
```javascript
import { FlinkSQL } from 'dt-sql-parser';
Expand Down Expand Up @@ -264,13 +255,12 @@ console.log(sqlSlices)

```

<br/>
### Code Completion
Obtaining autocomplete information at a specified position in SQL.
We can refer to the example of using `FlinkSQL`.

### Auto Complete
Get the autocomplete information in the specified position of sql, using `FlinkSQL` as an example:

Call the `getSuggestionAtCaretPosition` method, passing in the SQL content and the row and column numbers of the position that need to be autocompleted.
+ Get a list of keyword candidates
Invoke the `getSuggestionAtCaretPosition` method, pass the SQL content and the row and column numbers indicating the position where auto-completion is desired.
+ keyword candidates list

```javascript
import { FlinkSQL } from 'dt-sql-parser';
Expand All @@ -284,7 +274,7 @@ Call the `getSuggestionAtCaretPosition` method, passing in the SQL content and t
[ 'CATALOG', 'FUNCTION', 'TEMPORARY', 'VIEW', 'DATABASE', 'TABLE' ]
*/
```
+ Gets syntax-related autocompletion information
+ Obtaining information related to grammar completion
```javascript
const parser = new FlinkSQL();
const sql = 'SELECT * FROM tb';
Expand Down Expand Up @@ -323,14 +313,12 @@ Call the `getSuggestionAtCaretPosition` method, passing in the SQL content and t
]
*/
```
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.
<br/>
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.
### Other API
- `createLexer` Create an instance of Antlr4 Lexer and return;
- `createParser` Create an instance of Antlr4 parser and return;
- `createLexer` Create an instance of Antlr4 Lexer and return it;
- `createParser` Create an instance of Antlr4 parser and return it;
- `parse` Parses the input SQL and returns the parse tree;
<br/>
Expand Down

0 comments on commit e494e00

Please sign in to comment.