citrus 3.0.0 → 3.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2caf741a96f7499506f5bf450998aad817dbe9d4
+  data.tar.gz: 955838c4b13b2ae7c25be7b7d8e440a594105be8
+SHA512:
+  metadata.gz: 3b02bb8198f6190575e3e4960be9d81adcca08d638919e32a6b1b1dc164e953007ce60b6ed86e0988a51a3c81b2ad490f40863e9ed61f06a58e50193a055e03f
+  data.tar.gz: 3a5b292f74e1849e01ebe3349c402a4ad3d7f9c1f0a024b21f830c3f10700063f9551ebd601155070992f9d636cca4e6609dd00e4e72faa8400c098d622510ad

data/CHANGES

@@ -1,9 +1,54 @@
+= 3.0.1 / 2014-03-14
+
+  * Fixed bad 3.0.0 release.
+
 = 3.0.0 / 2014-03-14
 
   * Moved Object#grammar to citrus/core_ext.rb. Citrus no longer installs core
     extensions by default. Use "require 'citrus/core_ext.rb'" instead of
     "require 'citrus'" to keep the previous behavior.
 
+  * Removed Match#method_missing, added #capture(name) and #captures(name)
+
+    Match#method_missing is unsafe as illustrated in Github issue #41. In
+    particular, it makes composing a grammar with aribitrary gems unsafe (e.g.
+    when the latter make core extensions), leads to unexpected results with
+    labels match existing Kernel methods (e.g. `p`), and prevents Match from
+    getting new methods in a backward compatible way. This commit therefore
+    removes it.
+
+    In Citrus 2.x, method_missing allowed rule productions to denote captured
+    matches by label name:
+
+        rule pair
+          (foo ':' bar) {
+            [foo.value, bar.value]
+          }
+        end
+
+    Also, it allowed invoking String operators on the Match's text:
+
+        rule int
+          [0-9]+ { to_i }
+        end
+
+    Those two scenarios no longer work out of the box in Citrus 3.0. You must
+    use capture(label) for the former, and to_str for the latter:
+
+        rule pair
+          (foo ':' bar) {
+            [capture(:foo).value, capture(:bar).value]
+          }
+        end
+
+        rule int
+          [0-9]+ { to_str.to_i }
+        end
+
+    Match#captures now accepts an optional label name as first argument and
+    returns the corresponding array of matches for that label (useful in case
+    the label belongs to a repetition).
+
 = 2.5.0 / 2014-03-13
 
   * Inputs may be generated from many different sources, including Pathname and

data/README.md

@@ -232,8 +232,8 @@ Additionally, extensions may be specified inline using curly braces. When using
 this method, the code inside the curly braces may be invoked by calling the
 `value` method on the match object.
 
-    [0-9] { to_i }        # match any digit and return its integer value when
-                          # calling the #value method on the match object
+    [0-9] { to_str.to_i }     # match any digit and return its integer value when
+                              # calling the #value method on the match object
 
 Note that when using the inline block method you may also specify arguments in
 between vertical bars immediately following the opening curly brace, just like
@@ -358,13 +358,13 @@ blocks. Let's extend the `Addition` grammar using this technique.
     grammar Addition
       rule additive
         (number plus term:(additive | number)) {
-          number.value + term.value
+          capture(:number).value + capture(:term).value
         }
       end
 
       rule number
         ([0-9]+ space) {
-          to_i
+          to_str.to_i
         }
       end
 
@@ -383,17 +383,19 @@ execute by calling `value` on match objects that result from those rules. It's
 easiest to explain what is going on here by starting with the lowest level
 block, which is defined within `number`.
 
-Inside this block we see a call to another method, namely `to_i`. When called in
-the context of a match object, methods that are not defined may be called on a
-match's internal string object via `method_missing`. Thus, the call to `to_i`
-should return the integer value of the match.
+Inside this block we see a call to another method, namely `to_str`. When called
+in the context of a match object, this method returns the match's internal
+string object. Thus, the call to `to_str.to_i` should return the integer value
+of the match.
 
 Similarly, matches created by `additive` will also have a `value` method. Notice
 the use of the `term` label within the rule definition. This label allows the
 match that is created by the choice between `additive` and `number` to be
-retrieved using the `term` method. The value of an additive match is determined
+retrieved using `capture(:term)`. The value of an additive match is determined
 to be the values of its `number` and `term` matches added together using Ruby's
