rattler 0.5.0 → 0.6.0

data/features/{grammar → peg_syntax}/positive_lookahead.feature

@@ -1,8 +1,10 @@
 Feature: Positive Lookahead Operator
   
-  The "&" operator before an expression means to match only if the expression
-  would match here but never consume any input. This is known as zero-width
-  positive lookahead.
+  A positive lookahead predicate matches if a parsing expression would match
+  but the predicate consumes no input.
+
+  Positive lookahead is written by placing a "&" in front of a parsing
+  expression.
   
   Scenario Outline: Parsing
     Given a grammar with:
@@ -16,4 +18,4 @@ Feature: Positive Lookahead Operator
     | input | result |
     | "AB"  | "A"    |
     | "A"   | FAIL   |
-    | "AC"  | FAIL   |
+    | "AC"  | FAIL   |

data/features/peg_syntax/sequence.feature

@@ -0,0 +1,23 @@
+Feature: Sequences
+  
+  A sequence is a series of parsing expressions that matches if all of the
+  expressions match in sequence. If any of the parsing expressions fail, the
+  entire sequence fails and backtracks to the starting point.
+
+  A sequence is written as a series of parsing expressions separated by spaces.
+
+  Scenario Outline: Parsing
+    Given a grammar with:
+      """
+      expr <- "A" "B"
+      """
+    When I parse <input>
+    Then the parse result should be <result>
+  
+  Examples:
+    | input | result     |
+    | "AB"  | ["A", "B"] |
+    | "ABC" | ["A", "B"] |
+    | "ACB" | FAIL       |
+    | "A"   | FAIL       |
+    | "C"   | FAIL       |

data/features/{grammar → peg_syntax}/start_rule.feature

@@ -1,6 +1,6 @@
 Feature: Start Rule
   
-  The first rule defined in a grammar is the start rule.
+  By default the first rule defined in a grammar is the start rule.
   
   Scenario Outline: Default Start Rule
     Given a grammar with:

data/features/peg_syntax/zero_or_more.feature

@@ -0,0 +1,59 @@
+Feature: Zero-Or-More
+  
+  The "*" operator following a parsing expression causes it to match repeatedly
+  and succeed even if the expression never matches, i.e. it matches zero or
+  more times.
+  
+  Scenario Outline: Capturing expression
+    Given a grammar with:
+      """
+      letters <- ALPHA*
+      """
+    When I parse <input>
+    Then the parse result should be <result>
+      And the parse position should be <pos>
+  
+  Examples:
+    | input | result          | pos |
+    | "A"   | ["A"]           | 1   |
+    | "foo" | ["f", "o", "o"] | 3   |
+    | "234" | []              | 0   |
+  
+  Scenario Outline: Non-Capturing expression
+    Given a grammar with:
+      """
+      dashes <- ~"-"*
+      """
+    When I parse <input>
+    Then the parse result should be <result>
+      And the parse position should be <pos>
+  
+  Examples:
+    | input | result | pos |
+    | "-"   | true   | 1   |
+    | "---" | true   | 3   |
+    | "foo" | true   | 0   |
+
+  Scenario Outline: Choice of capturing or non-capturing
+    Given a grammar with:
+      """
+      expr  <- ("a" / ~"b")*
+      """
+    When I parse <input>
+    Then the parse result should be <result>
+      And the parse position should be <pos>
+  
+  Examples:
+    | input | result     | pos |
+    | "aa"  | ["a", "a"] | 2   |
+    | "aba" | ["a", "a"] | 3   |
+    | "bbc" | []         | 2   |
+
+  Scenario: Semantic attribute returning true
+    Given a grammar with:
+      """
+      expr  <- (ALPHA { true })*
+      """
+    When I parse "foo "
+    Then the parse result should be []
+      And the parse position should be 3

data/features/{grammar → semantics}/negative_semantic_predicate.feature

@@ -1,10 +1,31 @@
-Feature: Negative Symantic Predicates
+Feature: Negative Semantic Predicates
 
