rattler 0.5.0 → 0.6.0

data/features/{grammar → extended_matching_syntax}/skip_operator.feature

@@ -1,6 +1,7 @@
 Feature: Skip Operator
   
-  The "~" operator before an expression means to match but ignore the result.
+  The "~" operator in front of a parsing expression causes the expression's
+  parse result to be discarded.
   
   Scenario: Sequence with skipped sub-expressions
     Given a grammar with:

data/features/extended_matching_syntax/super.feature

@@ -0,0 +1,24 @@
+Feature: super keyword
+
+  A rule that redefines a rule from an included grammar can match using the
+  included grammar's version of the rule by using the "super" keyword.
+
+  Scenario Outline: Included Grammar
+    Given a grammar called "ExprGrammar" with:
+      """
+      expr <- "A"
+      """
+    And a grammar with:
+      """
+      include ExprGrammar
+      
+      expr <- super / "B"
+      """
+    When I parse <input>
+    Then the parse result should be <result>
+
+  Examples:
+    | input | result |
+    | "A"   | "A"    |
+    | "B"   | "B"    |
+    | "C"   | FAIL   |

data/features/{grammar → extended_matching_syntax}/token.feature

@@ -1,9 +1,10 @@
 Feature: Token Operator
   
-  The "@" operator before an expression means match as a token, i.e the result
-  is the entire matched string and whitespace within the token is never
-  automatically skipped. The expression becomes atomic, so any defined
-  whitespace will be automatically skipped before the token.
+  The "@" operator in front of a parsing expression causes it to match as a
+  token. The parse result is the entire string matched by the expression, and
+  whitespace is never automatically skipped within the expression. The
+  expression becomes atomic, so any defined whitespace will be automatically
+  skipped before the token is matched.
   
   Scenario: Nested sequences and repeats
     Given a grammar with:
@@ -19,7 +20,7 @@ Feature: Token Operator
       %whitespace SPACE*
       number <- @("-"? DIGIT+ ("." DIGIT+)?)
       """
-    When I parse "23 . 45"
+    When I parse "  23 . 45"
     Then the parse result should be "23"
   
   Scenario: With non-capturing sub-expressions

data/features/{grammar → extended_matching_syntax}/whitespace.feature

@@ -1,10 +1,11 @@
-Feature: Whitespace
+Feature: Whitespace Skipping
   
   The "%whitespace" directive allows whitespace to defined in one place and
-  skipped automatically by all atomic expressions. "%whitespace" is followed by
-  a parsing expression and an optional block delimited by "{" and "}". The block
-  form defines whitespace for expressions in the block, otherwise it is defined
-  for the rest of the grammar.
+  skipped automatically by all atomic expressions.
+
+  "%whitespace" is followed by a parsing expression that defines how to match
+  whitespace. The directive can be optionally followed by a block delimited
+  by curly braces to limit whitespace skipping to rules inside the block.
   
   Scenario: Block form
     Given a grammar with:
@@ -16,7 +17,7 @@ Feature: Whitespace
     When I parse "  foo"
     Then the parse result should be "foo"
   
-  Scenario: Shorcut form
+  Scenario: Global form
     Given a grammar with:
       """
       %whitespace SPACE*

data/features/{grammar → extended_matching_syntax}/word_literal.feature

@@ -1,10 +1,13 @@
 Feature: Word Literal Expressions
+
+  A word literal is like a string literal but matches only if it is not
+  followed by a word character.  Word literals are useful to match whole words
+  only.   What is considered a word character can be defined using the
+  %word_character directive.  By default a word charactacter is an alphanumeric
+  character or the underscore character.
   
-  A word literal is like a string literal but delimited with backquotes (`) and
-  it means to match the literal only if it is not followed by a word character.
-  It is useful when you want to match whole words only. What is considered a
-  word character can be defined using the %word_character directive. By default
-  a word charactacter is an alphanumeric character or the underscore character.
+  A word literal is written like a string literal but delimited with backquotes
+  (`) instead of double or single quotes.
   
   Scenario Outline: Default word character definition
     Given a grammar with:
@@ -33,4 +36,5 @@ Feature: Word Literal Expressions
   Examples:
     | input      | result |
     | "for "     | "for"  |
-    | "for-each" | FAIL   |
+    | "for-each" | FAIL   |
+  

data/features/grammar_heading/explicit_start_rule.feature