-addition operator.
+addition operator. Note that the plural form `captures(:term)` can be used to
+get an array of matches for a given label (e.g. when the label belongs to a
+repetition).
 
 Since `additive` is the first rule defined in the grammar, any match that
 results from parsing a string with this grammar will have a `value` method that
@@ -441,11 +443,11 @@ look like this:
     rule additive
       (number plus term:(additive | number)) {
         def lhs
-          number.value
+          capture(:number).value
         end
 
         def rhs
-          term.value
+          capture(:term).value
         end
 
         def value
@@ -475,11 +477,11 @@ define the following module.
 
     module Additive
       def lhs
-        number.value
+        capture(:number).value
       end
 
       def rhs
-        term.value
+        capture(:term).value
       end
 
       def value

data/lib/citrus.rb

@@ -1326,9 +1326,14 @@ 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
+    def captures(name = nil)
       process_events! unless @captures
-      @captures
+      name ? @captures[name] : @captures
+    end
+
+    # Convenient method for captures[name].first.
+    def capture(name)
+      captures[name].first
     end
 
     # Returns an array of all immediate submatches of this match.
@@ -1342,20 +1347,6 @@ module Citrus
       matches.first
     end
 
-    # 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)
-      unless defined?(Citrus::METHOD_MISSING_WARNED)
-        warn("[`#{sym}`] Citrus::Match#method_missing is unsafe and will be removed in 3.0. Use captures.")
-        Citrus.send(:const_set, :METHOD_MISSING_WARNED, true)
-      end
-      if string.respond_to?(sym)
-        string.__send__(sym, *args, &block)
-      else
-        captures[sym].first
-      end
-    end
-
     alias_method :to_s, :string
 
     # This alias allows strings to be compared to the string value of Match

data/lib/citrus/file.rb

@@ -6,6 +6,10 @@ module Citrus
   # Some helper methods for rules that alias +module_name+ and don't want to
   # use +Kernel#eval+ to retrieve Module objects.
   module ModuleNameHelpers #:nodoc:
+    def module_name
+      capture(:module_name)
+    end
+
     def module_segments
       @module_segments ||= module_name.value.split('::')
     end
@@ -58,6 +62,7 @@ module Citrus
           captures[:include].each {|inc| grammar.include(inc.value) }
           captures[:rule].each {|r| grammar.rule(r.rule_name.value, r.value) }
 
+          root = capture(:root)
           grammar.root(root.value) if root
 
           grammar
@@ -66,10 +71,17 @@ module Citrus
     end
 
     rule :rule do
-      all(:rule_keyword, :rule_name, zero_or_one(:expression), :end_keyword) {
-        # An empty rule definition matches the empty string.
-        expression ? expression.value : Rule.for('')
-      }
+      mod all(:rule_keyword, :rule_name, zero_or_one(:expression), :end_keyword) do
+        def rule_name
+          capture(:rule_name)
+        end
+
+        def value
+          # An empty rule definition matches the empty string.
+          expr = capture(:expression)
+          expr ? expr.value : Rule.for('')
+        end
+      end
     end
 
     rule :expression do
@@ -88,7 +100,8 @@ module Citrus
 
     rule :labelled do
       all(zero_or_one(:label), :extended) {
-        rule = extended.value
+        label = capture(:label)
+        rule = capture(:extended).value
         rule.label = label.value if label
         rule
       }
@@ -96,7 +109,8 @@ module Citrus
 
     rule :extended do
       all(:prefix, zero_or_one(:extension)) {
-        rule = prefix.value
+        extension = capture(:extension)
+        rule = capture(:prefix).value
         rule.extension = extension.value if extension
         rule
       }
@@ -104,7 +118,8 @@ module Citrus
 
     rule :prefix do
       all(zero_or_one(:predicate), :suffix) {
-        rule = suffix.value
+        predicate = capture(:predicate)
+        rule = capture(:suffix).value
         rule = predicate.value(rule) if predicate
         rule
       }
@@ -112,7 +127,8 @@ module Citrus
 
     rule :suffix do
       all(:primary, zero_or_one(:repeat)) {
-        rule = primary.value
+        repeat = capture(:repeat)
+        rule = capture(:primary).value
         rule = repeat.value(rule) if repeat
         rule
       }
@@ -124,7 +140,7 @@ module Citrus
 
     rule :grouping do
       all(['(', zero_or_one(:space)], :expression, [')', zero_or_one(:space)]) {
-        expression.value
+        capture(:expression).value
       }
     end
 
@@ -132,7 +148,7 @@ module Citrus
 
     rule :require do
       all(:require_keyword, :quoted_string) {
-        quoted_string.value
+        capture(:quoted_string).value
       }
     end
 
@@ -148,7 +164,7 @@ module Citrus
 
     rule :root do
       all(:root_keyword, :rule_name) {
-        rule_name.value
+        capture(:rule_name).value
       }
     end
 
@@ -172,7 +188,7 @@ module Citrus
 
     rule :alias do
       all(notp(:end_keyword), :rule_name) {
-        Alias.new(rule_name.value)
+        Alias.new(capture(:rule_name).value)
       }
     end
 
@@ -232,7 +248,7 @@ module Citrus
 
     rule :label do
       all(/[a-zA-Z0-9_]+/, :space, ':', :space) {
-        first.to_sym
+        first.to_str.to_sym
       }
     end
 
@@ -312,8 +328,8 @@ module Citrus
 
     rule :star do
       all(/[0-9]*/, '*', /[0-9]*/, :space) { |rule|
-        min = captures[1] == '' ? 0 : captures[1].to_i
-        max = captures[3] == '' ? Infinity : captures[3].to_i
+        min = captures[1] == '' ? 0 : captures[1].to_str.to_i
+        max = captures[3] == '' ? Infinity : captures[3].to_str.to_i
         Repeat.new(rule, min, max)
       }
     end

data/lib/citrus/version.rb

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

data/test/extension_test.rb

@@ -9,12 +9,12 @@ class ExtensionTest < Test::Unit::TestCase
 
   module NumericModule
     def add_one
-      to_i + 1
+      to_str.to_i + 1
     end
   end
 
   NumericProcBare = Proc.new {
-    to_i + 1
+    to_str.to_i + 1
   }
 
   def test_match_module

data/test/grammar_test.rb

@@ -149,6 +149,13 @@ class GrammarTest < Test::Unit::TestCase
     end
   end
 
+  def test_labeled_production
+    grammar = Grammar.new {
+      rule(:abc) { label('abc', :p){ capture(:p) } }
+    }
+    assert_equal('abc', grammar.parse('abc').value)
+  end
+
   def test_global_grammar
     assert_raise ArgumentError do
       grammar(:abc)

data/test/match_test.rb

@@ -94,13 +94,13 @@ class MatchTest < Test::Unit::TestCase
   grammar :Addition do
     rule :additive do
       all(:number, :plus, label(any(:additive, :number), 'term')) {
-        number.value + term.value
+        capture(:number).value + capture(:term).value
       }
     end
 
     rule :number do
       all(/[0-9]+/, :space) {
-        strip.to_i
+        to_str.strip.to_i
       }
     end
 
@@ -139,4 +139,23 @@ class MatchTest < Test::Unit::TestCase
     assert(match.matches)
     assert_equal(3, match.matches.length)
   end
+
+  def test_capture
+    match = Addition.parse('1+2')
+    assert(match.capture(:number))
+    assert_equal(1, match.capture(:number).value)
+  end
+
+  def test_captures
+    match = Addition.parse('1+2')
+    assert(match.captures)
+    assert_equal(7, match.captures.size)
+  end
+
+  def test_captures_with_a_name
+    match = Addition.parse('1+2')
+    assert(match.captures(:number))
+    assert_equal(2, match.captures(:number).size)
+    assert_equal([1, 2], match.captures(:number).map(&:value))
+  end
 end

metadata

@@ -1,30 +1,27 @@
 --- !ruby/object:Gem::Specification
 name: citrus
 version: !ruby/object:Gem::Version
-  version: 3.0.0
-  prerelease: 
+  version: 3.0.1
 platform: ruby
 authors:
 - Michael Jackson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-14 00:00:00.000000000 Z
+date: 2014-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 description: Parsing Expressions for Ruby
@@ -97,6 +94,7 @@ files:
 - CHANGES
 homepage: http://mjijackson.com/citrus
 licenses: []
+metadata: {}
 post_install_message: 
 rdoc_options:
 - --line-numbers
@@ -108,22 +106,20 @@ rdoc_options:
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.23
+rubygems_version: 2.0.3
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Parsing Expressions for Ruby
 test_files:
 - test/alias_test.rb