]> git.wincent.com - walrat.git/blob - lib/walrat/match_data_wrapper.rb
Initial import (extraction from Walrus repo, commit 0c9d44c)
[walrat.git] / 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