@@ -0,0 +1,20 @@
+Feature: Explicit Start Rule
+
+  The "%start" directive allows the specification of an explicit start rule.
+  By default the first rule defined in a grammar is the start rule.
+
+  Scenario Outline: Explicit Start Rule
+    Given a grammar with:
+      """
+      %start  word
+      
+      integer <-  @DIGIT+
+      word    <-  @ALPHA+
+      """
+    When I parse <input>
+    Then the parse result should be <result>
+  
+  Examples:
+    | input | result |
+    | "42"  | FAIL   |
+    | "foo" | "foo"  |

data/features/grammar_heading/grammar_declaration.feature

@@ -0,0 +1,60 @@
+Feature: Grammar Declaration
+
+  The grammar declaration names the grammar and tells rattler whether to
+  generate a grammar module or a parser class. In the case of the parser class,
+  the declaration also specifies the base class.
+
+  The declaration for a grammar module is "grammar" followed by a module name.
+
+  The declaration for a parser class is "parser", then a class name, then "<",
+  then the base class.
+  
+  Scenario: Grammar module
+    Given a grammar with:
+      """
+      grammar MyGrammar
+      """
+    When I generate parser code
+    Then the code should contain:
+      """
+      # @private
+      module MyGrammar
+      """
+
+  Scenario: Parser class
+    Given a grammar with:
+      """
+      parser MyParser < Rattler::Runtime::PackratParser
+      """
+    When I generate parser code
+    Then the code should contain:
+      """
+      # @private
+      class MyParser < Rattler::Runtime::PackratParser
+      """
+
+  Scenario: Grammar module in a module
+    Given a grammar with:
+      """
+      grammar MyModule::MyGrammar
+      """
+    When I generate parser code
+    Then the code should contain:
+      """
+      module MyModule
+        # @private
+        module MyGrammar
+      """
+
+  Scenario: Parser class in a module
+    Given a grammar with:
+      """
+      parser MyModule::MyParser < Rattler::Runtime::PackratParser
+      """
+    When I generate parser code
+    Then the code should contain:
+      """
+      module MyModule
+        # @private
+        class MyParser < Rattler::Runtime::PackratParser
+      """

data/features/grammar_heading/include.feature

@@ -0,0 +1,19 @@
+Feature: include
+
+  Any "include" statements in the grammar heading get placed at the top of the
+  class or module definition in the generated code.
+
+  Scenario:
+    Given a grammar with:
+      """
+      grammar MyGrammar
+
+      include MyHelper
+      """
+    When I generate parser code
+    Then the code should contain:
+      """
+      module MyGrammar #:nodoc:
+        
+        include MyHelper
+      """

data/features/grammar_heading/require.feature

@@ -0,0 +1,27 @@
+Feature: require
+
+  Any "require" statements in the grammar heading get placed at the top of the
+  generated code. If "require_relative" is use it gets converted into an
+  equivalent "require" statement compatible with Ruby 1.8.7.
+
+  Scenario: require
+    Given a grammar with:
+      """
+      require "logger"
+      """
+    When I generate parser code
+    Then the code should contain:
+      """
+      require "logger"
+      """
+
+  Scenario: require_relative
+    Given a grammar with:
+      """
+      require_relative "my_helper"
+      """
+    When I generate parser code
+    Then the code should contain:
+      """
+      require File.expand_path("my_helper", File.dirname(__FILE__))
+      """

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

@@ -1,6 +1,6 @@
 Feature: "Any Character" Symbol
 
-  The "." (period) means match any single character.
+  A "." (period) matches any single character.
 
   Scenario Outline: Parsing
     Given a grammar with:

data/features/peg_syntax/character_class.feature

@@ -0,0 +1,25 @@
+Feature: Character Classes
+
+  A character class defines a set of characters and matches any single
+  character in the set.
+
+  A character class is written as square brackets surrounding a set of
+  characters.
+
+  Character classes are identical in syntax and semantics to character classes
+  in Ruby's regular expressions.
+  
+  Scenario Outline: Parsing
+    Given a grammar with:
+      """
+      word_char <- [A-Za-z_]
+      """
+    When I parse <input>
+    Then the parse result should be <result>
+  
+  Examples:
+    | input | result |
+    | "foo" | "f"    |
+    | "BAR" | "B"    |
+    | "_ba" | "_"    |
+    | "42"  | FAIL   |

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

