citrus 1.6.0 → 1.7.0

data/README

@@ -10,7 +10,7 @@ elegance and expressiveness of the language with the simplicity and power of
 parsing expressions.
 
 
-  ** Installation **
+= Installation
 
 
 Via RubyGems:
@@ -24,7 +24,7 @@ From a local copy:
   $ rake package && sudo rake install
 
 
-  ** Background **
+= Background
 
 
 In order to be able to use Citrus effectively, you must first understand the
@@ -99,7 +99,7 @@ available to them including the text of the match, its position in the input,
 and any submatches.
 
 
-  ** Syntax **
+= Syntax
 
 
 The most straightforward way to compose a Citrus grammar is to use Citrus' own
@@ -168,7 +168,7 @@ Note that any operator binds more tightly than the bar.
 == Super
 
 When including a grammar inside another, all rules in the child that have the
-same name as a rule in the parent also have access to the super keyword to
+same name as a rule in the parent also have access to the "super" keyword to
 invoke the parent rule.
 
 == Labels
@@ -181,8 +181,31 @@ immediately preceding any expression.
                   # expression may be referred to as "chars"
                   # in a block method
 
+== Precedence
 
-  ** Example **
+The following table contains a list of all operators and their precedence. A
+higher level of precedence indicates tighter binding.
+
+Operator    | Level of Precedence   | Name
+----------------------------------------------------------------
+''          | 6                     | Literal string
+""          | 6                     | Literal string
+[]          | 6                     | Character class
+.           | 6                     | Any character (dot)
+//          | 6                     | Regular expression
+()          | 6                     | Grouping
+*           | 5                     | Repetition (arbitrary)
++           | 5                     | Repetition (one or more)
+?           | 5                     | Repetition (zero or one)
+&           | 4                     | And predicate
+!           | 4                     | Not predicate
+:           | 4                     | Label
+<>, {}      | 3                     | Extension
+e1 e2       | 2                     | Sequence
+e1 | e2     | 1                     | Ordered choice
+
+
+= Example
 
 
 Below is an example of a simple grammar that is able to parse strings of
@@ -300,7 +323,7 @@ Take a look at examples/calc.citrus for an example of a calculator that is able
 to parse and evaluate more complex mathematical expressions.
 
 
-  ** Links **
+= Links
 
 
 http://mjijackson.com/citrus
@@ -309,7 +332,7 @@ http://en.wikipedia.org/wiki/Parsing_expression_grammar
 http://treetop.rubyforge.org/index.html
 
 
-  ** License **
+= License
 
 
 Copyright 2010 Michael Jackson

data/examples/calc.citrus

@@ -1,6 +1,8 @@
 # A grammar for mathematical formulas that apply the basic four operations to
 # non-negative numbers (integers and floats), respecting operator precedence and
 # ignoring whitespace.
+#
+# An identical grammar that is written using pure Ruby can be found in calc.rb.
 grammar Calc
   rule term
     additive | factor

data/examples/calc.rb

@@ -3,6 +3,9 @@ require 'citrus'
 # A grammar for mathematical formulas that apply the basic four operations to
 # non-negative numbers (integers and floats), respecting operator precedence and
 # ignoring whitespace.
+#
+# An identical grammar that is written using Citrus' own grammar syntax can be
+# found in calc.citrus.
 grammar :Calc do
   rule :term do
     any(:additive, :factor)

data/examples/ip.citrus