-  A negative symantic predicate can be defined by placing a "!" in front of a
-  symantic action. If the action results in a false value the parse succeeds
-  with no parse result, otherwise the parse fails.
+  Semantic predicates can be used to cause a parsing expression to either
+  continue or fail based on the result of a Ruby expression.  With a negative
+  semantic predicate the expression is evaluated and if the result is truthy
+  the parsing expression fails at that point, otherwise it continues.
 
-  Scenario Outline: Single token
+  A negative semantic predicate is written as a "!" followed by curly braces
+  surrounding a Ruby expression.
+
+  Scenario: Truthy result
+    Given a grammar with:
+      """
+      expr <- !{ 1 }
+      """
+    When I parse "anything"
+    Then the parse should fail
+
+  Scenario: False result
+    Given a grammar with:
+      """
+      expr <- !{ false }
+      """
+    When I parse "anything"
+    Then the parse result should be true
+      And the parse position should be 0
+
+  Scenario Outline: Single-capture sequence
     Given a grammar with:
       """
       expr <- @DIGIT+ !{|s| s.to_i > 20 }
@@ -17,7 +38,7 @@ Feature: Negative Symantic Predicates
     | "17"  | "17"   |
     | "42"  | FAIL   |
 
-  Scenario Outline: Sequence
+  Scenario Outline: Multi-capture sequence
     Given a grammar with:
       """
       %whitespace SPACE*
@@ -57,7 +78,7 @@ Feature: Negative Symantic Predicates
     | "(17<23)" | ["(", "17", "<", "23", ")"] |
     | "(23<17)" | FAIL         |
 
-  Scenario Outline: Single token using "_"
+  Scenario Outline: Single-capture sequence using "_"
     Given a grammar with:
       """
       expr <- @DIGIT+ !{ _.to_i > 20 }
@@ -70,7 +91,7 @@ Feature: Negative Symantic Predicates
     | "17"  | "17"   |
     | "42"  | FAIL   |
   
-  Scenario Outline: Sequence using "_"
+  Scenario Outline: Multi-capture sequence using "_"
     Given a grammar with:
       """
       %whitespace SPACE*
@@ -84,7 +105,7 @@ Feature: Negative Symantic Predicates
     | "16 3" | ["16", "3"] |
     | "3 16" | FAIL        |
 
-  Scenario Outline: Sequence using "_" as a parameter name
+  Scenario Outline: Multi-capture sequence using "_" as a parameter name
     Given a grammar with:
       """
       %whitespace SPACE*

data/features/{grammar → semantics}/positive_semantic_predicate.feature

@@ -1,10 +1,31 @@
 Feature: Positive Semantic Predicates
 
-  A positive semantic predicate can be defined by placing a "&" in front of a
-  semantic action. If the action results in a true value the parse succeeds,
-  otherwise the parse fails.
+  Semantic predicates can be used to cause a parsing expression to either
+  continue or fail based on the result of a Ruby expression.  With a positive
+  semantic predicate the expression is evaluated and if the result is truthy
+  the parsing expression continues, otherwise it fails at that point.
 
-  Scenario Outline: Single token
+  A positive semantic predicate is written as a "&" followed by curly braces
+  surrounding a Ruby expression.
+
+  Scenario: Truthy result
+    Given a grammar with:
+      """
+      expr <- &{ 1 }
+      """
+    When I parse "anything"
+    Then the parse result should be true
+      And the parse position should be 0
+  
+  Scenario: False result
+    Given a grammar with:
+      """
+      expr <- &{ false }
+      """
+    When I parse "anything"
+    Then the parse should fail
+
+  Scenario Outline: Single-capture sequence
     Given a grammar with:
       """
       expr <- @DIGIT+ &{|s| s.to_i > 20 }
@@ -17,7 +38,7 @@ Feature: Positive Semantic Predicates
     | "42"  | "42"   |
     | "17"  | FAIL   |
 
