citrus 2.3.2 → 2.3.3

data/README

@@ -206,15 +206,6 @@ levels of precedence is below.
 
 See [Choice](api/classes/Citrus/Choice.html) for more information.
 
-## Grouping
-
-As is common in many programming languages, parentheses may be used to override
-the normal binding order of operators. In the following example parentheses are
-used to make the vertical bar between `'b'` and `'c'` bind tighter than the
-space between `'a'` and `'b'`.
-
-    'a' ('b' | 'c')   # match "a", then "b" or "c"
-
 ## Labels
 
 Match objects may be referred to by a different name than the rule that
@@ -299,6 +290,15 @@ Operator  | Name                      | Precedence
 e1 e2     | Sequence                  | 2
 e1 | e2   | Ordered choice            | 1
 
+## Grouping
+
+As is common in many programming languages, parentheses may be used to override
+the normal binding order of operators. In the following example parentheses are
+used to make the vertical bar between `'b'` and `'c'` bind tighter than the
+space between `'a'` and `'b'`.
+
+    'a' ('b' | 'c')   # match "a", then "b" or "c"
+
 
 # Example
 
@@ -510,7 +510,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)
@@ -567,9 +567,29 @@ To install the [Vim](http://www.vim.org/) scripts, copy the files in
 [runtimepath](http://vimdoc.sourceforge.net/htmldoc/options.html#\'runtimepath\').
 
 
+# Examples
+
+
+The project source directory contains several example scripts that demonstrate
+how grammars are to be constructed and used. Each Citrus file in the examples
+directory has an accompanying Ruby file with the same name that contains a suite
+of tests for that particular file.
+
+The best way to run any of these examples is to pass the name of the Ruby file
+directly to the Ruby interpreter on the command line, e.g.:
+
+    $ ruby -Ilib examples/calc.rb
+
+This particular invocation uses the `-I` flag to ensure that you are using the
+version of Citrus that was bundled with that particular example file (i.e. the
+version that is contained in the `lib` directory).
+
+
 # Links
 
 
+Discussion around Citrus happens on the [citrus-users Google group](http://groups.google.com/group/citrus-users).
+
 The primary resource for all things to do with parsing expressions can be found
 on the original [Packrat and Parsing Expression Grammars page](http://pdos.csail.mit.edu/~baford/packrat)
 at MIT.

data/Rakefile

@@ -6,7 +6,7 @@ task :default => :test
 # TESTS #######################################################################
 
 Rake::TestTask.new(:test) do |t|
-  t.test_files = FileList['test/*_test.rb']
+  t.test_files = FileList['test/*_test.rb'] + FileList['examples/*.rb']
 end
 
 # DOCS ########################################################################

data/citrus.gemspec

@@ -1,6 +1,6 @@
 $LOAD_PATH.unshift(File.expand_path('../lib', __FILE__))
 
-require 'citrus'
+require 'citrus/version'
 
 Gem::Specification.new do |s|
   s.name = 'citrus'

data/doc/syntax.markdown

@@ -104,15 +104,6 @@ levels of precedence is below.
 
 See [Choice](api/classes/Citrus/Choice.html) for more information.
 
-## Grouping
-
-As is common in many programming languages, parentheses may be used to override
-the normal binding order of operators. In the following example parentheses are
-used to make the vertical bar between `'b'` and `'c'` bind tighter than the
-space between `'a'` and `'b'`.
-
-    'a' ('b' | 'c')   # match "a", then "b" or "c"
-
 ## Labels
 
 Match objects may be referred to by a different name than the rule that
@@ -196,3 +187,12 @@ Operator                  | Name                      | Precedence
 `:`                       | Label                     | 3
 `e1 e2`                   | Sequence                  | 2
 <code>e1 &#124; e2</code> | Ordered choice            | 1
+
+## Grouping
+
+As is common in many programming languages, parentheses may be used to override
+the normal binding order of operators. In the following example parentheses are
+used to make the vertical bar between `'b'` and `'c'` bind tighter than the
+space between `'a'` and `'b'`.
+
+    'a' ('b' | 'c')   # match "a", then "b" or "c"

data/examples/calc.citrus

@@ -1,8 +1,7 @@
 # A grammar for mathematical formulas that apply basic mathematical operations
 # to all numbers, respecting operator precedence and grouping of expressions
-# while ignoring whitespace.
-#
-# An identical grammar that is written using pure Ruby can be found in calc.rb.
+# while ignoring whitespace. This grammar should provide the same interpretation
+# as Ruby for all mathematical expressions.
 grammar Calc
 
   ## Hierarchical syntax

data/examples/calc.rb

@@ -1,114 +1,121 @@
+# This file contains a suite of tests for the Calc grammar found in calc.citrus.
+
 require 'citrus'
+Citrus.require File.expand_path('../calc', __FILE__)
+require 'test/unit'
+
+class CalcTest < Test::Unit::TestCase
+  # A helper method that tests the successful parsing and evaluation of the
+  # given mathematical expression.
+  def do_test(expr)
+    match = ::Calc.parse(expr)
+    assert(match)
+    assert_equal(expr, match)
+    assert_equal(expr.length, match.length)
+    assert_equal(eval(expr), match.value)
+  end
+
+  def test_int
+    do_test('3')
+  end
 
-# A grammar for mathematical formulas that apply basic mathematical operations
-# to all numbers, respecting operator precedence and grouping of expressions
-# while ignoring whitespace.
-#
-# An identical grammar that is written using Citrus' own grammar syntax can be
-# found in calc.citrus.
-grammar :Calc do
+  def test_float
+    do_test('1.5')
+  end
 
-  ## Hierarchical syntax
+  def test_addition
+    do_test('1+2')
+  end
 
-  rule :term do
-    any(:additive, :factor)
+  def test_addition_multi
+    do_test('1+2+3')
   end
 
-  rule :additive do
-    all(:factor, :additive_operator, :term) {
-      additive_operator.value(factor.value, term.value)
-    }
+  def test_addition_float
+    do_test('1.5+3')
   end
 
-  rule :factor do
-    any(:multiplicative, :prefix)
+  def test_subtraction
+    do_test('3-2')
   end
 
-  rule :multiplicative do
-    all(:prefix, :multiplicative_operator, :factor) {
-      multiplicative_operator.value(prefix.value, factor.value)
-    }
+  def test_subtraction_float
+    do_test('4.5-3')
   end
 
-  rule :prefix do
-    any(:prefixed, :exponent)
+  def test_multiplication
+    do_test('2*5')
   end
 
-  rule :prefixed do
-    all(:unary_operator, :prefix) {
-      unary_operator.value(prefix.value)
-    }
+  def test_multiplication_float
+    do_test('1.5*3')
   end
 
-  rule :exponent do
-    any(:exponential, :primary)
+  def test_division
+    do_test('20/5')
   end
 
-  rule :exponential do
-    all(:primary, :exponential_operator, :prefix) {
-      exponential_operator.value(primary.value, prefix.value)
-    }
+  def test_division_float
+    do_test('4.5/3')
   end
 
-  rule :primary do
-    any(:group, :number)
+  def test_complex
+    do_test('7*4+3.5*(4.5/3)')
   end
 
-  rule :group do
-    all(:lparen, :term, :rparen) {
-      term.value
-    }
+  def test_complex_spaced
+    do_test('7 * 4 + 3.5 * (4.5 / 3)')
   end
 
-  ## Lexical syntax
+  def test_complex_with_underscores
+    do_test('(12_000 / 3) * 2.5')
+  end
 
-  rule :number do
-    any(:float, :integer)
+  def test_modulo
+    do_test('3 % 2 + 4')
   end
 
-  rule :float do
-    all(:digits, '.', :digits, zero_or_more(:space)) {
-      strip.to_f
-    }
+  def test_exponent
+    do_test('2**9')
   end
 
-  rule :integer do
-    all(:digits, zero_or_more(:space)) {
-      strip.to_i
-    }
+  def test_exponent_float
+    do_test('2**2.2')
   end
 
-  rule :digits do
-    # Numbers may contain underscores in Ruby.
-    /[0-9]+(?:_[0-9]+)*/
+  def test_negative_exponent
+    do_test('2**-3')
   end
 
-  rule :additive_operator do
-    all(any('+', '-'), zero_or_more(:space)) { |a, b|
-      a.send(strip, b)
-    }
+  def test_exponent_exponent
+    do_test('2**2**2')
   end
 
-  rule :multiplicative_operator do
-    all(any('*', '/', '%'), zero_or_more(:space)) { |a, b|
-      a.send(strip, b)
-    }
+  def test_exponent_group
+    do_test('2**(3+1)')
   end
 
-  rule :exponential_operator do
-    all('**', zero_or_more(:space)) { |a, b|
-      a ** b
-    }
+  def test_negative
+    do_test('-5')
   end
 
-  rule :unary_operator do
-    all(any('~', '+', '-'), zero_or_more(:space)) { |n|
-      # Unary + and - require an @.
-      n.send(strip == '~' ? strip : '%s@' % strip)
-    }
+  def test_double_negative
+    do_test('--5')
   end
 
-  rule :lparen, ['(', zero_or_more(:space)]
-  rule :rparen, [')', zero_or_more(:space)]
-  rule :space,  /[ \t\n\r]/
+  def test_complement
+    do_test('~4')
+  end
+
+  def test_double_complement
+    do_test('~~4')
+  end
+
+  def test_mixed_unary
+    do_test('~-4')
+  end
+
+  def test_complex_with_negatives
+    do_test('4 * -7 / (8.0 + 1_2)**2')
+  end
 end

data/examples/ipaddress.citrus

@@ -0,0 +1,16 @@
+# The grammars in this file conform to the ABNF given in Appendix A of RFC 3986
+# Uniform Resource Identifier (URI): Generic Syntax.
+#
+# See http://tools.ietf.org/html/rfc3986#appendix-A for more information.
+
+require 'ipv4address'
+require 'ipv6address'
+
+grammar IPAddress
+  include IPv4Address
+  include IPv6Address
+
+  rule IPaddress
+    IPv4address | IPv6address
+  end
+end

data/examples/ipaddress.rb

@@ -0,0 +1,23 @@
+examples = File.expand_path('..', __FILE__)
+$LOAD_PATH.unshift(examples) unless $LOAD_PATH.include?(examples)
+
+# This file contains a suite of tests for the IPAddress grammar found in
+# ipaddress.citrus.
+
+require 'citrus'
+Citrus.require 'ipaddress'
+require 'test/unit'
+
+class IPAddressTest < Test::Unit::TestCase
+  def test_v4
+    match = IPAddress.parse('1.2.3.4')
+    assert(match)
+    assert_equal(4, match.version)
+  end
+
+  def test_v6
+    match = IPAddress.parse('1:2:3:4::')
+    assert(match)
+    assert_equal(6, match.version)
+  end
+end

data/examples/ipv4address.citrus

@@ -0,0 +1,26 @@
+grammar IPv4Address
+  # A host identified by an IPv4 literal address is represented in
+  # dotted-decimal notation (a sequence of four decimal numbers in the
+  # range 0 to 255, separated by "."), as described in [RFC1123] by
+  # reference to [RFC0952].  Note that other forms of dotted notation may
+  # be interpreted on some platforms, as described in Section 7.4, but
+  # only the dotted-decimal form of four octets is allowed by this
+  # grammar.
+  rule IPv4address
+    (dec-octet '.' dec-octet '.' dec-octet '.' dec-octet) {
+      def version; 4 end
+    }
+  end
+
+  rule dec-octet
+      '25' [0-5]        # 250-255
+    | '2' [0-4] DIGIT   # 200-249
+    | '1' DIGIT DIGIT   # 100-199
+    | [1-9] DIGIT       # 10-99
+    | DIGIT             # 0-9
+  end
+
+  rule DIGIT
+    [0-9]
+  end
+end

data/examples/ipv4address.rb

@@ -0,0 +1,49 @@
+examples = File.expand_path('..', __FILE__)
+$LOAD_PATH.unshift(examples) unless $LOAD_PATH.include?(examples)
+
+# This file contains a suite of tests for the IPv4Address grammar found in
+# ipv4address.citrus.
+
+require 'citrus'
+Citrus.require 'ipv4address'
+require 'test/unit'
+
+class IPv4AddressTest < Test::Unit::TestCase
+  def test_dec_octet
+    match = IPv4Address.parse('0', :root => :'dec-octet')
+    assert(match)
+
+    match = IPv4Address.parse('255', :root => :'dec-octet')
+    assert(match)
+  end
+
+  def test_1
+    match = IPv4Address.parse('0.0.0.0')
+    assert(match)
+    assert_equal(4, match.version)
+  end
+
+  def test_2
+    match = IPv4Address.parse('255.255.255.255')
+    assert(match)
+    assert_equal(4, match.version)
+  end
+
+  def test_invalid
+    assert_raise Citrus::ParseError do
+      IPv4Address.parse('255.255.255.256')
+    end
+  end
+
+  def test_invalid_short
+    assert_raise Citrus::ParseError do
+      IPv4Address.parse('255.255.255')
+    end
+  end
+
+  def test_invalid_long
+    assert_raise Citrus::ParseError do
+      IPv4Address.parse('255.255.255.255.255')
+    end
+  end
+end

data/examples/{ip.citrus → ipv6address.citrus}

@@ -1,34 +1,4 @@
-# The grammars in this file conform to the ABNF given in Appendix A of RFC 3986
-# Uniform Resource Identifier (URI): Generic Syntax.
-#
-# See http://tools.ietf.org/html/rfc3986#appendix-A for more information.
-
-grammar IPv4Address
-  # A host identified by an IPv4 literal address is represented in
-  # dotted-decimal notation (a sequence of four decimal numbers in the
-  # range 0 to 255, separated by "."), as described in [RFC1123] by
-  # reference to [RFC0952].  Note that other forms of dotted notation may
-  # be interpreted on some platforms, as described in Section 7.4, but
-  # only the dotted-decimal form of four octets is allowed by this
-  # grammar.
-  rule IPv4address
-    (dec-octet '.' dec-octet '.' dec-octet '.' dec-octet) {
-      def version; 4 end
-    }
-  end
-
-  rule dec-octet
-      '25' [0-5]        # 250-255
-    | '2' [0-4] DIGIT   # 200-249
-    | '1' DIGIT DIGIT   # 100-199
-    | [1-9] DIGIT       # 10-99
-    | DIGIT             # 0-9
-  end
-
-  rule DIGIT
-    [0-9]
-  end
-end
+require 'ipv4address'
 
 grammar IPv6Address
   include IPv4Address
@@ -71,12 +41,3 @@ grammar IPv6Address
     DIGIT | [a-fA-F] # Hexadecimal should be case-insensitive.
   end
 end
-
-grammar IPAddress
-  include IPv4Address
-  include IPv6Address
-
-  rule IPaddress
-    IPv4address | IPv6address
-  end
-end