citrus 2.3.2 → 2.3.3

data/examples/ipv6address.rb

@@ -0,0 +1,55 @@
+examples = File.expand_path('..', __FILE__)
+$LOAD_PATH.unshift(examples) unless $LOAD_PATH.include?(examples)
+
+# This file contains a suite of tests for the IPv6Address grammar found in
+# ipv6address.citrus.
+
+require 'citrus'
+Citrus.require 'ipv6address'
+require 'test/unit'
+
+class IPv6AddressTest < Test::Unit::TestCase
+  def test_hexdig
+    match = IPv6Address.parse('0', :root => :HEXDIG)
+    assert(match)
+
+    match = IPv6Address.parse('A', :root => :HEXDIG)
+    assert(match)
+  end
+
+  def test_1
+    match = IPv6Address.parse('1:2:3:4:5:6:7:8')
+    assert(match)
+    assert_equal(6, match.version)
+  end
+
+  def test_2
+    match = IPv6Address.parse('12AD:34FC:A453:1922::')
+    assert(match)
+    assert_equal(6, match.version)
+  end
+
+  def test_3
+    match = IPv6Address.parse('12AD::34FC')
+    assert(match)
+    assert_equal(6, match.version)
+  end
+
+  def test_4
+    match = IPv6Address.parse('12AD::')
+    assert(match)
+    assert_equal(6, match.version)
+  end
+
+  def test_5
+    match = IPv6Address.parse('::')
+    assert(match)
+    assert_equal(6, match.version)
+  end
+
+  def test_invalid
+    assert_raise Citrus::ParseError do
+      IPv6Address.parse('1:2')
+    end
+  end
+end

data/lib/citrus.rb

@@ -1,4 +1,8 @@
+# encoding: UTF-8
+
 require 'strscan'
+require 'pathname'
+require 'citrus/version'
 
 # Citrus is a compact and powerful parsing library for Ruby that combines the
 # elegance and expressiveness of the language with the simplicity and power of
@@ -8,23 +12,29 @@ require 'strscan'
 module Citrus
   autoload :File, 'citrus/file'
 
-  # The current version of Citrus as [major, minor, patch].
-  VERSION = [2, 3, 2]
-
   # A pattern to match any character, including newline.
-  DOT = /./m
+  DOT = /./mu
 
   Infinity = 1.0 / 0
 
   CLOSE = -1
 
-  # Returns the current version of Citrus as a string.
-  def self.version
-    VERSION.join('.')
+  @cache = {}
+
+  # Returns a map of paths of files that have been loaded via #load to the
+  # result of #eval on the code in that file.
+  #
+  # Note: These paths are not absolute unless you pass an absolute path to
+  # #load. That means that if you change the working directory and try to
+  # #require the same file with a different relative path, it will be loaded
+  # twice.
+  def self.cache
+    @cache
   end
 
-  # Evaluates the given Citrus parsing expression grammar +code+ in the global
-  # scope. Returns an array of any grammar modules that are created.
+  # Evaluates the given Citrus parsing expression grammar +code+ and returns an
+  # array of any grammar modules that are created. Accepts the same +options+ as
+  # GrammarMethods#parse.
   #
   #     Citrus.eval(<<CITRUS)
   #     grammar MyGrammar
@@ -40,27 +50,73 @@ module Citrus
   end
 
   # Evaluates the given expression and creates a new Rule object from it.
+  # Accepts the same +options+ as #eval.
   #
   #     Citrus.rule('"a" | "b"')
   #     # => #<Citrus::Rule: ... >
   #
   def self.rule(expr, options={})
-    File.parse(expr, options.merge(:root => :rule_body)).value
+    eval(expr, options.merge(:root => :expression))
   end
 
-  # Loads the grammar from the given +file+ into the global scope using #eval.
+  # Loads the grammar(s) from the given +file+. Accepts the same +options+ as
+  # #eval, plus the following:
+  #
+  # force::   Normally this method will not reload a file that is already in
+  #           the #cache. However, if this option is +true+ the file will be
+  #           loaded, regardless of whether or not it is in the cache. Defaults
+  #           to +false+.
   #
   #     Citrus.load('mygrammar')
   #     # => [MyGrammar]
   #
   def self.load(file, options={})