-  Scenario Outline: Sequence
+  Scenario Outline: Multi-capture sequence
     Given a grammar with:
       """
       %whitespace SPACE*
@@ -57,7 +78,7 @@ Feature: Positive Semantic Predicates
     | "(17<23)" | ["(", "17", "<", "23", ")"] |
     | "(23<17)" | FAIL         |
 
-  Scenario Outline: Single token using "_"
+  Scenario Outline: Single-capture sequence using "_"
     Given a grammar with:
       """
       expr <- @DIGIT+ &{ _.to_i > 20 }
@@ -70,7 +91,7 @@ Feature: Positive Semantic Predicates
     | "42"  | "42"   |
     | "17"  | FAIL   |
   
-  Scenario Outline: Sequence using "_"
+  Scenario Outline: Multi-capture sequence using "_"
     Given a grammar with:
       """
       %whitespace SPACE*
@@ -84,7 +105,7 @@ Feature: Positive Semantic Predicates
     | "3 16" | ["3", "16"] |
     | "16 3" | FAIL        |
 
-  Scenario Outline: Sequence using "_" as a parameter name
+  Scenario Outline: Multi-capture sequence using "_" as a parameter name
     Given a grammar with:
       """
       %whitespace SPACE*

data/features/{grammar/symantic_action.feature → semantics/semantic_action.feature}

@@ -1,6 +1,6 @@
-Feature: Symantic Actions
+Feature: Semantic Actions
   
-  A symantic action can be added between "{" and "}" following an expression.
+  A semantic action can be added between "{" and "}" following an expression.
   It means to evaluate the action as a Ruby expression if the match succeeds
   and use the result of the action as the final parse result. Parameters can be
   specified like Ruby block parameters and are bound to the parse results from

data/features/semantics/semantic_result.feature

@@ -0,0 +1,86 @@
+Feature: Semantic Results
+
+  A semantic result can be used to add a synthetic parse result using a Ruby
+  expression.  The expression is evaluated and the result is inserted like a
+  normal parse result.  This can be used to insert implicit syntax nodes into
+  a parse tree, such as optional expression terminators.  Note that a false
+  value with cause the parse to fail.
+
+  A semantic result is written as a "^" followed by curly braces surrounding a
+  Ruby expression.
+
+  Scenario: Lone result
+    Given a grammar with:
+      """
+      expr <- ^{ ";" }
+      """
+    When I parse "anything"
+    Then the parse result should be ";"
+      And the parse position should be 0
+  
+  Scenario: False result
+    Given a grammar with:
+      """
+      expr <- ^{ false }
+      """
+    When I parse "anything"
+    Then the parse should fail
+
+  Scenario: Single-capture sequence
+    Given a grammar with:
+      """
+      expr <- @DIGIT+ ^{|a| a.to_i }
+      """
+    When I parse "23"
+    Then the parse result should be ["23", 23]
+  
+  Scenario: Multi-capture sequence
+    Given a grammar with:
+      """
+      %whitespace SPACE*
+      expr <- @DIGIT+ @DIGIT+ ^{|a,b| a.to_i * b.to_i }
+      """
+    When I parse "3 16"
+    Then the parse result should be ["3", "16", 48]
+
+  Scenario: Sequence with non-capturing expressions
+    Given a grammar with:
+      """
+      expr <- ~"(" @DIGIT+ ~"+" @DIGIT+ ~")" ^{|a,b| a.to_i + b.to_i }
+      """
+    When I parse "(23+17)"
+    Then the parse result should be ["23", "17", 40]
+
+  Scenario: Sequence with labeled expressions
+    Given a grammar with:
+      """
+      expr <- "(" l:@DIGIT+ "+" r:@DIGIT+ ")" ^{ l.to_i + r.to_i }
+      """
+    When I parse "(17+29)"
+    Then the parse result should be ["(", "17", "+", "29", ")", 46]
+  
+  Scenario: Single-capture sequence using "_"
+    Given a grammar with:
+      """
+      expr <- @DIGIT+ ^{ _.to_i }
+      """
+    When I parse "23"
+    Then the parse result should be ["23", 23]
+  
+  Scenario: Multi-capture sequence using "_"
+    Given a grammar with:
+      """
+      %whitespace SPACE*
+      expr <- @DIGIT+ @DIGIT+ ^{ _.reverse }
+      """
+    When I parse "3 16"
+    Then the parse result should be ["3", "16", ["16", "3"]]
+  
+  Scenario: Multi-capture sequence using "_" as a parameter name
+    Given a grammar with:
+      """
+      %whitespace SPACE*
+      expr <- @DIGIT+ @DIGIT+ ^{|_| _.to_i }
+      """
+    When I parse "3 16"
+    Then the parse result should be ["3", "16", 3]

