From 81b728c2436bfd94abe33b152493bc5b7a3a1728 Mon Sep 17 00:00:00 2001 From: matz Date: Mon, 26 Sep 2005 13:59:47 +0000 Subject: [PATCH] * eval.c (set_trace_func): add rb_secure(4) to prevent adding tracing function. * lib/delegate.rb: document update from James Edward Gray II . [ruby-core:05942] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_1_8@9317 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ChangeLog | 10 +++ eval.c | 1 + lib/.document | 2 + lib/delegate.rb | 191 ++++++++++++++++++++++++++++++++++++++++----- lib/forwardable.rb | 174 +++++++++++++++++++++++++++++++++++------ 5 files changed, 332 insertions(+), 46 deletions(-) diff --git a/ChangeLog b/ChangeLog index 2f7161eb3e..af525ed0b7 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +Mon Sep 26 22:32:13 2005 Yukihiro Matsumoto + + * eval.c (set_trace_func): add rb_secure(4) to prevent adding + tracing function. + Sun Sep 25 12:05:10 2005 Masatoshi SEKI * bin/erb: typo fixed. @@ -37,6 +42,11 @@ Sat Sep 24 08:38:07 2005 Minero Aoki * test/fileutils/test_verbose.rb: new file. +Sat Sep 24 02:40:20 2005 Yukihiro Matsumoto + + * lib/delegate.rb: document update from James Edward Gray II + . [ruby-core:05942] + Thu Sep 22 23:36:24 2005 Nobuyoshi Nakada * lib/mkmf.rb (find_executable0): default path if environment is not diff --git a/eval.c b/eval.c index 0140ed7d88..e9b953044e 100644 --- a/eval.c +++ b/eval.c @@ -2545,6 +2545,7 @@ set_trace_func(obj, trace) { rb_event_hook_t *hook; + rb_secure(4); if (NIL_P(trace)) { trace_func = 0; rb_remove_event_hook(call_trace_func); diff --git a/lib/.document b/lib/.document index 4e89de07a7..6b7422ed62 100644 --- a/lib/.document +++ b/lib/.document @@ -13,6 +13,8 @@ cgi.rb cgi complex.rb date.rb +delegate.rb +erb.rb English.rb fileutils.rb find.rb diff --git a/lib/delegate.rb b/lib/delegate.rb index ca1f028268..2a0119d082 100644 --- a/lib/delegate.rb +++ b/lib/delegate.rb @@ -1,23 +1,125 @@ -# Delegation class that delegates even methods defined in super class, -# which can not be covered with normal method_missing hack. -# -# Delegator is the abstract delegation class. Need to redefine -# `__getobj__' method in the subclass. SimpleDelegator is the -# concrete subclass for simple delegation. +# = delegate -- Support for the Delegation Pattern # -# Usage: -# foo = Object.new -# foo2 = SimpleDelegator.new(foo) -# foo.hash == foo2.hash # => false +# Documentation by James Edward Gray II and Gavin Sinclair # -# Foo = DelegateClass(Array) +# == Introduction # -# class ExtArraydelegate.rb provides full-class delegation via the +# DelegateClass() method. For single-method delegation via +# def_delegator(), see forwardable.rb. +# +# == Examples +# +# === SimpleDelegator +# +# Here's a simple example that takes advantage of the fact that +# SimpleDelegator's delegation object can be changed at any time. +# +# class Stats +# def initialize +# @source = SimpleDelegator.new([]) +# end +# +# def stats( records ) +# @source.__setobj__(records) +# +# "Elements: #{@source.size}\n" + +# " Non-Nil: #{@source.compact.size}\n" + +# " Unique: #{@source.uniq.size}\n" +# end +# end +# +# s = Stats.new +# puts s.stats(%w{James Edward Gray II}) +# puts +# puts s.stats([1, 2, 3, nil, 4, 5, 1, 2]) +# +# Prints: +# +# Elements: 4 +# Non-Nil: 4 +# Unique: 4 +# +# Elements: 8 +# Non-Nil: 7 +# Unique: 6 +# +# === DelegateClass() +# +# Here's a sample of use from tempfile.rb. +# +# A _Tempfile_ object is really just a _File_ object with a few special rules +# about storage location and/or when the File should be deleted. That makes for +# an almost textbook perfect example of how to use delegation. +# +# class Tempfile < DelegateClass(File) +# # constant and class member data initialization... +# +# def initialize(basename, tmpdir=Dir::tmpdir) +# # build up file path/name in var tmpname... +# +# @tmpfile = File.open(tmpname, File::RDWR|File::CREAT|File::EXCL, 0600) +# +# # ... +# +# super(@tmpfile) +# +# # below this point, all methods of File are supported... +# end +# +# # ... +# end +# +# === Delegator +# +# SimpleDelegator's implementation serves as a nice example here. +# +# class SimpleDelegator < Delegator +# def initialize(obj) +# super # pass obj to Delegator constructor, required +# @_sd_obj = obj # store obj for future use +# end +# +# def __getobj__ +# @_sd_obj # return object we are delegating to, required +# end +# +# def __setobj__(obj) +# @_sd_obj = obj # change delegation object, a feature we're providing +# end +# +# # ... +# end +# +# Delegator is an abstract class used to build delegator pattern objects from +# subclasses. Subclasses should redefine \_\_getobj\_\_. For a concrete +# implementation, see SimpleDelegator. +# class Delegator + # + # Pass in the _obj_ to delegate method calls to. All methods supported by + # _obj_ will be delegated to. + # def initialize(obj) preserved = ::Kernel.public_instance_methods(false) preserved -= ["to_s","to_a","inspect","==","=~","==="] @@ -49,6 +151,7 @@ class Delegator end alias initialize_methods initialize + # Handles the magic of delegation through \_\_getobj\_\_. def method_missing(m, *args) target = self.__getobj__ unless target.respond_to?(m) @@ -57,23 +160,39 @@ class Delegator target.__send__(m, *args) end + # + # Checks for a method provided by this the delegate object by fowarding the + # call through \_\_getobj\_\_. + # def respond_to?(m) return true if super return self.__getobj__.respond_to?(m) end + # + # This method must be overridden by subclasses and should return the object + # method calls are being delegated to. + # def __getobj__ raise NotImplementedError, "need to define `__getobj__'" end + # Serialization support for the object returned by \_\_getobj\_\_. def marshal_dump __getobj__ end + # Reinitializes delegation from a serialized object. def marshal_load(obj) initialize_methods(obj) end end +# +# A concrete implementation of Delegator, this class provides the means to +# delegate all supported method calls to the object passed into the constructor +# and even to change the object being delegated to at a later time with +# \_\_setobj\_\_ . +# class SimpleDelegator Edward + # names.__setobj__(%w{Gavin Sinclair}) + # puts names[1] # => Sinclair + # def __setobj__(obj) raise ArgumentError, "cannot delegate to self" if self.equal?(obj) @_sd_obj = obj end + # Clone support for the object returned by \_\_getobj\_\_. def clone super __setobj__(__getobj__.clone) end + # Duplication support for the object returned by \_\_getobj\_\_. def dup(obj) super __setobj__(__getobj__.dup) end end +# :stopdoc: # backward compatibility ^_^;;; Delegater = Delegator SimpleDelegater = SimpleDelegator +# :startdoc: +# +# The primary interface to this library. Use to setup delegation when defining +# your class. +# +# class MyClass < DelegateClass( ClassToDelegateTo ) # Step 1 +# def initiaize +# super(obj_of_ClassToDelegateTo) # Step 2 +# end +# end # def DelegateClass(superclass) klass = Class.new @@ -111,31 +258,31 @@ def DelegateClass(superclass) methods -= ::Kernel.public_instance_methods(false) methods |= ["to_s","to_a","inspect","==","=~","==="] klass.module_eval { - def initialize(obj) + def initialize(obj) # :nodoc: @_dc_obj = obj end - def method_missing(m, *args) + def method_missing(m, *args) # :nodoc: unless @_dc_obj.respond_to?(m) super(m, *args) end @_dc_obj.__send__(m, *args) end - def respond_to?(m) + def respond_to?(m) # :nodoc: return true if super return @_dc_obj.respond_to?(m) end - def __getobj__ + def __getobj__ # :nodoc: @_dc_obj end - def __setobj__(obj) + def __setobj__(obj) # :nodoc: raise ArgumentError, "cannot delegate to self" if self.equal?(obj) @_dc_obj = obj end - def clone + def clone # :nodoc: super __setobj__(__getobj__.clone) end - def dup + def dup # :nodoc: super __setobj__(__getobj__.dup) end @@ -159,6 +306,8 @@ def DelegateClass(superclass) return klass end +# :enddoc: + if __FILE__ == $0 class ExtArrayforwardable.rb provides single-method delegation via the +# def_delegator() and def_delegators() methods. For full-class +# delegation via DelegateClass(), see delegate.rb. +# +# == Examples +# +# === Forwardable +# +# Forwardable makes building a new class based on existing work, with a proper +# interface, almost trivial. We want to rely on what has come before obviously, +# but with delegation we can take just the methods we need and even rename them +# as appropriate. In many cases this is preferable to inheritance, which gives +# us the entire old interface, even if much of it isn't needed. +# +# class Queue # extend Forwardable -# -# def_delegators("@out", "printf", "print") -# def_delegators(:@in, :gets) -# def_delegator(:@contents, :[], "content_at") +# +# def initialize +# @q = [ ] # prepare delegate object +# end +# +# # setup prefered interface, enq() and deq()... +# def_delegator :@q, :push, :enq +# def_delegator :@q, :shift, :deq +# +# # support some general Array methods that fit Queues well +# def_delegators :@q, :clear, :first, :push, :shift, :size # end -# f = Foo.new -# f.printf ... -# f.gets -# f.content_at(1) +# +# q = Queue.new +# q.enq 1, 2, 3, 4, 5 +# q.push 6 +# +# q.shift # => 1 +# while q.size > 0 +# puts q.deq +# end +# +# q.enq "Ruby", "Perl", "Python" +# puts q.first +# q.clear +# puts q.first # -# g = Goo.new -# g.extend SingleForwardable -# g.def_delegator("@out", :puts) -# g.puts ... +# Prints: # +# 2 +# 3 +# 4 +# 5 +# 6 +# Ruby +# nil # +# === SingleForwardable +# +# printer = String.new +# printer.extend SingleForwardable # prepare object for delegation +# printer.def_delegator "STDOUT", "puts" # add delegation for STDOUT.puts() +# printer.puts "Howdy!" +# +# Prints: +# +# Howdy! +# +# The Forwardable module provides delegation of specified +# methods to a designated object, using the methods #def_delegator +# and #def_delegators. +# +# For example, say you have a class RecordCollection which +# contains an array @records. You could provide the lookup method +# #record_number(), which simply calls #[] on the @records +# array, like this: +# +# class RecordCollection +# extends Forwardable +# def_delegator :@records, :[], :record_number +# end +# +# Further, if you wish to provide the methods #size, #<<, and #map, +# all of which delegate to @records, this is how you can do it: +# +# class RecordCollection +# # extends Forwardable, but we did that above +# def_delegators :@records, :size, :<<, :map +# end +# +# Also see the example at forwardable.rb. +# module Forwardable @debug = nil class<