@@ -0,0 +1,82 @@
+# 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
+
+grammar IPv6Address
+  include IPv4Address
+
+  # A 128-bit IPv6 address is divided into eight 16-bit pieces. Each
+  # piece is represented numerically in case-insensitive hexadecimal,
+  # using one to four hexadecimal digits (leading zeroes are permitted).
+  # The eight encoded pieces are given most-significant first, separated
+  # by colon characters. Optionally, the least-significant two pieces
+  # may instead be represented in IPv4 address textual format. A
+  # sequence of one or more consecutive zero-valued 16-bit pieces within
+  # the address may be elided, omitting all their digits and leaving
+  # exactly two consecutive colons in their place to mark the elision.
+  rule IPv6address
+    (                         (h16 ":")6*6 ls32
+    |                    "::" (h16 ":")5*5 ls32
+    |  h16             ? "::" (h16 ":")4*4 ls32
+    | (h16 (":" h16)*1)? "::" (h16 ":")3*3 ls32
+    | (h16 (":" h16)*2)? "::" (h16 ":")2*2 ls32
+    | (h16 (":" h16)*3)? "::"  h16 ":"     ls32
+    | (h16 (":" h16)*4)? "::"              ls32
+    | (h16 (":" h16)*5)? "::"              h16
+    | (h16 (":" h16)*6)? "::"
+    ) {
+      def version; 6 end
+    }
+  end
+
+  # 16-bit address represented in hexadecimal.
+  rule h16
+    HEXDIG 1*4
+  end
+
+  # Least-significant 32 bits of address.
+  rule ls32
+    (h16 ":" h16) | IPv4address
+  end
+
+  rule HEXDIG
+    DIGIT | [a-fA-F] # Hexadecimal should be case-insensitive.
+  end
+end
+
+grammar IPAddress
+  include IPv4Address
+  include IPv6Address
+
+  rule IPaddress
+    IPv4address | IPv6address
+  end
+end

data/examples/ip.rb

@@ -0,0 +1,75 @@
+require 'citrus'
+
+# This file contains a small suite of tests for the grammars found in ip.citrus.
+# If this file is run directly (i.e. using `ruby ip.rb') the tests will run.
+# Otherwise, this file may be required by another that needs access to the IP
+# address grammars just as any other file would be.
+
+# Load and evaluate the grammars contained in ip.citrus into the global
+# namespace.
+Citrus.load(File.expand_path('../ip.citrus', __FILE__))
+
+if $0 == __FILE__
+  require 'test/unit'
+
+  class IPAddressTest < 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_hexdig
+      match = IPv6Address.parse('0', :root => :HEXDIG)
+      assert(match)
+
+      match = IPv6Address.parse('A', :root => :HEXDIG)
+      assert(match)
+    end
+
+    def test_v4
+      match = IPv4Address.parse('0.0.0.0')
+      assert(match)
+
+      match = IPv4Address.parse('255.255.255.255')
+      assert(match)
+
+      assert_raise Citrus::ParseError do
+        IPv4Address.parse('255.255.255')
+      end
+    end
+
+    def test_v6
+      match = IPv6Address.parse('1:2:3:4:5:6:7:8')
+      assert(match)
+
+      match = IPv6Address.parse('12AD:34FC:A453:1922::')
+      assert(match)
+
+      match = IPv6Address.parse('12AD::34FC')
+      assert(match)
+
+      match = IPv6Address.parse('12AD::')
+      assert(match)
+
+      match = IPv6Address.parse('::')
+      assert(match)
+
+      assert_raise Citrus::ParseError do
+        IPv6Address.parse('1:2')
+      end
+    end
+
+    def test_all
+      match = IPAddress.parse('1.2.3.4')
+      assert(match)
+      assert_equal(4, match.version)
+
+      match = IPAddress.parse('1:2:3:4::')
+      assert(match)
+      assert_equal(6, match.version)
+    end
+  end
+end

data/extras/citrus.vim

@@ -16,7 +16,7 @@ syn case match
 syn match ctDoubleColon "::" contained
 syn match ctConstant "\u\w*" contained
 syn match ctModule "\(\(::\)\?\u\w*\)\+" contains=ctDoubleColon,ctConstant contained
-syn match ctVariable "[a-zA-Z_-]\+" contained
+syn match ctVariable "\a[a-zA-Z0-9_-]*" contained
 
 " Comments
 syn match ctComment "#.*" contains=@Spell

data/lib/citrus.rb

@@ -4,7 +4,7 @@
 #
 # http://mjijackson.com/citrus
 module Citrus
-  VERSION = [1, 6, 0]
+  VERSION = [1, 7, 0]
 
   Infinity = 1.0 / 0
 
