document and add some more tests

Author: nikomatsakis

book/src/formality_core/parse.md

@@ -25,9 +25,23 @@ When parsing an enum there will be multiple possibilities. We will attempt to pa
 
 * Explicit precedence: By default, every variant has precedence 0, but you can override this by annotating variants with `#[precedence(N)]` (where `N` is some integer). This will override the precedence for that variant. Variants with higher precedences are preferred.
 * Reduction prefix: When parsing, we track the list of things we had to parse. If there are two variants at the same precedence level, but one of them had to parse strictly more things than the other and in the same way, we'll prefer the longer one. So for example if one variant parsed a `Ty` and the other parsed a `Ty Ty`, we'd take the `Ty Ty`.
+    * When considering whether a reduction is "significant", we take casts into account. See `ActiveVariant::mark_as_cast_variant` for a more detailed explanation and set of examples.
 
 Otherwise, the parser will panic and report ambiguity. The parser panics rather than returning an error because ambiguity doesn't mean that there is no way to parse the given text as the nonterminal -- rather that there are multiple ways. Errors mean that the text does not match the grammar for that nonterminal.
 
+### Left-recursive grammars
+
+We permit left recursive grammars like:
+
+```
+Expr = Expr + Expr
+     | integer
+```
+
+We *always* bias towards greedy parses, so `a + b + c` parses as `(a + b) + c`.
+This might occasionally not be what you want.
+Sorry.
+
 ### Symbols
 
 A grammar consists of a series of *symbols*. Each symbol matches some text in the input string. Symbols come in two varieties:
@@ -39,11 +53,20 @@ A grammar consists of a series of *symbols*. Each symbol matches some text in th
     * If fields have names, then `$field` should name the field.
     * For position fields (e.g., the T and U in `Mul(Expr, Expr)`), use `$v0`, `$v1`, etc.
     * Exception: `$$` is treated as the terminal `'$'`.
-* Nonterminals can also accept modes:
+* Nonterminals have various modes:
     * `$field` -- just parse the field's type
     * `$*field` -- the field must be a `Vec<T>` -- parse any number of `T` instances. Something like `[ $*field ]` would parse `[f1 f2 f3]`, assuming `f1`, `f2`, and `f3` are valid values for `field`.
     * `$,field` -- similar to the above, but uses a comma separated list (with optional trailing comma). So `[ $,field ]` will parse something like `[f1, f2, f3]`.
     * `$?field` -- will parse `field` and use `Default::default()` value if not present.
+    * `$<field>` -- parse `<E1, E2, E3>`, where `field: Vec<E>` 
+    * `$<?field>` -- parse `<E1, E2, E3>`, where `field: Vec<E>`, but accept empty string as empty vector
+    * `$(field)` -- parse `(E1, E2, E3)`, where `field: Vec<E>` 
+    * `$(?field)` -- parse `(E1, E2, E3)`, where `field: Vec<E>`, but accept empty string as empty vector
+    * `$[field]` -- parse `[E1, E2, E3]`, where `field: Vec<E>` 
+    * `$[?field]` -- parse `[E1, E2, E3]`, where `field: Vec<E>`, but accept empty string as empty vector
+    * `${field}` -- parse `{E1, E2, E3}`, where `field: Vec<E>` 
+    * `${?field}` -- parse `{E1, E2, E3}`, where `field: Vec<E>`, but accept empty string as empty vector
+    * `$:guard <nonterminal>` -- parses `<nonterminal>` but only if the keyword `guard` is present. For example, `$:where $,where_clauses` would parse `where WhereClause1, WhereClause2, WhereClause3`
 
 ### Greediness
 

tests/parser-torture-tests/precedence.rs

@@ -1,24 +1,33 @@
 use formality_core::term;
 use std::sync::Arc;
 
-#[test]
-fn precedence() {
-    #[term]
-    pub enum Root {
-        #[cast]
-        Id(Id),
+#[term]
+pub enum Expr {
+    #[cast]
+    Id(Id),
 
-        #[grammar($v0 + $v1)]
-        Add(Arc<Root>, Arc<Root>),
+    #[grammar($v0 + $v1)]
+    Add(Arc<Expr>, Arc<Expr>),
 
-        #[grammar($v0 * $v1)]
-        #[precedence(1)]
-        Mul(Arc<Root>, Arc<Root>),
-    }
+    #[grammar($v0 * $v1)]
+    #[precedence(1)]
+    Mul(Arc<Expr>, Arc<Expr>),
+}
 
-    formality_core::id!(Id);
+formality_core::id!(Id);
 
-    let term: Root = crate::ptt::term("a + b * c");
+#[test]
+fn mul_is_higher_precedence() {
+    let term: Expr = crate::ptt::term("a + b * c");
+    expect_test::expect![[r#"
+        a + b * c
+    "#]]
+    .assert_debug_eq(&term);
+}
+
+#[test]
+fn equal_precedence_panics() {
+    let term: Expr = crate::ptt::term("a + b * c");
     expect_test::expect![[r#"
         a + b * c
     "#]]