Cucumber expressions AST and parser (#1)

Co-authored-by: Ilya Solovyiov <ilya.solovyiov@gmail.com>

Author: tyranron

.clippy.toml

@@ -6,5 +6,6 @@ standard-macro-braces = [
     { name = "assert", brace = "(" },
     { name = "assert_eq", brace = "(" },
     { name = "assert_ne", brace = "(" },
+    { name = "matches", brace = "(" },
     { name = "vec", brace = "[" },
 ]

CHANGELOG.md

@@ -11,9 +11,12 @@ All user visible changes to `cucumber-expressions` crate will be documented in t
 
 ### Added
 
-- ???
+- [Cucumber Expressions] AST and parser. ([#1])
 
+[#1]: /../../pull/1
 
 
 
+
+[Cucumber Expressions]: https://github.com/cucumber/cucumber-expressions#readme
 [Semantic Versioning 2.0.0]: https://semver.org

Cargo.toml

@@ -3,6 +3,7 @@ name = "cucumber-expressions"
 version = "0.1.0-dev"
 edition = "2021"
 rust-version = "1.56"
+description = "Cucumber Expressions AST and parser."
 license = "MIT OR Apache-2.0"
 authors = [
     "Ilya Solovyiov <ilya.solovyiov@gmail.com>",
@@ -17,3 +18,9 @@ keywords = ["cucumber", "expression", "expressions", "cucumber-expressions"]
 include = ["/src/", "/LICENSE-*", "/README.md", "/CHANGELOG.md"]
 
 [dependencies]
+derive_more = { version = "0.99.16", features = ["as_ref", "deref", "deref_mut", "display", "error"], default_features = false }
+nom = "7.0"
+nom_locate = "4.0"
+
+# TODO: Remove once `derive_more` 0.99.17 is released.
+syn = "1.0.81"

README.md

@@ -15,6 +15,42 @@ This crate provides [AST] and parser of [Cucumber Expressions].
 
 
 
+## Grammar
+
+This implementation follows a context-free grammar, [which isn't yet merged][1]. Original grammar is impossible to follow while creating a performant parser, as it consists errors and describes not an exact [Cucumber Expressions] language, but rather some superset language, while being also context-sensitive. In case you've found some inconsistencies between this implementation and the ones in other languages, please file an issue! 
+
+[EBNF] spec of the current context-free grammar implemented by this crate:
+```ebnf
+expression              = single-expression*
+
+single-expression       = alternation
+                           | optional
+                           | parameter
+                           | text-without-whitespace+
+                           | whitespace
+text-without-whitespace = (- (text-to-escape | whitespace))
+                           | ('\', text-to-escape)
+text-to-escape          = '(' | '{' | '/' | '\'
+
+alternation             = single-alternation, (`/`, single-alternation)+
+single-alternation      = ((text-in-alternative+, optional*)
+                            | (optional+, text-in-alternative+))+
+text-in-alternative     = (- alternative-to-escape)
+                           | ('\', alternative-to-escape)
+alternative-to-escape   = ' ' | '(' | '{' | '/' | '\'
+
+optional                = '(' text-in-optional+ ')'
+text-in-optional        = (- optional-to-escape) | ('\', optional-to-escape)
+optional-to-escape      = '(' | ')' | '{' | '/' | '\'
+
+parameter               = '{', name*, '}'
+name                    = (- name-to-escape) | ('\', name-to-escape)
+name-to-escape          = '{' | '}' | '(' | '/' | '\'
+```
+
+
+
+
 ## License
 
 This project is licensed under either of
@@ -29,3 +65,6 @@ at your option.
 
 [AST]: https://en.wikipedia.org/wiki/Abstract_syntax_tree
 [Cucumber Expressions]: https://github.com/cucumber/cucumber-expressions#readme
+[EBNF]: https://en.wikipedia.org/wiki/Extended_Backus–Naur_form
+
+[1]: https://github.com/cucumber/cucumber-expressions/issues/41

src/ast.rs

@@ -0,0 +1,174 @@
+// Copyright (c) 2021  Brendan Molloy <brendan@bbqsrc.net>,
+//                     Ilya Solovyiov <ilya.solovyiov@gmail.com>,
+//                     Kai Ren <tyranron@gmail.com>
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+//! [Cucumber Expressions][1] [AST].
+//!
+//! See details in the [grammar spec][0].
+//!
+//! [0]: crate#grammar
+//! [1]: https://github.com/cucumber/cucumber-expressions#readme
+//! [AST]: https://en.wikipedia.org/wiki/Abstract_syntax_tree
+
+use derive_more::{AsRef, Deref, DerefMut};
+use nom::{error::ErrorKind, Err, InputLength};
+use nom_locate::LocatedSpan;
+
+use crate::parse;
+
+/// [`str`] along with its location information in the original input.
+pub type Spanned<'s> = LocatedSpan<&'s str>;
+
+/// Top-level `expression` defined in the [grammar spec][0].
+///
+/// See [`parse::expression()`] for the detailed grammar and examples.
+///
+/// [0]: crate#grammar
+#[derive(AsRef, Clone, Debug, Deref, DerefMut, Eq, PartialEq)]
+pub struct Expression<Input>(pub Vec<SingleExpression<Input>>);
+
+impl<'s> TryFrom<&'s str> for Expression<Spanned<'s>> {
+    type Error = parse::Error<Spanned<'s>>;
+
+    fn try_from(value: &'s str) -> Result<Self, Self::Error> {
+        parse::expression(Spanned::new(value))
+            .map_err(|e| match e {
+                Err::Error(e) | Err::Failure(e) => e,
+                Err::Incomplete(n) => parse::Error::Needed(n),
+            })
+            .and_then(|(rest, parsed)| {
+                rest.is_empty()
+                    .then(|| parsed)
+                    .ok_or(parse::Error::Other(rest, ErrorKind::Verify))
+            })
+    }
+}
+
+impl<'s> Expression<Spanned<'s>> {
+    /// Parses the given `input` as an [`Expression`].
+    ///
+    /// # Errors
+    ///
+    /// See [`parse::Error`] for details.
+    pub fn parse<I: AsRef<str> + ?Sized>(
+        input: &'s I,
+    ) -> Result<Self, parse::Error<Spanned<'s>>> {
+        Self::try_from(input.as_ref())
+    }
+}
+
+/// `single-expression` defined in the [grammar spec][0], representing a single
+/// entry of an [`Expression`].
+///
+/// See [`parse::single_expression()`] for the detailed grammar and examples.
+///
+/// [0]: crate#grammar
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum SingleExpression<Input> {
+    /// [`alternation`][0] expression.
+    ///
+    /// [0]: crate#grammar
+    Alternation(Alternation<Input>),
+
+    /// [`optional`][0] expression.
+    ///
+    /// [0]: crate#grammar
+    Optional(Optional<Input>),
+
+    /// [`parameter`][0] expression.
+    ///
+    /// [0]: crate#grammar
+    Parameter(Parameter<Input>),
+
+    /// Text without whitespaces.
+    Text(Input),
+
+    /// Whitespaces are treated as a special case to avoid placing every `text`
+    /// character in a separate [AST] node, as described in the
+    /// [grammar spec][0].
+    ///
+    /// [0]: crate#grammar
+    /// [AST]: https://en.wikipedia.org/wiki/Abstract_syntax_tree
+    Whitespaces(Input),
+}
+
+/// `single-alternation` defined in the [grammar spec][0], representing a
+/// building block of an [`Alternation`].
+///
+/// [0]: crate#grammar
+pub type SingleAlternation<Input> = Vec<Alternative<Input>>;
+
+/// `alternation` defined in the [grammar spec][0], allowing to match one of
+/// [`SingleAlternation`]s.
+///
+/// See [`parse::alternation()`] for the detailed grammar and examples.
+///
+/// [0]: crate#grammar
+#[derive(AsRef, Clone, Debug, Deref, DerefMut, Eq, PartialEq)]
+pub struct Alternation<Input>(pub Vec<SingleAlternation<Input>>);
+
+impl<Input: InputLength> Alternation<Input> {
+    /// Returns length of this [`Alternation`]'s span in the `Input`.
+    pub(crate) fn span_len(&self) -> usize {
+        self.0
+            .iter()
+            .flatten()
+            .map(|alt| match alt {
+                Alternative::Text(t) => t.input_len(),
+                Alternative::Optional(opt) => opt.input_len() + 2,
+            })
+            .sum::<usize>()
+            + self.len()
+            - 1
+    }
+
+    /// Indicates whether any of [`SingleAlternation`]s consists only from
+    /// [`Optional`]s.
+    pub(crate) fn contains_only_optional(&self) -> bool {
+        (**self).iter().any(|single_alt| {
+            single_alt
+                .iter()
+                .all(|alt| matches!(alt, Alternative::Optional(_)))
+        })
+    }
+}
+
+/// `alternative` defined in the [grammar spec][0].
+///
+/// See [`parse::alternative()`] for the detailed grammar and examples.
+///
+/// [0]: crate#grammar
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum Alternative<Input> {
+    /// [`optional`][1] expression.
+    ///
+    /// [1]: crate#grammar
+    Optional(Optional<Input>),
+
+    /// Text.
+    Text(Input),
+}
+
+/// `optional` defined in the [grammar spec][0], allowing to match an optional
+/// `Input`.
+///
+/// See [`parse::optional()`] for the detailed grammar and examples.
+///
+/// [0]: crate#grammar
+#[derive(AsRef, Clone, Copy, Debug, Deref, DerefMut, Eq, PartialEq)]
+pub struct Optional<Input>(pub Input);
+
+/// `parameter` defined in the [grammar spec][0], allowing to match some special
+/// `Input` described by a [`Parameter`] name.
+///
+/// See [`parse::parameter()`] for the detailed grammar and examples.
+///
+/// [0]: crate#grammar
+#[derive(AsRef, Clone, Copy, Debug, Deref, DerefMut, Eq, PartialEq)]
+pub struct Parameter<Input>(pub Input);