Adds initial PEG, basic recognizer API, and Error/Result APIs. (#8)

Adds `pest`/`pest_derive` dependencies and a very basic PEG definition
that is just a stream of PartiQL keywords.  This implementation is just
to flesh out some of the usage of `pest`, namely the derivation macro
and its error APIs.

This commit exposes a function `recognize_partiql` that runs the parser
over an input slice and returns `()` on success or fails on invalid
syntax.  Given that the syntax is just a stream of keywords, this is not
particularly interesting right now.

Adds the following modules:
* `result` contains the main `ParserError` enum, `Position`, and
  `ParserResult` alias.
* `prelude` exports most of `result` and will be used in the future for
  things like traits as well.
* `peg` is the module that hosts the low-level Pest PEG parser and the
  grammar definition file.

Other notes:
* Adds `From` implementation for `pest::error::Error` for `ParserError`
  to do basic translation of the relatively obtuse Pest error to
  something a bit more friendly.
* Updates README around versioning.
* Changes stub tests to just be no-op for the non-parser packages.
* Adds dependency for `thiserror` for less boilerplate error
  definitions.
* Adds dev dependency for `rstest` for table driven testing.

Author: almann

README.md

@@ -11,7 +11,14 @@ This is a collection of crates to provide Rust support for the [PartiQL][partiql
 ***The crates in this repository are considered experimental, under active/early development,
 and APIs are subject to change.***
 
-This project uses [workspaces][workspaces] to manage the crates in this repository.
+This project uses [workspaces][workspaces] to manage the crates in this repository.  The `partiql` crate is intended
+to be the crate that exports all the relevant `partiql-*` sub-crate functionality.  It is factored in this way
+to make applications needing only some sub-component of the PartiQL implementation possible (e.g. an application
+that only requires the PartiQL parser can depend on `partiql-parser` directly).
+
+Due to the lack of namespacing in [crates.io][crates], we have published `0.0.0` versions for the sub-crates we know
+we will need.  A crate with a version `0.1.0` or higher, should have real, albeit potentially very experimental and/or
+early implementations.
 
 ## Security
 
@@ -22,4 +29,5 @@ See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more inform
 This project is licensed under the Apache-2.0 License.
 
 [partiql]: https://partiql.org/
-[workspaces]: https://doc.rust-lang.org/stable/cargo/reference/workspaces.html
+[workspaces]: https://doc.rust-lang.org/stable/cargo/reference/workspaces.html
+[crates]: https://crates.io/policies

partiql-eval/src/lib.rs

@@ -1,7 +1,5 @@
 #[cfg(test)]
 mod tests {
     #[test]
-    fn it_works() {
-        assert_eq!(2 + 2, 4);
-    }
+    fn todo() {}
 }

partiql-irgen/src/lib.rs

@@ -1,7 +1,5 @@
 #[cfg(test)]
 mod tests {
     #[test]
-    fn it_works() {
-        assert_eq!(2 + 2, 4);
-    }
+    fn todo() {}
 }

partiql-parser/Cargo.toml

@@ -20,3 +20,9 @@ version = "0.0.0"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
+pest = "~2.1.3"
+pest_derive = "~2.1.0"
+thiserror = "~1.0.24"
+
+[dev-dependencies]
+rstest = "~0.9.0"

partiql-parser/src/lib.rs

@@ -1,7 +1,11 @@
-#[cfg(test)]
-mod tests {
-    #[test]
-    fn it_works() {
-        assert_eq!(2 + 2, 4);
-    }
-}
+// Copyright Amazon.com, Inc. or its affiliates.
+
+//! Provides a parser for the [PartiQL][partiql] query language.
+//!
+//! [partiql]: https://partiql.org
+
+mod peg;
+pub mod prelude;
+pub mod result;
+
+pub use peg::recognize_partiql;

partiql-parser/src/partiql.pest

@@ -0,0 +1,263 @@
+WHITESPACE = _{ " " | "\t" | "\x0B" | "\x0C" | "\r" | "\n" }
+
+// really basic rules to just detect a sequence of keywords
+// two dip our toes in Pest
+
+Keywords = _{ SOI ~ Keyword+ ~ EOI}
+
+Keyword = { AllKeywords }
+
+AllKeywords = _{
+      SqlKeywords
+    | PartiqlKeywords
+}
+
+SqlKeywords = _{
+      ^"absolute"
+    | ^"action"
+    | ^"add"
+    | ^"all"
+    | ^"allocate"
+    | ^"alter"
+    | ^"and"
+    | ^"any"
+    | ^"are"
+    | ^"as"
+    | ^"asc"
+    | ^"assertion"
+    | ^"at"
+    | ^"authorization"
+    | ^"avg"
+    | ^"begin"
+    | ^"between"
+    | ^"bit"
+    | ^"bit_length"
+    | ^"by"
+    | ^"cascade"
+    | ^"cascaded"
+    | ^"case"
+    | ^"cast"
+    | ^"catalog"
+    | ^"char"
+    | ^"character"
+    | ^"character_length"
+    | ^"char_length"
+    | ^"check"
+    | ^"close"
+    | ^"coalesce"
+    | ^"collate"
+    | ^"collation"
+    | ^"column"
+    | ^"commit"
+    | ^"connect"
+    | ^"connection"
+    | ^"constraint"
+    | ^"constraints"
+    | ^"continue"
+    | ^"convert"
+    | ^"corresponding"
+    | ^"count"
+    | ^"create"
+    | ^"cross"
+    | ^"current"
+    | ^"current_date"
+    | ^"current_time"
+    | ^"current_timestamp"
+    | ^"current_user"
+    | ^"cursor"
+    | ^"date"
+    | ^"deallocate"
+    | ^"dec"
+    | ^"decimal"
+    | ^"declare"
+    | ^"default"
+    | ^"deferrable"
+    | ^"deferred"
+    | ^"delete"
+    | ^"desc"
+    | ^"describe"
+    | ^"descriptor"
+    | ^"diagnostics"
+    | ^"disconnect"
+    | ^"distinct"
+    | ^"domain"
+    | ^"double"
+    | ^"drop"
+    | ^"else"
+    | ^"end"
+    | ^"end-exec"
+    | ^"escape"
+    | ^"except"
+    | ^"exception"
+    | ^"exec"
+    | ^"execute"
+    | ^"exists"
+    | ^"external"
+    | ^"extract"
+    | ^"date_add"
+    | ^"date_diff"
+    | ^"false"
+    | ^"fetch"
+    | ^"first"
+    | ^"float"
+    | ^"for"
+    | ^"foreign"
+    | ^"found"
+    | ^"from"
+    | ^"full"
+    | ^"get"
+    | ^"global"
+    | ^"go"
+    | ^"goto"
+    | ^"grant"
+    | ^"group"
+    | ^"having"
+    | ^"identity"
+    | ^"immediate"
+    | ^"in"
+    | ^"indicator"
+    | ^"initially"
+    | ^"inner"
+    | ^"input"
+    | ^"insensitive"
+    | ^"insert"
+    | ^"int"
+    | ^"integer"
+    | ^"intersect"
+    | ^"interval"
+    | ^"into"
+    | ^"is"
+    | ^"isolation"
+    | ^"join"
+    | ^"key"
+    | ^"language"
+    | ^"last"
+    | ^"left"
+    | ^"level"
+    | ^"like"
+    | ^"local"
+    | ^"lower"
+    | ^"match"
+    | ^"max"
+    | ^"min"
+    | ^"module"
+    | ^"names"
+    | ^"national"
+    | ^"natural"
+    | ^"nchar"
+    | ^"next"
+    | ^"no"
+    | ^"not"
+    | ^"null"
+    | ^"nullif"
+    | ^"numeric"
+    | ^"octet_length"
+    | ^"of"
+    | ^"on"
+    | ^"only"
+    | ^"open"
+    | ^"option"
+    | ^"or"
+    | ^"order"
+    | ^"outer"
+    | ^"output"
+    | ^"overlaps"
+    | ^"pad"
+    | ^"partial"
+    | ^"position"
+    | ^"precision"
+    | ^"prepare"
+    | ^"preserve"
+    | ^"primary"
+    | ^"prior"
+    | ^"privileges"
+    | ^"procedure"
+    | ^"public"
+    | ^"read"
+    | ^"real"
+    | ^"references"
+    | ^"relative"
+    | ^"restrict"
+    | ^"revoke"
+    | ^"right"
+    | ^"rollback"
+    | ^"rows"
+    | ^"schema"
+    | ^"scroll"
+    | ^"section"
+    | ^"select"
+    | ^"session"
+    | ^"session_user"
+    | ^"set"
+    | ^"size"
+    | ^"smallint"
+    | ^"some"
+    | ^"space"
+    | ^"sql"
+    | ^"sqlcode"
+    | ^"sqlerror"
+    | ^"sqlstate"
+    | ^"substring"
+    | ^"sum"
+    | ^"system_user"
+    | ^"table"
+    | ^"temporary"
+    | ^"then"
+    | ^"time"
+    | ^"timestamp"
+    | ^"to"
+    | ^"transaction"
+    | ^"translate"
+    | ^"translation"
+    | ^"trim"
+    | ^"true"
+    | ^"union"
+    | ^"unique"
+    | ^"unknown"
+    | ^"update"
+    | ^"upper"
+    | ^"usage"
+    | ^"user"
+    | ^"using"
+    | ^"value"
+    | ^"values"
+    | ^"varchar"
+    | ^"varying"
+    | ^"view"
+    | ^"when"
+    | ^"whenever"
+    | ^"where"
+    | ^"with"
+    | ^"work"
+    | ^"write"
+    | ^"zone"
+}
+
+PartiqlKeywords = _{
+      ^"missing"
+    | ^"pivot"
+    | ^"unpivot"
+    | ^"limit"
+    | ^"tuple"
+    | ^"remove"
+    | ^"index"
+    | ^"conflict"
+    | ^"do"
+    | ^"nothing"
+    | ^"returning"
+    | ^"modified"
+    | ^"all"
+    | ^"new"
+    | ^"old"
+    | ^"let"
+    | ^"bool"
+    | ^"boolean"
+    | ^"string"
+    | ^"symbol"
+    | ^"clob"
+    | ^"blob"
+    | ^"struct"
+    | ^"list"
+    | ^"sexp"
+    | ^"bag"
+}

partiql-parser/src/peg.rs

@@ -0,0 +1,48 @@
+// Copyright Amazon.com, Inc. or its affiliates.
+
+//! Contains the [Pest](https://pest.rs) defined parser for PartiQL and a wrapper APIs that
+//! can be exported for users to consume.
+
+use crate::prelude::*;
+use pest::Parser;
+use pest_derive::Parser;
+
+#[derive(Parser)]
+#[grammar = "partiql.pest"]
+struct PartiQLParser;
+
+/// Recognizer for PartiQL queries.
+///
+/// Returns `Ok(())` in the case that the input is valid PartiQL.  Returns `Err([ParserError])`
+/// in the case that the input is not valid PartiQL.
+///
+/// This API will be replaced with one that produces an AST in the future.
+pub fn recognize_partiql(input: &str) -> ParserResult<()> {
+    PartiQLParser::parse(Rule::Keywords, input)?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn simple() -> ParserResult<()> {
+        recognize_partiql("SELECT FROM WHERE")
+    }
+
+    #[test]
+    fn error() -> ParserResult<()> {
+        match recognize_partiql("SELECT FROM MOO") {
+            Err(ParserError::SyntaxError { position, .. }) => assert_eq!(
+                Position::At {
+                    line: 1,
+                    column: 13
+                },
+                position
+            ),
+            _ => panic!("Expected Syntax Error"),
+        };
+        Ok(())
+    }
+}

partiql-parser/src/prelude.rs

@@ -0,0 +1,8 @@
+// Copyright Amazon.com, Inc. or its affiliates.
+
+//! Convenience export of common traits and basic types that are almost always
+//! needed when using the parser APIs.
+
+pub use crate::result::ParserError;
+pub use crate::result::ParserResult;
+pub use crate::result::Position;