citrus 2.4.0 → 2.4.1

data/CHANGES

@@ -1,3 +1,9 @@
+= 2.4.1 / 2011-11-04
+
+  * Fixed a bug that prevented rule names from starting with "super".
+
+  * Several minor bug fixes.
+
 = 2.4.0 / 2011-05-11
 
   * Fixed a bug that prevented parsing nested blocks correctly (issue #21).

data/{README → README.md}

@@ -1,9 +1,4 @@
-
-
-                                  ~* Citrus *~
-
-                          Parsing Expressions for Ruby
-
+Citrus :: Parsing Expressions for Ruby
 
 Citrus is a compact and powerful parsing library for
 [Ruby](http://ruby-lang.org/) that combines the elegance and expressiveness of
@@ -52,13 +47,13 @@ In Citrus, there are three main types of objects: rules, grammars, and matches.
 
 ## Rules
 
-A [Rule](api/classes/Citrus/Rule.html) is an object that specifies some matching
-behavior on a string. There are two types of rules: terminals and non-terminals.
-Terminals can be either Ruby strings or regular expressions that specify some
-input to match. For example, a terminal created from the string "end" would
-match any sequence of the characters "e", "n", and "d", in that order. Terminals
-created from regular expressions may match any sequence of characters that can
-be generated from that expression.
+A [Rule](http://mjijackson.com/citrus/api/classes/Citrus/Rule.html) is an object
+that specifies some matching behavior on a string. There are two types of rules:
+terminals and non-terminals. Terminals can be either Ruby strings or regular
+expressions that specify some input to match. For example, a terminal created
+from the string "end" would match any sequence of the characters "e", "n", and
+"d", in that order. Terminals created from regular expressions may match any
+sequence of characters that can be generated from that expression.
 
 Non-terminals are rules that may contain other rules but do not themselves match
 directly on the input. For example, a Repeat is a non-terminal that may contain
@@ -70,9 +65,9 @@ of Ruby modules. Rules use these modules to extend the matches they create.
 
 ## Grammars
 
-A [Grammar](api/classes/Citrus/Grammar.html) is a container for rules. Usually
-the rules in a grammar collectively form a complete specification for some
-language, or a well-defined subset thereof.
+A [Grammar](http://mjijackson.com/citrus/api/classes/Citrus/Grammar.html) is a
+container for rules. Usually the rules in a grammar collectively form a complete
+specification for some language, or a well-defined subset thereof.
 
 A Citrus grammar is really just a souped-up Ruby
 [module](http://ruby-doc.org/core/classes/Module.html). These modules may be
@@ -84,8 +79,9 @@ Ruby's `super` keyword.
 
 ## Matches
 
-A [Match](api/classes/Citrus/Match.html) object represents a successful
-recognition of some piece of the input. Matches are created by rule objects during a parse.
+A [Match](http://mjijackson.com/citrus/api/classes/Citrus/Match.html) object
+represents a successful recognition of some piece of the input. Matches are
+created by rule objects during a parse.
 
 Matches are arranged in a tree structure where any match may contain any number
 of other matches. Each match contains information about its own subtree. The
@@ -132,8 +128,9 @@ match in a case-insensitive manner.
 Besides case sensitivity, case-insensitive strings have the same behavior as
 double quoted strings.
 
-See [Terminal](api/classes/Citrus/Terminal.html) and
-[StringTerminal](api/classes/Citrus/StringTerminal.html) for more information.
+See [Terminal](http://mjijackson.com/citrus/api/classes/Citrus/Terminal.html) and
+[StringTerminal](http://mjijackson.com/citrus/api/classes/Citrus/StringTerminal.html)
+for more information.
 
 ## Repetition
 
@@ -156,7 +153,8 @@ The `+` and `?` operators are supported as well for the common cases of `1*` and
     'abc'+        # match "abc" one or more times
     'abc'?        # match "abc" zero or one time
 
-See [Repeat](api/classes/Citrus/Repeat.html) for more information.
+See [Repeat](http://mjijackson.com/citrus/api/classes/Citrus/Repeat.html) for
+more information.
 
 ## Lookahead
 
@@ -164,7 +162,7 @@ Both positive and negative lookahead are supported in Citrus. Use the `&` and
 `!` operators to indicate that an expression either should or should not match.
 In neither case is any input consumed.
 
-    &'a' 'b'      # match a "b" preceded by an "a"
+    'a' &'b'      # match an "a" that is followed by a "b"
     'a' !'b'      # match an "a" that is not followed by a "b"
     !'a' .        # match any character except for "a"
 
@@ -177,9 +175,10 @@ that does not match a given expression.
 When using this operator (the tilde), at least one character must be consumed
 for the rule to succeed.
 
-See [AndPredicate](api/classes/Citrus/AndPredicate.html),
-[NotPredicate](api/classes/Citrus/NotPredicate.html), and
-[ButPredicate](api/classes/Citrus/ButPredicate.html) for more information.
+See [AndPredicate](http://mjijackson.com/citrus/api/classes/Citrus/AndPredicate.html),
+[NotPredicate](http://mjijackson.com/citrus/api/classes/Citrus/NotPredicate.html),
+and [ButPredicate](http://mjijackson.com/citrus/api/classes/Citrus/ButPredicate.html)
+for more information.
 
 ## Sequences
 
@@ -189,7 +188,8 @@ should match in that order.
     'a' 'b' 'c'   # match "a", then "b", then "c"
     'a' [0-9]     # match "a", then a numeric digit
 
-See [Sequence](api/classes/Citrus/Sequence.html) for more information.
+See [Sequence](http://mjijackson.com/citrus/api/classes/Citrus/Sequence.html)
+for more information.
 
 ## Choices
 
@@ -204,7 +204,8 @@ It is important to note when using ordered choice that any operator binds more
 tightly than the vertical bar. A full chart of operators and their respective
 levels of precedence is below.
 
-See [Choice](api/classes/Citrus/Choice.html) for more information.
+See [Choice](http://mjijackson.com/citrus/api/classes/Citrus/Choice.html) for
+more information.
 
 ## Labels
 
@@ -245,14 +246,14 @@ same name as a rule in the parent also have access to the `super` keyword to
 invoke the parent rule.
 
     grammar Number
-      def number
+      rule number
         [0-9]+
       end
     end
-    
+
     grammar FloatingPoint
       include Number
-      
+
       rule number
         super ('.' super)?
       end
@@ -262,33 +263,34 @@ In the example above, the `FloatingPoint` grammar includes `Number`. Both have a
 rule named `number`, so `FloatingPoint#number` has access to `Number#number` by
 means of using `super`.
 
-See [Super](api/classes/Citrus/Super.html) for more information.
+See [Super](http://mjijackson.com/citrus/api/classes/Citrus/Super.html) for more
+information.
 
 ## Precedence
 
 The following table contains a list of all Citrus symbols and operators and
 their precedence. A higher precedence indicates tighter binding.
 
-Operator  | Name                      | Precedence
---------- | ------------------------- | ----------
-''        | String (single quoted)    | 7
-""        | String (double quoted)    | 7
-``        | String (case insensitive) | 7
-[]        | Character class           | 7
-.         | Dot (any character)       | 7
-//        | Regular expression        | 7
-()        | Grouping                  | 7
-*         | Repetition (arbitrary)    | 6
-+         | Repetition (one or more)  | 6
-?         | Repetition (zero or one)  | 6
-&         | And predicate             | 5
-!         | Not predicate             | 5
-~         | But predicate             | 5
-<>        | Extension (module name)   | 4
-{}        | Extension (literal)       | 4
-:         | Label                     | 3
-e1 e2     | Sequence                  | 2
-e1 | e2   | Ordered choice            | 1
+Operator                  | Name                      | Precedence
+------------------------- | ------------------------- | ----------
+`''`                      | String (single quoted)    | 7
+`""`                      | String (double quoted)    | 7
+<code>``</code>           | String (case insensitive) | 7
+`[]`                      | Character class           | 7
+`.`                       | Dot (any character)       | 7
+`//`                      | Regular expression        | 7
+`()`                      | Grouping                  | 7
+`*`                       | Repetition (arbitrary)    | 6
+`+`                       | Repetition (one or more)  | 6
+`?`                       | Repetition (zero or one)  | 6
+`&`                       | And predicate             | 5
+`!`                       | Not predicate             | 5
+`~`                       | But predicate             | 5
+`<>`                      | Extension (module name)   | 4
+`{}`                      | Extension (literal)       | 4
+`:`                       | Label                     | 3
+`e1 e2`                   | Sequence                  | 2
+<code>e1 &#124; e2</code> | Ordered choice            | 1
 
 ## Grouping
 
@@ -310,15 +312,15 @@ integers separated by any amount of white space and a `+` symbol.
       rule additive
         number plus (additive | number)
       end
-      
+
       rule number
         [0-9]+ space
       end
-      
+
       rule plus
         '+' space
       end
-      
+
       rule space
         [ \t]*
       end
@@ -341,8 +343,9 @@ and "1 + 2+3", but it does not have enough semantic information to be able to
 actually interpret these expressions.
 
 At this point, when the grammar parses a string it generates a tree of
-[Match](api/classes/Citrus/Match.html) objects. Each match is created by a rule
-and may itself be comprised of any number of submatches.
+[Match](http://mjijackson.com/citrus/api/classes/Citrus/Match.html) objects.
+Each match is created by a rule and may itself be comprised of any number of
+submatches.
 
 Submatches are created whenever a rule contains another rule. For example, in
 the grammar above `number` matches a string of digits followed by white space.
@@ -358,17 +361,17 @@ blocks. Let's extend the `Addition` grammar using this technique.
           number.value + term.value
         }
       end
-      
+
       rule number
         ([0-9]+ space) {
           to_i
         }
       end
-      
+
       rule plus
         '+' space
       end
-      
+
       rule space
         [ \t]*
       end
@@ -415,14 +418,14 @@ commands in a terminal.
 Congratulations! You just ran your first piece of Citrus code.
 
 One interesting thing to notice about the above sequence of commands is the
-return value of [Citrus#load](api/classes/Citrus.html#M000003). When you use
-`Citrus.load` to load a grammar file (and likewise
-[Citrus#eval](api/classes/Citrus.html#M000004) to evaluate a raw string of
-grammar code), the return value is an array of all the grammars present in that
-file.
+return value of [Citrus#load](http://mjijackson.com/citrus/api/classes/Citrus.html#M000003).
+When you use `Citrus.load` to load a grammar file (and likewise
+[Citrus#eval](http://mjijackson.com/citrus/api/classes/Citrus.html#M000004) to
+evaluate a raw string of grammar code), the return value is an array of all the
+grammars present in that file.
 
 Take a look at
-[examples/calc.citrus](http://github.com/mjijackson/citrus/blob/master/examples/calc.citrus)
+[calc.citrus](http://github.com/mjijackson/citrus/blob/master/lib/citrus/grammars/calc.citrus)
 for an example of a calculator that is able to parse and evaluate more complex
 mathematical expressions.
 
@@ -431,20 +434,20 @@ mathematical expressions.
 If you need more than just a `value` method on your match object, you can attach
 additional methods as well. There are two ways to do this. The first lets you
 define additional methods inline in your semantic block. This block will be used
-to create a new Module using [Module#new](http://ruby-doc.org/core/classes/Module.html#M001682). Using the
-`Addition` example above, we might refactor the `additive` rule to look like
-this:
+to create a new Module using [Module#new](http://ruby-doc.org/core/classes/Module.html#M001682).
+Using the `Addition` example above, we might refactor the `additive` rule to
+look like this:
 
     rule additive
       (number plus term:(additive | number)) {
         def lhs
           number.value
         end
-        
+
         def rhs
           term.value
         end
-        
+
         def value
           lhs + rhs
         end
@@ -474,11 +477,11 @@ define the following module.
       def lhs
         number.value
       end
-      
+
       def rhs
         term.value
       end
-      
+
       def value
         lhs + rhs
       end
@@ -510,7 +513,7 @@ case that could be used to test that our grammar works properly.
         assert_equal('23 + 12', match)
         assert_equal(35, match.value)
       end
-      
+
       def test_number
         match = Addition.parse('23', :root => :number)
         assert(match)
@@ -530,11 +533,11 @@ made to test equality of match objects with string values.
 
 ## Debugging
 
-When a parse fails, a [ParseError](api/classes/Citrus/ParseError.html) object is
-generated which provides a wealth of information about exactly where the parse
-failed including the offset, line number, line text, and line offset. Using this
-object, you could possibly provide some useful feedback to the user about why
-the input was bad. The following code demonstrates one way to do this.
+When a parse fails, a [ParseError](http://mjijackson.com/citrus/api/classes/Citrus/ParseError.html)
+object is generated which provides a wealth of information about exactly where
+the parse failed including the offset, line number, line text, and line offset.
+Using this object, you could possibly provide some useful feedback to the user
+about why the input was bad. The following code demonstrates one way to do this.
 
     def parse_some_stuff(stuff)
       match = StuffGrammar.parse(stuff)
@@ -606,7 +609,7 @@ included here for those who may wish to explore an alternative implementation.
 # License
 
 
-Copyright 2010 Michael Jackson
+Copyright 2010-2011 Michael Jackson
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -618,10 +621,10 @@ furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in
 all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+The software is provided "as is", without warranty of any kind, express or
+implied, including but not limited to the warranties of merchantability,
+fitness for a particular purpose and non-infringement. In no event shall the
+authors or copyright holders be liable for any claim, damages or other
+liability, whether in an action of contract, tort or otherwise, arising from,
+out of or in connection with the software or the use or other dealings in
+the software.

data/citrus.gemspec

@@ -20,7 +20,7 @@ Gem::Specification.new do |s|
     Dir['extras/**'] +
     Dir['lib/**/*.rb'] +
     Dir['test/**/*'] +
-    %w< citrus.gemspec Rakefile README CHANGES >
+    %w< citrus.gemspec Rakefile README.md CHANGES >
 
   s.test_files = s.files.select {|path| path =~ /^test\/.*_test.rb/ }
 
@@ -28,7 +28,7 @@ Gem::Specification.new do |s|
 
   s.has_rdoc = true
   s.rdoc_options = %w< --line-numbers --inline-source --title Citrus --main Citrus >
-  s.extra_rdoc_files = %w< README CHANGES >
+  s.extra_rdoc_files = %w< README.md CHANGES >
 
   s.homepage = 'http://mjijackson.com/citrus'
 end

data/doc/syntax.markdown

@@ -62,7 +62,7 @@ Both positive and negative lookahead are supported in Citrus. Use the `&` and
 `!` operators to indicate that an expression either should or should not match.
 In neither case is any input consumed.
 
-    &'a' 'b'      # match a "b" preceded by an "a"
+    'a' &'b'      # match an "a" that is followed by a "b"
     'a' !'b'      # match an "a" that is not followed by a "b"
     !'a' .        # match any character except for "a"
 
@@ -143,14 +143,14 @@ same name as a rule in the parent also have access to the `super` keyword to
 invoke the parent rule.
 
     grammar Number
-      def number
+      rule number
         [0-9]+
       end
     end
-    
+
     grammar FloatingPoint
       include Number
-      
+
       rule number
         super ('.' super)?
       end

data/lib/citrus/file.rb

@@ -165,7 +165,7 @@ module Citrus
     end
 
     rule :super do
-      all('super', :space) {
+      all('super', andp(" "), :space) {
         Super.new
       }
     end

data/lib/citrus/grammars.rb

@@ -8,4 +8,5 @@
 
 require 'citrus'
 
-$LOAD_PATH.unshift(::File.expand_path('../grammars', __FILE__))
+grammars = ::File.expand_path(::File.join('..', 'grammars'), __FILE__)
+$LOAD_PATH.unshift(grammars) unless $LOAD_PATH.include?(grammars)

data/lib/citrus/version.rb

@@ -1,6 +1,6 @@
 module Citrus
   # The current version of Citrus as [major, minor, patch].
-  VERSION = [2, 4, 0]
+  VERSION = [2, 4, 1]
 
   # Returns the current version of Citrus as a string.
   def self.version

data/test/_files/file3.citrus

@@ -0,0 +1,9 @@
+grammar SuperThree
+  rule keyword
+    super_keyword | "keyword"
+  end
+
+  rule super_keyword
+    "super"
+  end
+end

data/test/_files/rule5.citrus

@@ -0,0 +1 @@
+rule super '' end