refactor: make intermediate AST utility available without a feature f…

…lag (#61)

# Rationale for this change
This PR exists to address non-blocking issues mentioned in #59 without
blocking #56.
<!--
Why are you proposing this change? If this is already explained clearly
in the linked Jira ticket then this section is not needed.
Explaining clearly why changes are proposed helps reviewers understand
your changes and offer better suggestions for fixes.
-->

# What changes are included in this PR?
- remove `parser-test-utility` feature
- rename `proof-of-sql-parser/src/test_utility.rs` to `utility.rs`
- improve docs for the file above
<!--
There is no need to duplicate the description in the ticket here but it
is sometimes worth providing a summary of the individual changes in this
PR.
-->

# Are these changes tested?
Existing tests should pass
<!--
We typically require tests for all PRs in order to:
1. Prevent the code from being accidentally broken by subsequent changes
2. Serve as another way to document the expected behavior of the code

If tests are not included in your PR, please explain why (for example,
are they covered by existing tests)?
-->

crates/proof-of-sql-parser/Cargo.toml

@@ -23,9 +23,6 @@ lalrpop-util = { workspace = true, features = ["lexer", "unicode"] }
 serde = { workspace = true, features = ["serde_derive"] }
 thiserror = { workspace = true }
 
-[features]
-parser-test-utility = []
-
 [build-dependencies]
 lalrpop = { version = "0.20.0" }
 

crates/proof-of-sql-parser/src/intermediate_ast_tests.rs

@@ -2,7 +2,7 @@ use crate::{
     intermediate_ast::OrderByDirection::{Asc, Desc},
     intermediate_decimal::IntermediateDecimal,
     sql::*,
-    test_utility::*,
+    utility::*,
     SelectStatement,
 };
 

crates/proof-of-sql-parser/src/lib.rs

@@ -9,12 +9,11 @@ extern crate lalrpop_util;
 
 pub mod intermediate_ast;
 
-#[cfg(all(test, feature = "parser-test-utility"))]
+#[cfg(test)]
 mod intermediate_ast_tests;
 
-#[cfg(feature = "parser-test-utility")]
 /// Shortcuts to construct intermediate AST nodes.
-pub mod test_utility;
+pub mod utility;
 
 pub(crate) mod select_statement;
 pub use select_statement::SelectStatement;

crates/proof-of-sql-parser/src/test_utility.rs → crates/proof-of-sql-parser/src/utility.rs

@@ -1,6 +1,6 @@
 use crate::{intermediate_ast::*, Identifier, SelectStatement};
 
-/// A == B
+/// Construct a new boxed `Expression` A == B
 pub fn equal(left: Box<Expression>, right: Box<Expression>) -> Box<Expression> {
     Box::new(Expression::Binary {
         op: BinaryOperator::Equal,
@@ -9,7 +9,7 @@ pub fn equal(left: Box<Expression>, right: Box<Expression>) -> Box<Expression> {
     })
 }
 
-/// A >= B
+/// Construct a new boxed `Expression` A >= B
 pub fn ge(left: Box<Expression>, right: Box<Expression>) -> Box<Expression> {
     Box::new(Expression::Binary {
         op: BinaryOperator::GreaterThanOrEqual,
@@ -18,7 +18,7 @@ pub fn ge(left: Box<Expression>, right: Box<Expression>) -> Box<Expression> {
     })
 }
 
-/// A <= B
+/// Construct a new boxed `Expression` A <= B
 pub fn le(left: Box<Expression>, right: Box<Expression>) -> Box<Expression> {
     Box::new(Expression::Binary {
         op: BinaryOperator::LessThanOrEqual,
@@ -27,15 +27,15 @@ pub fn le(left: Box<Expression>, right: Box<Expression>) -> Box<Expression> {
     })
 }
 
-/// NOT P
+/// Construct a new boxed `Expression` NOT P
 pub fn not(expr: Box<Expression>) -> Box<Expression> {
     Box::new(Expression::Unary {
         op: UnaryOperator::Not,
         expr,
     })
 }
 
-/// P AND Q
+/// Construct a new boxed `Expression` P AND Q
 pub fn and(left: Box<Expression>, right: Box<Expression>) -> Box<Expression> {
     Box::new(Expression::Binary {
         op: BinaryOperator::And,
@@ -44,7 +44,7 @@ pub fn and(left: Box<Expression>, right: Box<Expression>) -> Box<Expression> {
     })
 }
 
-/// P OR Q
+/// Construct a new boxed `Expression` P OR Q
 pub fn or(left: Box<Expression>, right: Box<Expression>) -> Box<Expression> {
     Box::new(Expression::Binary {
         op: BinaryOperator::Or,
@@ -53,7 +53,9 @@ pub fn or(left: Box<Expression>, right: Box<Expression>) -> Box<Expression> {
     })
 }
 
-/// Get table from schema and name
+/// Get table from schema and name.
+///
+/// If the schema is `None`, the table is assumed to be in the default schema.
 pub fn tab(schema: Option<&str>, name: &str) -> Box<TableExpression> {
     Box::new(TableExpression::Named {
         table: name.parse().unwrap(),
@@ -71,25 +73,25 @@ pub fn lit<L: Into<Literal>>(literal: L) -> Box<Expression> {
     Box::new(Expression::Literal(literal.into()))
 }
 
-/// SELECT *
+/// Select all columns from a table i.e. SELECT *
 pub fn col_res_all() -> SelectResultExpr {
     SelectResultExpr::ALL
 }
 
-/// SELECT COL AS ALIAS
+/// Select one column from a table and give it an alias i.e. SELECT COL AS ALIAS
 pub fn col_res(col_val: Box<Expression>, alias: &str) -> SelectResultExpr {
     SelectResultExpr::AliasedResultExpr(AliasedResultExpr {
         expr: col_val,
         alias: alias.parse().unwrap(),
     })
 }
 
-/// SELECT COL1, COL2, ...
+/// Select multiple columns from a table i.e. SELECT COL1, COL2, ...
 pub fn cols_res(names: &[&str]) -> Vec<SelectResultExpr> {
     names.iter().map(|name| col_res(col(name), name)).collect()
 }
 
-/// SELECT MIN(EXPR) AS ALIAS
+/// Compute the minimum of an expression and give it an alias i.e. SELECT MIN(EXPR) AS ALIAS
 pub fn min_res(expr: Box<Expression>, alias: &str) -> SelectResultExpr {
     SelectResultExpr::AliasedResultExpr(AliasedResultExpr {
         expr: Box::new(Expression::Aggregation {
@@ -100,7 +102,7 @@ pub fn min_res(expr: Box<Expression>, alias: &str) -> SelectResultExpr {
     })
 }
 
-/// SELECT MAX(EXPR) AS ALIAS
+/// Compute the maximum of an expression and give it an alias i.e. SELECT MAX(EXPR) AS ALIAS
 pub fn max_res(expr: Box<Expression>, alias: &str) -> SelectResultExpr {
     SelectResultExpr::AliasedResultExpr(AliasedResultExpr {
         expr: Expression::Aggregation {
@@ -112,7 +114,7 @@ pub fn max_res(expr: Box<Expression>, alias: &str) -> SelectResultExpr {
     })
 }
 
-/// SELECT SUM(EXPR) AS ALIAS
+/// Compute the sum of an expression and give it an alias i.e. SELECT SUM(EXPR) AS ALIAS
 pub fn sum_res(expr: Box<Expression>, alias: &str) -> SelectResultExpr {
     SelectResultExpr::AliasedResultExpr(AliasedResultExpr {
         expr: Expression::Aggregation {
@@ -124,7 +126,7 @@ pub fn sum_res(expr: Box<Expression>, alias: &str) -> SelectResultExpr {
     })
 }
 
-/// SELECT COUNT(EXPR) AS ALIAS
+/// Count an expression and give it an alias i.e. SELECT COUNT(EXPR) AS ALIAS
 pub fn count_res(expr: Box<Expression>, alias: &str) -> SelectResultExpr {
     SelectResultExpr::AliasedResultExpr(AliasedResultExpr {
         expr: Expression::Aggregation {
@@ -136,7 +138,7 @@ pub fn count_res(expr: Box<Expression>, alias: &str) -> SelectResultExpr {
     })
 }
 
-/// SELECT COUNT(*) AS ALIAS
+/// Count rows and give the result an alias i.e. SELECT COUNT(*) AS ALIAS
 pub fn count_all_res(alias: &str) -> SelectResultExpr {
     SelectResultExpr::AliasedResultExpr(AliasedResultExpr {
         expr: Expression::Aggregation {
@@ -148,7 +150,7 @@ pub fn count_all_res(alias: &str) -> SelectResultExpr {
     })
 }
 
-/// SELECT COL1, COL2, ... FROM TAB WHERE EXPR GROUP BY ...
+/// Generate a `SetExpression` of the kind SELECT COL1, COL2, ... FROM TAB WHERE EXPR GROUP BY ...
 pub fn query(
     result_exprs: Vec<SelectResultExpr>,
     tab: Box<TableExpression>,
@@ -163,7 +165,9 @@ pub fn query(
     })
 }
 
-/// SELECT COL1, COL2, ... FROM TAB GROUP BY ...
+/// Generate a `SetExpression` of the kind SELECT COL1, COL2, ... FROM TAB GROUP BY ...
+///
+/// Note that there is no WHERE clause.
 pub fn query_all(
     result_exprs: Vec<SelectResultExpr>,
     tab: Box<TableExpression>,
@@ -177,7 +181,9 @@ pub fn query_all(
     })
 }
 
-/// SELECT ... ORDER BY ... [LIMIT ... OFFSET ...]
+/// Generate a query of the kind SELECT ... ORDER BY ... [LIMIT ... OFFSET ...]
+///
+/// Note that `expr` is a boxed `SetExpression`
 pub fn select(
     expr: Box<SetExpression>,
     order_by: Vec<OrderBy>,
@@ -190,15 +196,15 @@ pub fn select(
     }
 }
 
-/// ORDER BY ID [ASC|DESC]
+/// Order by one column i.e. ORDER BY ID [ASC|DESC]
 pub fn order(id: &str, direction: OrderByDirection) -> Vec<OrderBy> {
     vec![OrderBy {
         expr: id.parse().unwrap(),
         direction,
     }]
 }
 
-/// ORDER BY ID0 [ASC|DESC], ID1 [ASC|DESC], ...
+/// Order by multiple columns i.e. ORDER BY ID0 [ASC|DESC], ID1 [ASC|DESC], ...
 pub fn orders(ids: &[&str], directions: &[OrderByDirection]) -> Vec<OrderBy> {
     ids.iter()
         .zip(directions.iter())
@@ -209,15 +215,15 @@ pub fn orders(ids: &[&str], directions: &[OrderByDirection]) -> Vec<OrderBy> {
         .collect::<Vec<_>>()
 }
 
-/// LIMIT N OFFSET M
+/// Slice a query result using `LIMIT` and `OFFSET` clauses i.e. LIMIT N OFFSET M
 pub fn slice(number_rows: u64, offset_value: i64) -> Option<Slice> {
     Some(Slice {
         number_rows,
         offset_value,
     })
 }
 
-/// GROUP BY ID0, ID1, ...
+/// Group by clause with multiple columns i.e. GROUP BY ID0, ID1, ...
 pub fn group_by(ids: &[&str]) -> Vec<Identifier> {
     ids.iter().map(|id| id.parse().unwrap()).collect()
 }