citrus 1.7.0 → 1.8.0

data/examples/calc.rb

@@ -1,97 +1,103 @@
 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.
+# 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
+
+  ## Hierarchy
+
   rule :term do
     any(:additive, :factor)
   end
 
   rule :additive do
-    all(:factor, label(any(:plus, :minus), :operator), :term) {
-      def value
-        operator.apply(factor, term)
-      end
+    all(:factor, :additive_operator, :term) {
+      additive_operator.value(factor.value, term.value)
     }
   end
 
   rule :factor do
-    any(:multiplicative, :primary)
+    any(:multiplicative, :prefix)
   end
 
   rule :multiplicative do
-    all(:primary, label(any(:star, :slash), :operator), :factor) {
-      def value
-        operator.apply(primary, factor)
-      end
+    all(:prefix, :multiplicative_operator, :factor) {
+      multiplicative_operator.value(prefix.value, factor.value)
     }
   end
 
-  rule :primary do
-    any(:term_paren, :number)
+  rule :prefix do
+    any(:prefixed, :exponent)
   end
 
-  rule :term_paren do
-    all(:lparen, :term, :rparen) {
-      def value
-        term.value
-      end
+  rule :prefixed do
+    all(:unary_operator, :prefix) {
+      unary_operator.value(prefix.value)
     }
   end
 
+  rule :exponent do
+    any(:exponential, :primary)
+  end
+
+  rule :exponential do
+    all(:primary, :exponential_operator, :prefix) {
+      exponential_operator.value(primary.value, prefix.value)
+    }
+  end
+
+  rule :primary do
+    any(:group, :number)
+  end
+
+  rule :group do
+    all(:lparen, :term, :rparen) { term.value }
+  end
+
+  ## Syntax
+
   rule :number do
     any(:float, :integer)
   end
 
   rule :float do
-    all(/[0-9]+/, '.', /[0-9]+/, :space) {
-      def value
-        text.strip.to_f
-      end
-    }
+    all(:digits, '.', :digits, :space) { strip.to_f }
   end
 
   rule :integer do
-    all(/[0-9]+/, :space) {
-      def value
-        text.strip.to_i
-      end
-    }
+    all(:digits, :space) { strip.to_i }
+  end
+
+  rule :digits do
+    /[0-9]+(?:_[0-9]+)*/
   end
 
-  rule :plus do
-    all('+', :space) {
-      def apply(factor, term)
-        factor.value + term.value
-      end
+  rule :additive_operator do
+    all(any('+', '-'), :space) { |a, b|
+      a.send(strip, b)
     }
   end
 
-  rule :minus do
-    all('-', :space) {
-      def apply(factor, term)
-        factor.value - term.value
-      end
+  rule :multiplicative_operator do
+    all(any('*', '/', '%'), :space) { |a, b|
+      a.send(strip, b)
     }
   end
 
-  rule :star do
-    all('*', :space) {
-      def apply(primary, factor)
-        primary.value * factor.value
-      end
+  rule :exponential_operator do
+    all('**', :space) { |a, b|
+      a ** b
     }
   end
 
-  rule :slash do
-    all('/', :space) {
-      def apply(primary, factor)
-        primary.value / factor.value
-      end
+  rule :unary_operator do
+    all(any('~', '+', '-'), :space) { |n|
+      # Unary + and - require an @.
+      n.send(strip == '~' ? strip : '%s@' % strip)
     }
   end
 

data/examples/ip.rb

@@ -7,7 +7,7 @@ require 'citrus'
 
 # Load and evaluate the grammars contained in ip.citrus into the global
 # namespace.
-Citrus.load(File.expand_path('../ip.citrus', __FILE__))
+Citrus.load(File.expand_path('../ip', __FILE__))
 
 if $0 == __FILE__
   require 'test/unit'

data/lib/citrus.rb

@@ -4,17 +4,20 @@
 #
 # http://mjijackson.com/citrus
 module Citrus
-  VERSION = [1, 7, 0]
-
-  Infinity = 1.0 / 0
-
   autoload :File, 'citrus/file'
 
+  VERSION = [1, 8, 0]
+
   # Returns the current version of Citrus as a string.
   def self.version
     VERSION.join('.')
   end
 
+  # A pattern to match any character, including \n.
+  DOT = /./m
+
+  Infinity = 1.0 / 0
+
   F = ::File
 
   # Loads the grammar from the given +file+ into the global scope using #eval.
@@ -26,7 +29,8 @@ module Citrus
   end
 
   # Evaluates the given Citrus parsing expression grammar +code+ in the global
-  # scope. Returns an array of any grammar modules that were created.
+  # scope. The +code+ may contain the definition of any number of modules.
+  # Returns an array of any grammar modules that are created.
   def self.eval(code)
     File.parse(code).value
   end
@@ -177,6 +181,12 @@ module Citrus
       @root || rule_names.first
     end
 
+    # Creates a new rule that will match any single character. A block may be
+    # provided to specify semantic behavior (via #ext).
+    def dot(&block)
+      ext(Rule.new(DOT), block)
+    end
+
     # Creates a new Super for the rule currently being defined in the grammar. A
     # block may be provided to specify semantic behavior (via #ext).
     def sup(&block)
@@ -195,17 +205,25 @@ module Citrus
       ext(NotPredicate.new(rule), block)
     end
 
+    # Creates a new ButPredicate using the given +rule+. A block may be provided
+    # to specify semantic behavior (via #ext).
+    def but(rule, &block)
+      ext(ButPredicate.new(rule), block)
+    end
+
+    alias butp but # For consistency with #andp and #notp.
+
     # Creates a new Label using the given +rule+ and +label+. A block may be
     # provided to specify semantic behavior (via #ext).
     def label(rule, label, &block)
-      ext(Label.new(label, rule), block)
+      ext(Label.new(rule, label), block)
     end
 
     # Creates a new Repeat using the given +rule+. +min+ and +max+ specify the
     # minimum and maximum number of times the rule must match. A block may be
     # provided to specify semantic behavior (via #ext).
     def rep(rule, min=1, max=Infinity, &block)
-      ext(Repeat.new(min, max, rule), block)
+      ext(Repeat.new(rule, min, max), block)
     end
 
     # An alias for #rep.
@@ -256,7 +274,13 @@ module Citrus
       raise 'No rule named "%s"' % root unless root_rule
 
       input = Input.new(string, opts[:memoize])
-      input.match(root_rule, opts[:offset]) or raise ParseError.new(input)
+      match = input.match(root_rule, opts[:offset])
+
+      if match.nil? || (opts[:consume] && input.length != match.length)
+        raise ParseError.new(input)
+      end
+
+      match
     end
 
     # The default set of options that is used in #parse. The options hash may
@@ -270,10 +294,14 @@ module Citrus
     #             guarantees parsers will operate in linear time but costs
     #             significantly more in terms of time and memory required.
     #             Defaults to +false+.
+    # consume::   If this is +true+ a ParseError will be raised during a parse
+    #             unless the entire input string is consumed. Defaults to
+    #             +false+.
     def default_parse_options
       { :offset   => 0,
         :root     => root,
-        :memoize  => false
+        :memoize  => false,
+        :consume  => false
       }
     end
   end
@@ -341,6 +369,14 @@ module Citrus
   # A Rule is an object that is used by a grammar to create matches on the
   # Input during parsing.
   module Rule
+    # Evaluates the given expression and creates a new rule object from it.
+    #
+    #     Citrus::Rule.eval('"a" | "b"')
+    #
+    def self.eval(expr)
+      File.parse(expr, :root => :rule_body).value
+    end
+
     # Returns a new Rule object depending on the type of object given.
     def self.new(obj)
       case obj
@@ -356,14 +392,6 @@ 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.
@@ -391,7 +419,18 @@ module Citrus
     # result from this rule. If +mod+ is a Proc, it is used to create an
     # anonymous module.
     def extension=(mod)
-      mod = Module.new(&mod) if Proc === mod
+      if Proc === mod
+        begin
+          tmp = Module.new(&mod)
+          raise ArgumentError unless tmp.instance_methods.any?
+          mod = tmp
+        rescue ArgumentError, NameError, NoMethodError
+          mod = Module.new { define_method(:value, &mod) }
+        end
+      end
+
+      raise ArgumentError unless Module === mod
+
       @extension = mod
     end
 
@@ -422,7 +461,7 @@ module Citrus
   private
 
     def extend_match(match, name)
-      match.extensions << extension if extension
+      match.extend(extension) if extension
       match.names << name if name
       match
     end
@@ -554,7 +593,7 @@ module Citrus
     # Returns the Match for this rule on +input+ at the given +offset+, +nil+ if
     # no match can be made.
     def match(input, offset=0)
-      create_match(rule.dup, offset) if rule == input[offset, rule.length]
+      create_match(rule.dup, offset) if input[offset, rule.length] == rule
     end
   end
 
@@ -612,7 +651,7 @@ module Citrus
     include Nonterminal
 
     def initialize(rule='')
-      super([ rule ])
+      super([rule])
     end
 
     # Returns the Rule object this rule uses to match.
@@ -663,6 +702,38 @@ module Citrus
     end
   end
 
+  # A ButPredicate is a Predicate that consumes all characters until its rule
+  # matches. It must match at least one character in order to succeed. The
+  # Citrus notation is any expression preceded by a tilde, e.g.:
+  #
+  #     ~expr
+  #
+  class ButPredicate
+    include Predicate
+
+    DOT_RULE = Rule.new(DOT)
+
+    # Returns the Match for this rule on +input+ at the given +offset+, +nil+ if
+    # no match can be made.
+    def match(input, offset=0)
+      matches = []
+      os = offset
+      while input.match(rule, os).nil?
+        m = input.match(DOT_RULE, os)
+        break unless m
+        matches << m
+        os += m.length
+      end
+      # Create a single match from the aggregate text value of all submatches.
+      create_match(matches.join, offset) if matches.any?
+    end
+
+    # Returns the Citrus notation of this rule as a string.
+    def to_s
+      '~' + rule.embed
+    end
+  end
+
   # A Label is a Predicate that applies a new name to any matches made by its
   # rule. The Citrus notation is any sequence of word characters (i.e.
   # <tt>[a-zA-Z0-9_]</tt>) followed by a colon, followed by any other
@@ -673,30 +744,30 @@ module Citrus
   class Label
     include Predicate
 
-    def initialize(label_name='<label>', rule='')
+    def initialize(rule='', label='<label>')
       super(rule)
-      self.label_name = label_name
+      self.label = label
     end
 
     # Sets the name of this label.
-    def label_name=(label_name)
-      @label_name = label_name.to_sym
+    def label=(label)
+      @label = label.to_sym
     end
 
-    # The name this rule adds to all its matches.
-    attr_reader :label_name
+    # The label this rule adds to all its matches.
+    attr_reader :label
 
     # Returns the Match for this rule on +input+ at the given +offset+, +nil+ if
     # no match can be made. When a Label makes a match, it re-names the match to
     # the value of its label.
     def match(input, offset=0)
-      m = rule.match(input, offset)
-      extend_match(m, label_name) if m
+      m = input.match(rule, offset)
+      extend_match(m, label) if m
     end
 
     # Returns the Citrus notation of this rule as a string.
     def to_s
-      label_name.to_s + ':' + rule.embed
+      label.to_s + ':' + rule.embed
     end
   end
 
@@ -722,10 +793,10 @@ module Citrus
   class Repeat
     include Predicate
 
-    def initialize(min=1, max=Infinity, rule='')
+    def initialize(rule='', min=1, max=Infinity)
+      super(rule)
       raise ArgumentError, "Min cannot be greater than max" if min > max
       @range = Range.new(min, max)
-      super(rule)
     end
 
     # Returns the Match for this rule on +input+ at the given +offset+, +nil+ if
@@ -835,15 +906,16 @@ module Citrus
   # The base class for all matches. Matches are organized into a tree where any
   # match may contain any number of other matches. This class provides several
   # convenient tree traversal methods that help when examining parse results.
-  class Match
+  class Match < String
     def initialize(data, offset=0)
       case data
       when String
-        @text = data
+        super(data)
       when MatchData
-        @text = data[0]
+        super(data[0])
         @captures = data.captures
       when Array
+        super(data.join)
         @matches = data
       end
 
@@ -870,11 +942,6 @@ module Citrus
       names.include?(name)
     end
 
-    # An array of all extension modules of this match.
-    def extensions
-      @extensions ||= []
-    end
-
     # An array of all sub-matches of this match.
     def matches
       @matches ||= []
@@ -886,31 +953,13 @@ module Citrus
       @captures ||= []
     end
 
-    # Returns the raw text value of this match, which may simply be an
-    # aggregate of the text of all sub-matches if this match is not #terminal?.
-    def text
-      @text ||= matches.inject('') {|s, m| s << m.text }
-    end
-
-    alias to_s text
-
-    # Returns the length of this match's #text value as an Integer.
-    def length
-      text.length
-    end
-
-    # Passes all arguments to the #text of this match.
-    def [](*args)
-      text.__send__(:[], *args)
-    end
-
     # Returns an array of all sub-matches with the given +name+. If +deep+ is
     # +false+, returns only sub-matches that are immediate descendants of this
     # match.
     def find(name, deep=true)
       sym = name.to_sym
       ms = matches.select {|m| m.has_name?(sym) }
-      ms.concat(matches.map {|m| m.find(name, deep) }.flatten) if deep
+      matches.each {|m| ms.concat(m.find(name, deep)) } if deep
       ms
     end
 
@@ -927,41 +976,21 @@ module Citrus
       matches.length == 0
     end
 
-    # Checks equality by comparing this match's #text value to +obj+.
-    def ==(obj)
-      obj == text
-    end
-
-    alias eql? ==
-
-  private
-
-    def redefine_method_missing! # :nodoc:
-      instance_eval(<<-RUBY, __FILE__, __LINE__ + 1)
-        def method_missing(sym, *args)
-          if sym == :to_ary
-            original_method_missing(sym, *args)
-          else
-            m = first(sym)
-            return m if m
-            raise 'No match named "%s" in %s (%s)' % [sym, self, name]
-          end
-        end
-      RUBY
+    # Creates a new String object from the contents of this match.
+    def to_s
+      String.new(self)
     end
 
-    alias original_method_missing method_missing
-
-  public
-
     # Allows sub-matches of this match to be retrieved by name as instance
     # methods.
     def method_missing(sym, *args)
-      # Extend this object only when needed and immediately redefine
-      # #method_missing so that the new version is used on all future calls.
-      extensions.each {|e| extend(e) } if @extensions
-      redefine_method_missing!
-      __send__(sym, *args)
+      m = first(sym)
+      return m if m
+      raise 'No match named "%s" in %s (%s)' % [sym, self, name]
+    end
+
+    def to_ary
+      # This method intentionally left blank to work around a bug in Ruby 1.9.
     end
   end
 end