From d2922eb29fc01df9b1126ecd94d116dcb454e7e3 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Wed, 28 Dec 2022 09:07:50 -0600 Subject: [PATCH] Improve Readme --- README.md | 70 ++++++++++++++++++++++++++++++++++-------------------- src/lib.rs | 4 +++- 2 files changed, 47 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index e8a14e131..c2ae31564 100644 --- a/README.md +++ b/README.md @@ -6,24 +6,10 @@ [![Coverage Status](https://coveralls.io/repos/github/sqlparser-rs/sqlparser-rs/badge.svg?branch=main)](https://coveralls.io/github/sqlparser-rs/sqlparser-rs?branch=main) [![Gitter Chat](https://badges.gitter.im/sqlparser-rs/community.svg)](https://gitter.im/sqlparser-rs/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) -The goal of this project is to build a SQL lexer and parser capable of parsing -SQL that conforms with the [ANSI/ISO SQL standard][sql-standard] while also -making it easy to support custom dialects so that this crate can be used as a -foundation for vendor-specific parsers. - -This parser is currently being used by the [DataFusion] query engine, -[LocustDB], [Ballista] and [GlueSQL]. - -This crate provides only a syntax parser, and tries to avoid applying -any SQL semantics, and accepts queries that specific databases would -reject, even when using that Database's specific `Dialect`. For -example, `CREATE TABLE(x int, x int)` is accepted by this crate, even -though most SQL engines will reject this statement due to the repeated -column name `x`. - -This crate avoids semantic analysis because it varies drastically -between dialects and implementations. If you want to do semantic -analysis, feel free to use this project as a base +This crate contains a lexer and parser for SQL that conforms with the +[ANSI/ISO SQL standard][sql-standard] and other dialects. This crate +is used as a foundation for SQL query engines, vendor-specific +parsers, and various SQL analysis. ## Example @@ -51,11 +37,27 @@ This outputs AST: [Query(Query { ctes: [], body: Select(Select { distinct: false, projection: [UnnamedExpr(Identifier("a")), UnnamedExpr(Identifier("b")), UnnamedExpr(Value(Long(123))), UnnamedExpr(Function(Function { name: ObjectName(["myfunc"]), args: [Identifier("b")], over: None, distinct: false }))], from: [TableWithJoins { relation: Table { name: ObjectName(["table_1"]), alias: None, args: [], with_hints: [] }, joins: [] }], selection: Some(BinaryOp { left: BinaryOp { left: Identifier("a"), op: Gt, right: Identifier("b") }, op: And, right: BinaryOp { left: Identifier("b"), op: Lt, right: Value(Long(100)) } }), group_by: [], having: None }), order_by: [OrderByExpr { expr: Identifier("a"), asc: Some(false) }, OrderByExpr { expr: Identifier("b"), asc: None }], limit: None, offset: None, fetch: None })] ``` -## Command line -To parse a file and dump the results as JSON: -``` -$ cargo run --features json_example --example cli FILENAME.sql [--dialectname] -``` + +## Features + +The following optional [crate features](https://doc.rust-lang.org/cargo/reference/features.html) are available: + +* `serde`: Adds [Serde](https://serde.rs/) support by implementing `Serialize` and `Deserialize` for all AST nodes. +* `visitor`: Adds a `Visitor` capable of recursively walking the AST tree. + + +## Syntax vs Semantics + +This crate provides only a syntax parser, and tries to avoid applying +any SQL semantics, and accepts queries that specific databases would +reject, even when using that Database's specific `Dialect`. For +example, `CREATE TABLE(x int, x int)` is accepted by this crate, even +though most SQL engines will reject this statement due to the repeated +column name `x`. + +This crate avoids semantic analysis because it varies drastically +between dialects and implementations. If you want to do semantic +analysis, feel free to use this project as a base. ## SQL compliance @@ -81,10 +83,21 @@ that are actually used. Note that if you urgently need support for a feature, you will likely need to write the implementation yourself. See the [Contributing](#Contributing) section for details. -### Supporting custom SQL dialects +## Command line + +This crate contains a CLI program that can parse a file and dump the results as JSON: +``` +$ cargo run --features json_example --example cli FILENAME.sql [--dialectname] +``` + +## Users + +This parser is currently being used by the [DataFusion] query engine, +[LocustDB], [Ballista] and [GlueSQL]. + +If your project is using sqlparser-rs feel free to make a PR to add it +to this list. -This is a work in progress, but we have some notes on [writing a custom SQL -parser](docs/custom_sql_parser.md). ## Design @@ -103,6 +116,11 @@ reasons: - It is far easier to extend and make dialect-specific extensions compared to using a parser generator +### Supporting custom SQL dialects + +This is a work in progress, but we have some notes on [writing a custom SQL +parser](docs/custom_sql_parser.md). + ## Contributing Contributions are highly encouraged! However, the bandwidth we have to diff --git a/src/lib.rs b/src/lib.rs index fffb7e82f..75209b054 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -13,7 +13,8 @@ //! SQL Parser for Rust //! //! This crate provides an ANSI:SQL 2011 lexer and parser that can parse SQL -//! into an Abstract Syntax Tree (AST). +//! into an Abstract Syntax Tree (AST). See the [sqlparser crates.io page] +//! for more information. //! //! See [`Parser::parse_sql`](crate::parser::Parser::parse_sql) and //! [`Parser::new`](crate::parser::Parser::new) for the Parsing API @@ -36,6 +37,7 @@ //! //! println!("AST: {:?}", ast); //! ``` +//! [sqlparser crates.io page]: https://crates.io/crates/sqlparser #![cfg_attr(not(feature = "std"), no_std)] #![allow(clippy::upper_case_acronyms)]