@@ -68,7 +68,7 @@ module Citrus
     # created with this method may be assigned a name by being assigned to some
     # constant, e.g.:
     #
-    #     Calc = Grammar.new {}
+    #     Calc = Citrus::Grammar.new {}
     #
     def self.new(&block)
       mod = Module.new { include Grammar }
@@ -143,8 +143,8 @@ module Citrus
     end
 
     # Gets/sets the rule with the given +name+. If +obj+ is given the rule
-    # will be set to the value of +obj+ passed through Rule#create. If a block
-    # is given, its return value will be used for the value of +obj+.
+    # will be set to the value of +obj+ passed through Rule#new. If a block is
+    # given, its return value will be used for the value of +obj+.
     #
     # It is important to note that this method will also check any included
     # grammars for a rule with the given +name+ if one cannot be found in this
@@ -156,7 +156,7 @@ module Citrus
       if obj
         rule_names << sym unless has_rule?(sym)
 
-        rule = Rule.create(obj)
+        rule = Rule.new(obj)
         rule.name = name
         setup_super(rule, name)
         rule.grammar = self
@@ -239,7 +239,7 @@ module Citrus
     # the given +rule+. A block may also be given that will be used to create
     # an anonymous module. See Rule#ext=.
     def ext(rule, mod=nil)
-      rule = Rule.create(rule)
+      rule = Rule.new(rule)
       mod = Proc.new if block_given?
       rule.extension = mod if mod
       rule
@@ -342,7 +342,7 @@ module Citrus
   # Input during parsing.
   module Rule
     # Returns a new Rule object depending on the type of object given.
-    def self.create(obj)
+    def self.new(obj)
       case obj
       when Rule     then obj
       when Symbol   then Alias.new(obj)
@@ -356,6 +356,14 @@ module Citrus
       end
     end
 
+    # Creates a new rule object from the given expression.
+    #
+    #     Citrus::Rule.create('"a" | "b"')
+    #
+    def self.create(expr)
+      File.parse(expr, :root => :rule_body).value
+    end
+
     @unique_id = 0
 
     # Generates a new rule id.
@@ -587,7 +595,7 @@ module Citrus
     include Rule
 
     def initialize(rules=[])
-      @rules = rules.map {|r| Rule.create(r) }
+      @rules = rules.map {|r| Rule.new(r) }
     end
 
     # An array of the actual Rule objects this rule uses to match.

data/lib/citrus/file.rb

@@ -75,7 +75,7 @@ module Citrus
     end
 
     rule :sequence do