-    file << '.citrus' unless ::File.file?(file)
-    raise ArgumentError, "Cannot find file #{file}" unless ::File.file?(file)
-    raise ArgumentError, "Cannot read file #{file}" unless ::File.readable?(file)
-    eval(::File.read(file), options)
+    file += '.citrus' unless file =~ /\.citrus$/
+    force = options.delete(:force)
+
+    if force || !@cache[file]
+      raise LoadError, "Cannot find file #{file}" unless ::File.file?(file)
+      raise LoadError, "Cannot read file #{file}" unless ::File.readable?(file)
+
+      begin
+        @cache[file] = eval(::File.read(file), options)
+      rescue SyntaxError => e
+        e.message.replace("#{::File.expand_path(file)}: #{e.message}")
+        raise e
+      end
+    end
+
+    @cache[file]
+  end
+
+  # Searches the <tt>$LOAD_PATH</tt> for a +file+ with the .citrus suffix and
+  # attempts to load it via #load. Returns the path to the file that was loaded
+  # on success, +nil+ on failure. Accepts the same +options+ as #load.
+  #
+  #     path = Citrus.require('mygrammar')
+  #     # => "/path/to/mygrammar.citrus"
+  #     Citrus.cache[path]
+  #     # => [MyGrammar]
+  #
+  def self.require(file, options={})
+    file += '.citrus' unless file =~ /\.citrus$/
+    found = nil
+
+    (Pathname.new(file).absolute? ? [''] : $LOAD_PATH).each do |dir|
+      found = Dir[::File.join(dir, file)].first
+      break if found
+    end
+
+    if found
+      Citrus.load(found, options)
+    else
+      raise LoadError, "Cannot find file #{file}"
+    end
+
+    found
   end
 
-  # A standard error class that all Citrus errors extend.
+  # A base class for all Citrus errors.
   class Error < RuntimeError; end
 
   # Raised when a parse fails.
@@ -71,7 +127,11 @@ module Citrus
       @line_offset = input.line_offset(offset)
       @line_number = input.line_number(offset)
       @line = input.line(offset)
-      super("Failed to parse input on line #{line_number} at offset #{line_offset}\n#{detail}")
+
+      message = "Failed to parse input on line #{line_number}"
+      message << " at offset #{line_offset}\n#{detail}"
+
+      super(message)
     end
 
     # The 0-based offset at which the error occurred in the input, i.e. the
@@ -96,6 +156,20 @@ module Citrus
     end
   end
 
+  # Raised when Citrus.load fails to load a file.
+  class LoadError < Error; end
+
+  # Raised when Citrus::File.parse fails.
+  class SyntaxError < Error
+    # The +error+ given here is an instance of Citrus::ParseError.
+    def initialize(error)
+      message = "Malformed Citrus syntax on line #{error.line_number}"
+      message << " at offset #{error.line_offset}\n#{error.detail}"
+
+      super(message)
+    end
+  end
+
   # An Input is a scanner that is responsible for executing rules at different
   # positions in the input string and persisting event streams.
   class Input < StringScanner
@@ -172,12 +246,11 @@ module Citrus
       index = events.size
 
       if apply_rule(rule, position, events).size > index
-        position += events[-1]
-        @max_offset = position if position > @max_offset
+        @max_offset = pos if pos > @max_offset
+      else
+        self.pos = position
       end
 
-      self.pos = position
-
       events
     end
 
@@ -260,7 +333,7 @@ module Citrus
     # created with this method may be assigned a name by being assigned to some
     # constant, e.g.:
     #
-    #     Calc = Citrus::Grammar.new {}
+    #     MyGrammar = Citrus::Grammar.new {}
     #
     def self.new(&block)
       mod = Module.new { include Grammar }
@@ -284,9 +357,11 @@ module Citrus
       super
     end
 
-    # Parses the given +string+ using this grammar's root rule. Optionally, the
-    # name of a different rule may be given here as the value of the +:root+
-    # option. Otherwise, all options are the same as in Rule#parse.
+    # Parses the given +string+ using this grammar's root rule. Accepts the same
+    # +options+ as Rule#parse, plus the following:
+    #
+    # root::    The name of the root rule to start parsing at. Defaults to this
+    #           grammar's #root.
     def parse(string, options={})
       rule_name = options.delete(:root) || root
       raise Error, "No root rule specified" unless rule_name