data/features/{grammar → semantics}/side_effect.feature

@@ -1,19 +1,41 @@
 Feature: Semantic side-effects
 
-  A semantic side-effect can be defined by placing a "~" in front of a symantic
-  action. The expression is evaulated for effect and always succeeds with no
-  parse result.
+  Semantic side effects can be used to set or change some state during a parse
+  using a Ruby expression without directly affecting the parse.  The expression
+  is evaluated for effect and its result is discarded.
 
-  Scenario: Single token
+  A semantic side-effect is written as a "~" followed by curly braces
+  surrounding a Ruby expression.
+
+  Scenario: Lone action
     Given a grammar with:
       """
-      expr <- @DIGIT+ ~{|s| $x = s.to_i }
+      expr <- ~{ $x = 42 }
       """
-    When I parse "42 "
-    Then the parse result should be "42"
+    When I parse "anything"
+    Then the parse result should be true
       And $x should be 42
+      And the parse position should be 0
+  
+  Scenario: False result
+    Given a grammar with:
+      """
+      expr <- ~{ false }
+      """
+    When I parse "anything"
+    Then the parse result should be true
+      And the parse position should be 0
 
-  Scenario: Sequence
+  Scenario: Single-capture sequence
+    Given a grammar with:
+      """
+      expr <- @DIGIT+ ~{|a| $x = a.to_i }
+      """
+    When I parse "23"
+    Then the parse result should be "23"
+      And $x should be 23
+  
+  Scenario: Multi-capture sequence
     Given a grammar with:
       """
       %whitespace SPACE*
@@ -41,7 +63,7 @@ Feature: Semantic side-effects
     Then the parse result should be ["(", "17", "+", "29", ")"]
       And $x should be 46
   
-  Scenario: Single token using "_"
+  Scenario: Single-capture sequence using "_"
     Given a grammar with:
       """
       expr <- @DIGIT+ ~{ $x = _.to_i }
@@ -50,7 +72,7 @@ Feature: Semantic side-effects
     Then the parse result should be "23"
       And $x should be 23
   
-  Scenario: Sequence using "_"
+  Scenario: Multi-capture sequence using "_"
     Given a grammar with:
       """
       %whitespace SPACE*
@@ -60,7 +82,7 @@ Feature: Semantic side-effects
     Then the parse result should be ["3", "16"]
       And $x should be ["16", "3"]
   
-  Scenario: Sequence using "_" as a parameter name
+  Scenario: Multi-capture sequence using "_" as a parameter name
     Given a grammar with:
       """
       %whitespace SPACE*
@@ -69,13 +91,3 @@ Feature: Semantic side-effects
     When I parse "3 16"
     Then the parse result should be ["3", "16"]
       And $x should be 3
-
-  Scenario: Lone action
-    Given a grammar with:
-      """
-      expr <- ~{ $x = 42 }
-      """
-    When I parse "anything"
-    Then the parse result should be true
-      And $x should be 42
-      And the parse position should be 0

data/features/step_definitions/cli_steps.rb

@@ -1,3 +1,3 @@
-Then /^the file "([^"]+)" should contain:$/ do |file, partial_content|
+Then /^the file "([^\"]+)" should contain:$/ do |file, partial_content|
   check_file_content(file, partial_content, true)
 end