-      zero_or_more(:prefix) {
+      zero_or_more(:appendix) {
         def values
           matches.map {|m| m.value }
         end
@@ -86,44 +86,44 @@ module Citrus
       }
     end
 
-    rule :prefix do
-      all(zero_or_one(:qualifier), :appendix) {
+    rule :appendix do
+      all(:prefix, zero_or_one(:extension)) {
         def value
-          rule = appendix.value
-          qualifier = matches[0].first
-          rule = qualifier.wrap(rule) if qualifier
+          rule = prefix.value
+          extension = matches[1].first
+          rule.extension = extension.value if extension
           rule
         end
       }
     end
 
-    rule :appendix do
-      all(:suffix, zero_or_one(:extension)) {
+    rule :prefix do
+      all(zero_or_one(:predicate), :suffix) {
         def value
           rule = suffix.value
-          extension = matches[1].first
-          extension.apply(rule) if extension
+          predicate = matches[0].first
+          rule = predicate.wrap(rule) if predicate
           rule
         end
       }
     end
 
     rule :suffix do
-      all(:primary, zero_or_one(:quantifier)) {
+      all(:primary, zero_or_one(:repeat)) {
         def value
           rule = primary.value
-          quantifier = matches[1].first
-          rule = quantifier.wrap(rule) if quantifier
+          repeat = matches[1].first
+          rule = repeat.wrap(rule) if repeat
           rule
         end
       }
     end
 
     rule :primary do
-      any(:super, :alias, :rule_body_paren, :terminal)
+      any(:super, :alias, :grouping, :terminal)
     end
 
-    rule :rule_body_paren do
+    rule :grouping do
       all(:lparen, :rule_body, :rparen) {
         def value
           rule_body.value
@@ -157,8 +157,10 @@ module Citrus
       }
     end
 
+    # Rule names may contain letters, numbers, underscores, and dashes. They
+    # MUST start with a letter.
     rule :rule_name do
-      all(/[a-zA-Z_-]+/, :space) {
+      all(/[a-zA-Z][a-zA-Z0-9_-]*/, :space) {
         def value
           first.text
         end
@@ -184,7 +186,7 @@ module Citrus
     rule :terminal do
       any(:quoted_string, :character_class, :anything_symbol, :regular_expression) {
         def value
-          Rule.create(super)
+          Rule.new(super)
         end
       }
     end
@@ -221,7 +223,7 @@ module Citrus
       }
     end
 
-    rule :qualifier do
+    rule :predicate do
       any(:and, :not, :label)
     end
 
@@ -254,11 +256,7 @@ module Citrus
     end
 
     rule :extension do
-      any(:tag, :block) {
-        def apply(rule)
-          rule.extension = value
-        end
-      }
+      any(:tag, :block)
     end
 
     rule :tag do
@@ -277,8 +275,8 @@ module Citrus
       }
     end
 
-    rule :quantifier do
-      any(:question, :plus, :repeat) {
+    rule :repeat do
+      any(:question, :plus, :star_quantity) {
         def wrap(rule)
           Repeat.new(min, max, rule)
         end
@@ -299,7 +297,7 @@ module Citrus
       }
     end
 
-    rule :repeat do
+    rule :star_quantity do
       all(/[0-9]*/, '*', /[0-9]*/, :space) {
         def min
           matches[0] == '' ? 0 : matches[0].text.to_i

data/test/file_test.rb

@@ -105,6 +105,13 @@ class CitrusFileTest < Test::Unit::TestCase
     assert_kind_of(Rule, match.value)
     assert_instance_of(Repeat, match.value)
 
+    match = grammar.parse('"a"*')
+    assert(match)
+    assert_kind_of(Rule, match.value)
+    assert_instance_of(Repeat, match.value)
+    assert_equal(0, match.value.min)
+    assert_equal(Infinity, match.value.max)
+
     match = grammar.parse('("a" "b")*')
     assert(match)
     assert_kind_of(Rule, match.value)
@@ -469,8 +476,8 @@ class CitrusFileTest < Test::Unit::TestCase
     assert_equal(/a/i, match.value)
   end
 
-  def test_qualifier
-    grammar = file(:qualifier)
+  def test_predicate
+    grammar = file(:predicate)
 
     match = grammar.parse('&')
     assert(match)
@@ -570,8 +577,8 @@ class CitrusFileTest < Test::Unit::TestCase
     assert(match.value)
   end
 
-  def test_quantifier
-    grammar = file(:quantifier)
+  def test_repeat
+    grammar = file(:repeat)
 
     match = grammar.parse('?')
     assert(match)

data/test/rule_test.rb

@@ -20,6 +20,13 @@ class RuleTest < Test::Unit::TestCase
 
   NumericModule = Module.new(&NumericProc)
 
+  def test_create
+    rule = Rule.create('"a"')
+    assert(rule)
+    match = rule.match(input('a'))
+    assert(match)
+  end
+
   def test_match_module
     rule = EqualRule.new('a')
     rule.extension = MatchModule

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 1
-  - 6
+  - 7
   - 0
-  version: 1.6.0
+  version: 1.7.0
 platform: ruby
 authors: 
 - Michael Jackson
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-17 00:00:00 -06:00
+date: 2010-08-17 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -63,6 +63,8 @@ files:
 - doc/syntax.rdoc
 - examples/calc.citrus
 - examples/calc.rb
+- examples/ip.citrus
+- examples/ip.rb
 - extras/citrus.vim
 - lib/citrus/debug.rb
 - lib/citrus/file.rb