← Back to branch summary

~ubuntu-branches/ubuntu/hardy/ruby1.8/hardy-updates

« back to all changes in this revision

Viewing changes to lib/delegate.rb

  • Committer: Bazaar Package Importer
  • Author(s): akira yamada
  • Date: 2007-03-13 22:11:58 UTC
  • mfrom: (1.1.5 upstream)
  • Revision ID: james.westby@ubuntu.com-20070313221158-h3oql37brlaf2go2
Tags: 1.8.6-1
http://bugs.debian.org/410018
* new upstream version, 1.8.6.
* libruby1.8 conflicts with libopenssl-ruby1.8 (< 1.8.6) (closes: #410018)
* changed packaging style to cdbs from dbs.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/delegate.rb
 
1
# = delegate -- Support for the Delegation Pattern
 
2
#
 
3
# Documentation by James Edward Gray II and Gavin Sinclair
 
4
#
 
5
# == Introduction
 
6
#
 
7
# This library provides three different ways to delegate method calls to an
 
8
# object.  The easiest to use is SimpleDelegator.  Pass an object to the
 
9
# constructor and all methods supported by the object will be delegated.  This
 
10
# object can be changed later.
 
11
#
 
12
# Going a step further, the top level DelegateClass method allows you to easily
 
13
# setup delegation through class inheritance.  This is considerably more
 
14
# flexible and thus probably the most common use for this library.
 
15
#
 
16
# Finally, if you need full control over the delegation scheme, you can inherit
 
17
# from the abstract class Delegator and customize as needed.  (If you find
 
18
# yourself needing this control, have a look at _forwardable_, also in the
 
19
# standard library.  It may suit your needs better.)
 
20
#
 
21
# == Notes
 
22
#
 
23
# Be advised, RDoc will not detect delegated methods.
 
24
#
 
25
# <b>delegate.rb provides full-class delegation via the
 
26
# DelegateClass() method.  For single-method delegation via
 
27
# def_delegator(), see forwardable.rb.</b>
 
28
#
 
29
# == Examples
 
30
#
 
31
# === SimpleDelegator
 
32
#
 
33
# Here's a simple example that takes advantage of the fact that
 
34
# SimpleDelegator's delegation object can be changed at any time.
 
35
#
 
36
#   class Stats
 
37
#     def initialize
 
38
#       @source = SimpleDelegator.new([])
 
39
#     end
 
40
#     
 
41
#     def stats( records )
 
42
#       @source.__setobj__(records)
 
43
#               
 
44
#       "Elements:  #{@source.size}\n" +
 
45
#       " Non-Nil:  #{@source.compact.size}\n" +
 
46
#       "  Unique:  #{@source.uniq.size}\n"
 
47
#     end
 
48
#   end
 
49
#   
 
50
#   s = Stats.new
 
51
#   puts s.stats(%w{James Edward Gray II})
 
52
#   puts
 
53
#   puts s.stats([1, 2, 3, nil, 4, 5, 1, 2])
 
54
#
 
55
# <i>Prints:</i>
 
56
#
 
57
#   Elements:  4
 
58
#    Non-Nil:  4
 
59
#     Unique:  4
 
60
# 
 
61
#   Elements:  8
 
62
#    Non-Nil:  7
 
63
#     Unique:  6
 
64
#
 
65
# === DelegateClass()
 
66
#
 
67
# Here's a sample of use from <i>tempfile.rb</i>.
 
68
#
 
69
# A _Tempfile_ object is really just a _File_ object with a few special rules
 
70
# about storage location and/or when the File should be deleted.  That makes for
 
71
# an almost textbook perfect example of how to use delegation.
 
72
#
 
73
#   class Tempfile < DelegateClass(File)
 
74
#     # constant and class member data initialization...
 
75
#   
 
76
#     def initialize(basename, tmpdir=Dir::tmpdir)
 
77
#       # build up file path/name in var tmpname...
 
78
#     
 
79
#       @tmpfile = File.open(tmpname, File::RDWR|File::CREAT|File::EXCL, 0600)
 
80
#     
 
81
#       # ...
 
82
#     
 
83
#       super(@tmpfile)
 
84
#     
 
85
#       # below this point, all methods of File are supported...
 
86
#     end
 
87
#   
 
88
#     # ...
 
89
#   end
 
90
#
 
91
# === Delegator
 
92
#
 
93
# SimpleDelegator's implementation serves as a nice example here.
 
94
#
 
95
#    class SimpleDelegator < Delegator
 
96
#      def initialize(obj)
 
97
#        super             # pass obj to Delegator constructor, required
 
98
#        @_sd_obj = obj    # store obj for future use
 
99
#      end
 
100
# 
 
101
#      def __getobj__
 
102
#        @_sd_obj          # return object we are delegating to, required
 
103
#      end
 
104
# 
 
105
#      def __setobj__(obj)
 
106
#        @_sd_obj = obj    # change delegation object, a feature we're providing
 
107
#      end
 
108
# 
 
109
#      # ...
 
110
#    end
 
111
 
 
112
#
 
113
# Delegator is an abstract class used to build delegator pattern objects from
 
114
# subclasses.  Subclasses should redefine \_\_getobj\_\_.  For a concrete
 
115
# implementation, see SimpleDelegator.
 
116
#
 
117
class Delegator
 
118
 
 
119
  #
 
120
  # Pass in the _obj_ to delegate method calls to.  All methods supported by
 
121
  # _obj_ will be delegated to.
 
122
  #
 
123
  def initialize(obj)
 
124
    preserved = ::Kernel.public_instance_methods(false)
 
125
    preserved -= ["to_s","to_a","inspect","==","=~","==="]
 
126
    for t in self.class.ancestors
 
127
      preserved |= t.public_instance_methods(false)
 
128
      preserved |= t.private_instance_methods(false)
 
129
      preserved |= t.protected_instance_methods(false)
 
130
      break if t == Delegator
 
131
    end
 
132
    preserved << "singleton_method_added"
 
133
    for method in obj.methods
 
134
      next if preserved.include? method
 
135
      begin
 
136
        eval <<-EOS
 
137
          def self.#{method}(*args, &block)
 
138
            begin
 
139
              __getobj__.__send__(:#{method}, *args, &block)
 
140
            rescue Exception
 
141
              $@.delete_if{|s| /:in `__getobj__'$/ =~ s} #`
 
142
              $@.delete_if{|s| /^\\(eval\\):/ =~ s}
 
143
              Kernel::raise
 
144
            end
 
145
          end
 
146
        EOS
 
147
      rescue SyntaxError
 
148
        raise NameError, "invalid identifier %s" % method, caller(4)
 
149
      end
 
150
    end
 
151
  end
 
152
  alias initialize_methods initialize
 
153
 
 
154
  # Handles the magic of delegation through \_\_getobj\_\_.
 
155
  def method_missing(m, *args)
 
156
    target = self.__getobj__
 
157
    unless target.respond_to?(m)
 
158
      super(m, *args)
 
159
    end
 
160
    target.__send__(m, *args)
 
161
  end
 
162
 
 
163
  # 
 
164
  # Checks for a method provided by this the delegate object by fowarding the 
 
165
  # call through \_\_getobj\_\_.
 
166
  # 
 
167
  def respond_to?(m)
 
168
    return true if super
 
169
    return self.__getobj__.respond_to?(m)
 
170
  end
 
171
 
 
172
  #
 
173
  # This method must be overridden by subclasses and should return the object
 
174
  # method calls are being delegated to.
 
175
  #
 
176
  def __getobj__
 
177
    raise NotImplementedError, "need to define `__getobj__'"
 
178
  end
 
179
 
 
180
  # Serialization support for the object returned by \_\_getobj\_\_.
 
181
  def marshal_dump
 
182
    __getobj__
 
183
  end
 
184
  # Reinitializes delegation from a serialized object.
 
185
  def marshal_load(obj)
 
186
    initialize_methods(obj)
 
187
    __setobj__(obj)
 
188
  end
 
189
end
 
190
 
 
191
#
 
192
# A concrete implementation of Delegator, this class provides the means to
 
193
# delegate all supported method calls to the object passed into the constructor
 
194
# and even to change the object being delegated to at a later time with
 
195
# \_\_setobj\_\_ .
 
196
#
 
197
class SimpleDelegator<Delegator
 
198
 
 
199
  # Pass in the _obj_ you would like to delegate method calls to.
 
200
  def initialize(obj)
 
201
    super
 
202
    @_sd_obj = obj
 
203
  end
 
204
 
 
205
  # Returns the current object method calls are being delegated to.
 
206
  def __getobj__
 
207
    @_sd_obj
 
208
  end
 
209
 
 
210
  #
 
211
  # Changes the delegate object to _obj_.
 
212
  #
 
213
  # It's important to note that this does *not* cause SimpleDelegator's methods
 
214
  # to change.  Because of this, you probably only want to change delegation
 
215
  # to objects of the same type as the original delegate.
 
216
  #
 
217
  # Here's an example of changing the delegation object.
 
218
  #
 
219
  #   names = SimpleDelegator.new(%w{James Edward Gray II})
 
220
  #   puts names[1]    # => Edward
 
221
  #   names.__setobj__(%w{Gavin Sinclair})
 
222
  #   puts names[1]    # => Sinclair
 
223
  #
 
224
  def __setobj__(obj)
 
225
    raise ArgumentError, "cannot delegate to self" if self.equal?(obj)
 
226
    @_sd_obj = obj
 
227
  end
 
228
 
 
229
  # Clone support for the object returned by \_\_getobj\_\_.
 
230
  def clone
 
231
    super
 
232
    __setobj__(__getobj__.clone)
 
233
  end
 
234
  # Duplication support for the object returned by \_\_getobj\_\_.
 
235
  def dup(obj)
 
236
    super
 
237
    __setobj__(__getobj__.dup)
 
238
  end
 
239
end
 
240
 
 
241
# :stopdoc:
 
242
# backward compatibility ^_^;;;
 
243
Delegater = Delegator
 
244
SimpleDelegater = SimpleDelegator
 
245
# :startdoc:
 
246
 
 
247
#
 
248
# The primary interface to this library.  Use to setup delegation when defining
 
249
# your class.
 
250
#
 
251
#   class MyClass < DelegateClass( ClassToDelegateTo )    # Step 1
 
252
#     def initiaize
 
253
#       super(obj_of_ClassToDelegateTo)                   # Step 2
 
254
#     end
 
255
#   end
 
256
#
 
257
def DelegateClass(superclass)
 
258
  klass = Class.new
 
259
  methods = superclass.public_instance_methods(true)
 
260
  methods -= ::Kernel.public_instance_methods(false)
 
261
  methods |= ["to_s","to_a","inspect","==","=~","==="]
 
262
  klass.module_eval {
 
263
    def initialize(obj)  # :nodoc:
 
264
      @_dc_obj = obj
 
265
    end
 
266
    def method_missing(m, *args)  # :nodoc:
 
267
      unless @_dc_obj.respond_to?(m)
 
268
        super(m, *args)
 
269
      end
 
270
      @_dc_obj.__send__(m, *args)
 
271
    end
 
272
    def respond_to?(m)  # :nodoc:
 
273
      return true if super
 
274
      return @_dc_obj.respond_to?(m)
 
275
    end
 
276
    def __getobj__  # :nodoc:
 
277
      @_dc_obj
 
278
    end
 
279
    def __setobj__(obj)  # :nodoc:
 
280
      raise ArgumentError, "cannot delegate to self" if self.equal?(obj)
 
281
      @_dc_obj = obj
 
282
    end
 
283
    def clone  # :nodoc:
 
284
      super
 
285
      __setobj__(__getobj__.clone)
 
286
    end
 
287
    def dup  # :nodoc:
 
288
      super
 
289
      __setobj__(__getobj__.dup)
 
290
    end
 
291
  }
 
292
  for method in methods
 
293
    begin
 
294
      klass.module_eval <<-EOS
 
295
        def #{method}(*args, &block)
 
296
          begin
 
297
            @_dc_obj.__send__(:#{method}, *args, &block)
 
298
          rescue
 
299
            $@[0,2] = nil
 
300
            raise
 
301
          end
 
302
        end
 
303
      EOS
 
304
    rescue SyntaxError
 
305
      raise NameError, "invalid identifier %s" % method, caller(3)
 
306
    end
 
307
  end
 
308
  return klass
 
309
end
 
310
 
 
311
# :enddoc:
 
312
 
 
313
if __FILE__ == $0
 
314
  class ExtArray<DelegateClass(Array)
 
315
    def initialize()
 
316
      super([])
 
317
    end
 
318
  end
 
319
 
 
320
  ary = ExtArray.new
 
321
  p ary.class
 
322
  ary.push 25
 
323
  p ary
 
324
 
 
325
  foo = Object.new
 
326
  def foo.test
 
327
    25
 
328
  end
 
329
  def foo.error
 
330
    raise 'this is OK'
 
331
  end
 
332
  foo2 = SimpleDelegator.new(foo)
 
333
  p foo.test == foo2.test       # => true
 
334
  foo2.error                    # raise error!
 
335
end