From e494e00e68d1e3c068f7f293ed12ffe38cacada4 Mon Sep 17 00:00:00 2001 From: hayden Date: Fri, 20 Oct 2023 17:46:12 +0800 Subject: [PATCH] docs: improve and update README --- README-zh_CN.md | 18 ++---------------- README.md | 44 ++++++++++++++++---------------------------- 2 files changed, 18 insertions(+), 44 deletions(-) diff --git a/README-zh_CN.md b/README-zh_CN.md index 0fb028b..f905ca5 100644 --- a/README-zh_CN.md +++ b/README-zh_CN.md @@ -53,7 +53,7 @@ yarn add dt-sql-parser
## 使用 -在开始使用前，需要先了解基本的使用方式。`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'; ``` @@ -65,8 +65,6 @@ const parser = new GenericSQL(); 下文中的使用示例将使用 `GenericSQL`，其他 SQL 类型的 Parser 使用方式与`GenericSQL` 相同。 -
- ### 语法校验（Syntax Validation） ```javascript import { GenericSQL } from 'dt-sql-parser'; @@ -112,8 +110,6 @@ console.log(errors); 先实例化 Parser 对象，然后使用 `validate` 方法对 SQL 语句进行校验，如果校验失败，则返回一个包含 `error` 信息的数组。 -
- ### 词法分析（Tokenizer） 必要场景下，可单独对 SQL 语句进行词法分析，获取所有的 Tokens 对象： @@ -143,8 +139,6 @@ console.log(tokens) */ ``` -
- ### 访问者模式（Visitor） 使用 Visitor 模式访问 AST 中的指定节点 @@ -180,8 +174,6 @@ TableName user1 > 提示：使用 Visitor 模式时，节点的方法名称可以在对应 SQL 目录下的 Visitor 文件中查找 -
- ### 监听器（Listener） Listener 模式，利用 [ANTLR4](https://github.com/antlr/antlr4) 提供的 `ParseTreeWalker` 对象遍历 AST，进入各个节点时调用对应的方法。 @@ -215,8 +207,6 @@ TableName user1 > 提示：使用 Listener 模式时，节点的方法名称可以在对应 SQL 目录下的 Listener 文件中查找 -
- ### SQL 按语句切割 以 `FlinkSQL` 为例： ```javascript @@ -251,9 +241,7 @@ console.log(sqlSlices) ``` -
- -### 自动补全（Auto Complete） +### 自动补全（Code Completion） 在 sql 的指定位置上获取自动补全信息，以 `FlinkSQL` 为例： 调用 `getSuggestionAtCaretPosition` 方法，传入 sql 内容和需要自动补全的位置的行列号。 @@ -312,8 +300,6 @@ console.log(sqlSlices) ``` 语法相关自动补全信息返回一个数组，数组中每一项代表该位置可以填写什么语法，比如上例中的输出结果代表该位置可以填写**表名**或者**视图名称**。其中 `syntaxContextType` 是可以补全的语法类型，`wordRanges` 则是已经填写的内容。 -
- ### 其他 API - `createLexer` 创建一个 Antlr4 Lexer 实例并返回； diff --git a/README.md b/README.md index 4883030..50b9d1f 100644 --- a/README.md +++ b/README.md @@ -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**: @@ -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 | | ----------- | -------- | -------- | @@ -63,19 +63,18 @@ yarn add dt-sql-parser
## 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`. - -
+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 @@ -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. -
- ### Tokenizer Get all **tokens** by the Parser: @@ -154,8 +151,6 @@ console.log(tokens) */ ``` -
- ### Visitor Traverse the tree node by the Visitor: @@ -192,8 +187,6 @@ TableName user1 > Tips: The node's method name can be found in the Visitor file under the corresponding SQL directory -
- ### Listener Access the specified node in the AST by the Listener @@ -228,9 +221,7 @@ TableName user1 > Tips: The node's method name can be found in the Listener file under the corresponding SQL directory -
- -### Split sql by statement +### Splitting SQL statements Take `FlinkSQL` as an example: ```javascript import { FlinkSQL } from 'dt-sql-parser'; @@ -264,13 +255,12 @@ console.log(sqlSlices) ``` -
+### 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'; @@ -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'; @@ -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. - -
+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;