@@ -1,4 +1,4 @@
-Feature: Whitespace
+Feature: Comments
   
   Comments start with "#" and continue to the end of the line.
   

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

@@ -1,7 +1,9 @@
-Feature: Literal Expressions
+Feature: String Literals
+
+  A string literal matches exact text.  The expression matches if the exact
+  text is next in the input.
   
-  A string literal has the same syntax as a Ruby string literal and it means to
-  match if that exact text is next in the input.
+  A string literal is written exactly like a Ruby string literal.
   
   Scenario Outline: Normal String
     Given a grammar with:

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

@@ -1,8 +1,10 @@
 Feature: Negative Lookahead Operator
   
-  The "!" operator before an expression means to match only if the expression
-  would not match here and never consume any input. This is known as zero-width
-  negative lookahead.
+  A negative lookahead predicate matches only if a parsing expression would NOT
+  match and never consumes input.
+
+  Negative lookahead is written by placing a "!" in front of a parsing
+  expression.
   
   Scenario Outline: Parsing
     Given a grammar with:

data/features/peg_syntax/nonterminal.feature

@@ -0,0 +1,46 @@
+Feature: Nonterminals
+
+  A nonterminal is a reference to another parse rule that matches according to
+  that rule.  Nonterminals can be used to factor the grammar or to define
+  recursive rules.
+  
+  A nonterminal is simply the name of the other rule.
+  
+  Scenario: Simple example
+    Given a grammar with:
+      """
+      expr  <-  a* "b"
+      a     <-  "a"
+      """
+    When I parse "aaab"
+    Then the parse result should be [["a", "a", "a"], "b"]
+  
+  Scenario: Recursive definition
+    Given a grammar with:
+      """
+      expr  <-  xs "y"
+      xs    <-  "x" xs
+              / "x"
+      """
+    When I parse "xxxy"
+    Then the parse result should be [["x", ["x", "x"]], "y"]
+
+  Scenario: Direct left-recursion
+    Given a grammar with:
+      """
+      xs  <-  xs "x"
+            / "x"
+      """
+    When I parse "xxxx"
+    Then the parse result should be [[["x", "x"], "x"], "x"]
+
+  Scenario: Indirect left-recursion
+    Given a grammar with:
+      """
+      a   <-  b "x"
+            / "y"
+      b   <-  a "y"
+            / "x"
+      """
+    When I parse "xxyx"
+    Then the parse result should be [[["x", "x"], "y"], "x"]

data/features/peg_syntax/one_or_more.feature

@@ -0,0 +1,59 @@
+Feature: One-Or-More
+  
+  The "+" operator following a parsing expression causes it to match repeatedly
+  and succeed if the expression matches at least once, i.e. it matches one or
+  more times.
+  
+  Scenario Outline: Capturing Expression
+    Given a grammar with:
+      """
+      digits <- DIGIT+
+      """
+    When I parse <input>
+    Then the parse result should be <result>
+      And the parse position should be <pos>
+  
+  Examples:
+    | input | result          | pos |
+    | "5"   | ["5"]           | 1   |
+    | "234" | ["2", "3", "4"] | 3   |
+    | "foo" | FAIL            | 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" | FAIL   | 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 → peg_syntax}/optional.feature

@@ -1,7 +1,7 @@
 Feature: Optional Operator
   
-  The "?" operator following an expression makes the it optional, meaning it
-  succeeds even if no input is matched.
+  The "?" operator following a parsing expression makes it optional, so that it
+  succeeds even if the expression does not match.
   
   Scenario Outline: Capturing Expression
     Given a grammar with:

data/features/peg_syntax/ordered_choice.feature

@@ -0,0 +1,24 @@
+Feature: Ordered Choice
+  
+  An ordered choice tries a series of parsing expressions in order until one
+  matches, and fails if none of the expressions match.  The first expression
+  that matches is the one that is used.
+
+  An ordered choice is written as a series of parsing expressions separated by
+  "/".  The "/" has the lowest precedence.
+  
+  Scenario Outline: Parsing
+    Given a grammar with:
+      """
+      expr <- "A" / "B"
+      """
+    When I parse <input>
+    Then the parse result should be <result>
+  
+  Examples:
+    | input | result |
+    | "A"   | "A"    |
+    | "AB"  | "A"    |
+    | "B"   | "B"    |
+    | "BA"  | "B"    |
+    | "C"   | FAIL   |