lib/walrat/match_data_wrapper.rb

   1 # Copyright 2007-2010 Wincent Colaiuta. All rights reserved.
   2 # Redistribution and use in source and binary forms, with or without
   3 # modification, are permitted provided that the following conditions are met:
   4 #
   5 # 1. Redistributions of source code must retain the above copyright notice,
   6 #    this list of conditions and the following disclaimer.
   7 # 2. Redistributions in binary form must reproduce the above copyright notice,
   8 #    this list of conditions and the following disclaimer in the documentation
   9 #    and/or other materials provided with the distribution.
  10 #
  11 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  12 # AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  13 # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  14 # ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
  15 # LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  16 # CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  17 # SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  18 # INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  19 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  20 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  21 # POSSIBILITY OF SUCH DAMAGE.
  22
  23 require 'walrat'
  24
  25 module Walrat
  26   # Simple wrapper for MatchData objects that implements length, to_s and
  27   # to_str methods.
  28   #
  29   # By implementing to_str, MatchDataWrappers can be directly compared with
  30   # Strings using the == method. The original MatchData instance can be
  31   # obtained using the match_data accessor. Upon creation a clone of the passed
  32   # in MatchData object is stored; this means that the $~ global variable can
  33   # be conveniently wrapped without having to worry that subsequent operations
  34   # will alter the contents of the variable.
  35   class MatchDataWrapper
  36     include Walrat::LocationTracking
  37
  38     attr_reader :match_data
  39
  40     # Raises if data is nil.
  41     def initialize data
  42       raise ArgumentError, 'nil data' if data.nil?
  43       self.match_data = data
  44     end
  45
  46     # The definition of this method, in conjunction with the == method, allows
  47     # automatic comparisons with String objects using the == method.
  48     # This is because in a parser matches essentially are Strings (just like
  49     # Exceptions and Pathnames); it's just that this class encapsulates a
  50     # little more information (the match data) for those who want it.
  51     def to_str
  52       self.to_s
  53     end
  54
  55     # Although this method explicitly allows for MatchDataWrapper to
  56     # MatchDataWrapper comparisons, note that all such comparisons will return
  57     # false except for those between instances which were initialized with
  58     # exactly the same match data instance; this is because the MatchData class
  59     # itself always returns false when compared with other MatchData instances.
  60     def ==(other)
  61       if other.kind_of? MatchDataWrapper
  62         self.match_data == other.match_data
  63       elsif other.respond_to? :to_str
  64         self.to_str == other.to_str
  65       else
  66         false
  67       end
  68     end
  69
  70     def to_s
  71       @match_data[0]
  72     end
  73
  74     def jlength
  75       self.to_s.jlength
  76     end
  77
  78   private
  79
  80     def match_data=(data)
  81       @match_data = (data.clone rescue data)
  82     end
  83   end # class MatchDataWrapper
  84 end # module Walrat