add more tests and documentation

Author: lovasoa

README.md

@@ -40,6 +40,25 @@ 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 })]
 ```
 
+### Analyzing and transforming the AST
+
+Once you have an abstract syntax tree, you can analyze and transform it 
+using the optional [`derive-visitor`](https://github.com/nikis05/derive-visitor) feature.
+
+For instance, if you want to rename all identifiers in a query:
+
+```rust
+use sqlparser::{dialect::GenericDialect, parser::Parser, ast::Ident};
+ use derive_visitor::{visitor_enter_fn_mut, DriveMut};
+
+let mut statements = Parser::parse_sql(&GenericDialect, "select x").unwrap();
+statements[0].drive_mut(&mut visitor_enter_fn_mut(|ident: &mut Ident| {
+    ident.value = ident.value.replace("x", "y");
+}));
+assert_eq!(statements[0].to_string(), "SELECT y");
+```
+
+
 ## Command line
 To parse a file and dump the results as JSON:
 ```

src/lib.rs

@@ -25,12 +25,31 @@
 //!
 //! let sql = "SELECT a, b, 123, myfunc(b) \
 //!            FROM table_1 \
-//!            WHERE a > b AND b < 100 \
+//!            WHERE a > b AND b < $x \
 //!            ORDER BY a DESC, b";
 //!
-//! let ast = Parser::parse_sql(&dialect, sql).unwrap();
+//! let mut ast = Parser::parse_sql(&dialect, sql).unwrap();
 //!
 //! println!("AST: {:?}", ast);
+//!
+//! # #[cfg(feature = "derive-visitor")] {
+//! // You can activate the derive-visitor feature
+//! // to apply transforms to all AST nodes of a given type
+//!
+//! use derive_visitor::{visitor_enter_fn_mut, DriveMut};
+//! use sqlparser::ast;
+//!
+//! ast[0].drive_mut(&mut visitor_enter_fn_mut(|value: &mut ast::Value| {
+//!     if let ast::Value::Placeholder(ref mut placeholder) = value {
+//!         *placeholder += "_transformed";
+//!     }
+//! }));
+//!
+//! assert_eq!(
+//!     ast[0].to_string(),
+//!     "SELECT a, b, 123, myfunc(b) FROM table_1 WHERE a > b AND b < $x_transformed ORDER BY a DESC, b"
+//! );
+//! # }
 //! ```
 
 #![cfg_attr(not(feature = "std"), no_std)]

tests/sqlparser_visitor.rs

@@ -1,9 +1,11 @@
 #[cfg(feature = "derive-visitor")]
 mod test {
-    use derive_visitor::{visitor_enter_fn_mut, DriveMut, Drive, Visitor};
+    use derive_visitor::{visitor_enter_fn_mut, Drive, DriveMut, Visitor};
     use sqlparser::ast;
     use sqlparser::ast::TableFactor::Table;
-    use sqlparser::ast::{Ident, Join, JoinConstraint, JoinOperator, ObjectName, TableFactor, Value};
+    use sqlparser::ast::{
+        Ident, Join, JoinConstraint, JoinOperator, ObjectName, TableFactor, Value,
+    };
     use sqlparser::dialect::GenericDialect;
     use sqlparser::parser::Parser;
 
@@ -79,4 +81,13 @@ mod test {
         ast[0].drive(&mut counter);
         assert_eq!(counter.0, 2, "There are 2 placeholders in the query");
     }
+
+    #[test]
+    fn test_readme_example() {
+        let mut statements = Parser::parse_sql(&GenericDialect, "select x").unwrap();
+        statements[0].drive_mut(&mut visitor_enter_fn_mut(|ident: &mut Ident| {
+            ident.value = ident.value.replace("x", "y");
+        }));
+        assert_eq!(statements[0].to_string(), "SELECT y");
+    }
 }