@@ -307,8 +382,7 @@ module Citrus
     end
 
     # Returns an array of all names of rules in this grammar as symbols ordered
-    # in the same way they were defined (i.e. rules that were defined later
-    # appear later in the array).
+    # in the same way they were declared.
     def rule_names
       @rule_names ||= []
     end
@@ -370,7 +444,6 @@ module Citrus
 
       rules[sym] || super_rule(sym)
     rescue => e
-      # This preserves the backtrace.
       e.message.replace("Cannot create rule \"#{name}\": #{e.message}")
       raise e
     end
@@ -447,7 +520,7 @@ module Citrus
       ext(Choice.new(args), block)
     end
 
-    # Adds +label+ to the given +rule+.A block may be provided to specify
+    # Adds +label+ to the given +rule+. A block may be provided to specify
     # semantic behavior (via #ext).
     def label(rule, label, &block)
       rule = ext(rule, block)
@@ -491,7 +564,7 @@ module Citrus
       end
     end
 
-    # The grammar this rule belongs to.
+    # The grammar this rule belongs to, if any.
     attr_accessor :grammar
 
     # Sets the name of this rule.
@@ -528,7 +601,7 @@ module Citrus
     # The module this rule uses to extend new matches.
     attr_reader :extension
 
-    # The default set of options to use when calling #parse or #test.
+    # The default set of options to use when calling #parse.
     def default_options # :nodoc:
       { :consume  => true,
         :memoize  => false,
@@ -549,19 +622,14 @@ module Citrus
     def parse(string, options={})
       opts = default_options.merge(options)
 
-      input = if opts[:memoize]
-        MemoizedInput.new(string)
-      else
-        Input.new(string)
-      end
-
+      input = (opts[:memoize] ? MemoizedInput : Input).new(string)
       input.pos = opts[:offset] if opts[:offset] > 0
 
       events = input.exec(self)
       length = events[-1]
 
       if !length || (opts[:consume] && length < (string.length - opts[:offset]))
-        raise ParseError.new(input)
+        raise ParseError, input
       end
 
       Match.new(string.slice(opts[:offset], length), events)
@@ -623,8 +691,6 @@ module Citrus
       end
     end
 
-    alias_method :eql?, :==
-
     def inspect # :nodoc:
       to_s
     end
@@ -636,8 +702,8 @@ module Citrus
 
   # A Proxy is a Rule that is a placeholder for another rule. It stores the
   # name of some other rule in the grammar internally and resolves it to the
-  # actual Rule object at runtime. This lazy evaluation permits us to create
-  # Proxy objects for rules that we may not know the definition of yet.
+  # actual Rule object at runtime. This lazy evaluation permits creation of
+  # Proxy objects for rules that may not yet be defined.
   module Proxy
     include Rule
 
@@ -707,8 +773,7 @@ module Citrus
       rule = grammar.rule(rule_name)
 
       unless rule
-        raise RuntimeError,
-          "No rule named \"#{rule_name}\" in grammar #{grammar.name}"
+        raise Error, "No rule named \"#{rule_name}\" in grammar #{grammar}"
       end
 
       rule
@@ -738,8 +803,8 @@ module Citrus
       rule = grammar.super_rule(rule_name)
 
       unless rule
-        raise RuntimeError,
-          "No rule named \"#{rule_name}\" in hierarchy of grammar #{grammar.name}"
+        raise Error,
+          "No rule named \"#{rule_name}\" in hierarchy of grammar #{grammar}"
       end
 
       rule
@@ -773,12 +838,12 @@ module Citrus
 
     # Returns an array of events for this rule on the given +input+.
     def exec(input, events=[])
-      length = input.scan_full(@regexp, false, false)
+      match = input.scan(@regexp)
 
-      if length
+      if match
         events << self
         events << CLOSE
-        events << length
+        events << match.length
       end
 
       events
@@ -1011,7 +1076,8 @@ module Citrus
     def initialize(rule='', min=1, max=Infinity)
       raise ArgumentError, "Min cannot be greater than max" if min > max
       super([rule])
-      @range = Range.new(min, max)
+      @min = min
+      @max = max
     end
 
     # Returns the Rule object this rule uses to match.
@@ -1026,9 +1092,8 @@ module Citrus
       index = events.size
       start = index - 1
       length = n = 0
-      m = max
 
-      while n < m && input.exec(rule, events).size > index
+      while n < max && input.exec(rule, events).size > index
         length += events[-1]
         index = events.size
         n += 1
@@ -1045,14 +1110,10 @@ module Citrus
     end
 
     # The minimum number of times this rule must match.
-    def min
-      @range.begin
-    end
+    attr_reader :min
 
     # The maximum number of times this rule may match.
-    def max
-      @range.end
-    end
+    attr_reader :max
 
     # Returns the operator this rule uses as a string. Will be one of
     # <tt>+</tt>, <tt>?</tt>, or <tt>N*M</tt>.
@@ -1170,7 +1231,7 @@ module Citrus
 
         while events[0].elide?
           elisions.unshift(events.shift)
-          events = events.slice(0, events.length - 2)
+          events.slice!(-2, events.length)
         end
 
         events[0].extend_match(self)
@@ -1178,6 +1239,9 @@ module Citrus
         elisions.each do |rule|
           rule.extend_match(self)
         end
+      else
+        # Create a default stream of events for the given string.
+        events = [Rule.for(string), CLOSE, string.length]
       end
 
       @events = events
@@ -1194,114 +1258,28 @@ module Citrus
     # Returns a hash of capture names to arrays of matches with that name,
     # in the order they appeared in the input.
     def captures
-      @captures ||= begin
-        captures = {}
-        stack = []
-        offset = 0
-        close = false
-        index = 0
-        last_length = nil
-        in_proxy = false
-        count = 0
-
-        while index < @events.size
-          event = @events[index]
-
-          if close
-            start = stack.pop
-
-            if Rule === start
-              rule = start
-              os = stack.pop
-              start = stack.pop
-
-              match = Match.new(@string.slice(os, event), @events[start..index])
-
-              # We can lookup immediate submatches by their index.
-              if stack.size == 1
-                captures[count] = match
-                count += 1
-              end
-
-              # We can lookup matches that were created by proxy by the name of
-              # the rule they are proxy for.
-              if Proxy === rule
-                if captures[rule.rule_name]
-                  captures[rule.rule_name] << match
-                else
-                  captures[rule.rule_name] = [match]
-                end
-              end
-
-              # We can lookup matches that were created by rules with labels by
-              # that label.
-              if rule.label
-                if captures[rule.label]
-                  captures[rule.label] << match
-                else
-                  captures[rule.label] = [match]
-                end
-              end
-
-              in_proxy = false
-            end
-
-            unless last_length
-              last_length = event
-            end
-
-            close = false
-          elsif event == CLOSE
-            close = true
-          else
-            stack << index
-
-            # We can calculate the offset of this rule event by adding back the
-            # last match length.
-            if last_length
-              offset += last_length
-              last_length = nil
-            end
-
-            # We should not create captures when traversing the portion of the
-            # event stream that is masked by a proxy in the original rule
-            # definition.
-            unless in_proxy || stack.size == 1
-              stack << offset
-              stack << event
-              in_proxy = true if Proxy === event
-            end
-          end
-
-          index += 1
-        end
-
-        captures
-      end
+      process_events! unless @captures
+      @captures
     end
 
     # Returns an array of all immediate submatches of this match.
     def matches
-      @matches ||= (0...captures.size).map {|n| captures[n] }.compact
+      process_events! unless @matches
+      @matches
     end
 
     # A shortcut for retrieving the first immediate submatch of this match.
     def first
-      captures[0]
+      matches.first
     end
 
-    # The default value for a match is its string value. This method is
-    # overridden in most cases to be more meaningful according to the desired
-    # interpretation.
-    alias_method :value, :to_s
-
     # Allows methods of this match's string to be called directly and provides
     # a convenient interface for retrieving the first match with a given name.
     def method_missing(sym, *args, &block)
       if @string.respond_to?(sym)
         @string.__send__(sym, *args, &block)
       else
-        captures[sym].first if captures[sym]
+        captures[sym].first
       end
     end
 
@@ -1311,6 +1289,32 @@ module Citrus
 
     alias_method :to_str, :to_s
 
+    # The default value for a match is its string value. This method is
+    # overridden in most cases to be more meaningful according to the desired
+    # interpretation.
+    alias_method :value, :to_s
+
+    # Returns this match plus all sub #matches in an array.
+    def to_a
+      [captures[0]] + matches
+    end
+
+    alias_method :to_ary, :to_a
+
+    # Returns the capture at the given +key+. If it is an Integer (and an
+    # optional length) or a Range, the result of #to_a with the same arguments
+    # is returned. Otherwise, the value at +key+ in #captures is returned.
+    def [](key, *args)
+      case key
+      when Integer, Range
+        to_a[key, *args]
+      else
+        captures[key]
+      end
+    end
+
+    alias_method :fetch, :[]
+
     def ==(other)
       case other
       when String
@@ -1322,8 +1326,6 @@ module Citrus
       end
     end
 
-    alias_method :eql?, :==
-
     def inspect
       @string.inspect
     end
@@ -1350,9 +1352,7 @@ module Citrus
           string = @string.slice(os, event)
           lines[start] = "#{space}#{string.inspect} rule=#{rule}, offset=#{os}, length=#{event}"
 
-          unless last_length
-            last_length = event
-          end
+          last_length = event unless last_length
 
           close = false
         elsif event == CLOSE
@@ -1373,11 +1373,121 @@ module Citrus
 
       puts lines.compact.join("\n")
     end
+
+  private
+
+    # Initializes both the @captures and @matches instance variables.
+    def process_events!
+      @captures = captures_hash
+      @matches = []
+
+      capture!(@events[0], self)
+
+      stack = []
+      offset = 0
+      close = false
+      index = 0
+      last_length = nil
+      capture = true
+
+      while index < @events.size
+        event = @events[index]
+
+        if close
+          start = stack.pop
+
+          if Rule === start
+            rule = start
+            os = stack.pop
+            start = stack.pop
+
+            match = Match.new(@string.slice(os, event), @events[start..index])
+            capture!(rule, match)
+
+            @matches << match if stack.size == 1
+
+            capture = true
+          end
+
+          last_length = event unless last_length
+
+          close = false
+        elsif event == CLOSE
+          close = true
+        else
+          stack << index
+
+          # We can calculate the offset of this rule event by adding back the
+          # last match length.
+          if last_length
+            offset += last_length
+            last_length = nil
+          end
+
+          if capture && stack.size != 1
+            stack << offset
+            stack << event
+
+            # We should not create captures when traversing a portion of the
+            # event stream that is masked by a proxy in the original rule
+            # definition.
+            capture = false if Proxy === event
+          end
+        end
+
+        index += 1
+      end
+
+      # Add numeric indices to @captures.
+      @captures[0] = self
+
+      @matches.each_with_index do |match, index|
+        @captures[index + 1] = match
+      end
+    end
+
+    def capture!(rule, match)
+      # We can lookup matches that were created by proxy by the name of
+      # the rule they are proxy for.
+      if Proxy === rule
+        if @captures.key?(rule.rule_name)
+          @captures[rule.rule_name] << match
+        else
+          @captures[rule.rule_name] = [match]
+        end
+      end
+
+      # We can lookup matches that were created by rules with labels by
+      # that label.
+      if rule.label
+        if @captures.key?(rule.label)
+          @captures[rule.label] << match
+        else
+          @captures[rule.label] = [match]
+        end
+      end
+    end
+
+    # Returns a new Hash that is to be used for @captures. This hash normalizes
+    # String keys to Symbols, returns +nil+ for unknown Numeric keys, and an
+    # empty Array for all other unknown keys.
+    def captures_hash
+      Hash.new do |hash, key|
+        case key
+        when String
+          hash[key.to_sym]
+        when Numeric
+          nil
+        else
+          []
+        end
+      end
+    end
   end
 end
 
 class Object
-  # A sugar method for creating grammars.
+  # A sugar method for creating Citrus grammars from any namespace.
   #
   #     grammar :Calc do
   #     end