decorate 0.3.0

data/History.txt

@@ -0,0 +1,3 @@
+=== 0.3.0 / 2011-01-31
+
+* First (alpha) release!

data/Manifest.txt

@@ -0,0 +1,15 @@
+README.txt
+History.txt
+Manifest.txt
+Rakefile
+test.rb
+docsrc/repo
+lib/decorate.rb
+lib/decorate/create_alias.rb
+lib/decorate/private_method.rb
+lib/decorate/protected_method.rb
+lib/decorate/public_method.rb
+lib/decorate/module_method.rb
+lib/decorate/memoize.rb
+lib/decorate/before_decorator.rb
+lib/decorate/around_decorator.rb

data/README.txt

@@ -0,0 +1,37 @@
+= decorate
+
+Homepage:: http://github.com/lang/decorate
+
+== Description
+
+Python style decorators for Ruby, some common decorators like
+private_method are provided out of the box.
+
+Decorators that come with the decorate library:
+
+* Decorate::PrivateMethod
+* Decorate::ProtectedMethod
+* Decorate::PublicMethod
+* Decorate::ModuleMethod
+* Decorate::Memoize
+
+Helpers to create your own decorators:
+
+* Decorate::AroundDecorator
+* Decorate::BeforeDecorator
+
+== Hygiene issues
+
+Decorate hooks into (aka redefines) Module#method_added and
+Object#singleton_method_added via the classic alias/delegate pattern.
+If you override these methods in one of your classes that use
+decorators, make sure to call +super+, otherwise decorate breaks.
+
+Also, private_method, protected_method, public_method and
+module_method are defined as private methods of Module, but only if
+the respective files are required.
+
+== License
+
+Decorate is licensed under the same terms as the main Ruby
+implementation. See http://www.ruby-lang.org/en/LICENSE.txt.

data/Rakefile

@@ -0,0 +1,13 @@
+require "hoe"
+
+$LOAD_PATH.unshift("lib")
+require "decorate"
+
+Hoe.new "decorate", Decorate::VERSION do |p|
+  p.author = "Stefan Lang"
+  p.email = "langstefan@gmx.at"
+  p.url = "http://github.com/lang/decorate"
+  p.remote_rdoc_dir = ""
+  p.need_tar = true
+  p.need_zip = true
+end

data/docsrc/repo

@@ -0,0 +1,8 @@
+repo.or.cz
+
+Homepage: http://repo.or.cz/w/decorate.git
+Username: lang
+Owner: langstefan@gmx.at
+Mirror URL: git://repo.or.cz/decorate.git
+            http://repo.or.cz/r/decorate.git
+Push URL: git+ssh://repo.or.cz/srv/git/decorate.git

data/lib/decorate.rb

@@ -0,0 +1,104 @@
+module Decorate
+
+  VERSION = "0.3.0"
+
+  # A BlockDecorator instance wraps an object (+block+) and delegates
+  # calls to +decorate+ to the wrapped objects +call+ method.
+  class BlockDecorator
+
+    def initialize(block)
+      @block = block
+    end
+
+    def decorate(klass, method_name)
+      @block.call(klass, method_name)
+    end
+
+  end
+
+  # Push a decorator on the current threads decorator stack.
+  # A decorator is an object that responds to +decorate+ taking a
+  # class and a method name (symbol) as arguments.
+  def self.push_decorator(decorator)
+    raise TypeError, "#{decorator} not a decorator" unless decorator
+    (Thread.current[:_decorator_stack_] ||= []).push(decorator)
+  end
+
+  # Clear the current threads decorator stack. Returns the old stack
+  # as an Enumerable.
+  def self.clear_decorators
+    stack = (Thread.current[:_decorator_stack_] ||= []).dup
+    Thread.current[:_decorator_stack_].clear
+    stack
+  end
+
+  # Add a decorator that will be applied to the next method
+  # definition. Either pass an object that responds to
+  # decorate(klass, method_name) or a block. The block will be wrapped
+  # in a BlockDecorator.
+  #
+  # Example:
+  #
+  #   def trace_def
+  #     Decorate.decorate { |klass, method_name|
+  #       puts "Method #{method_name.inspect} defined in #{klass.inspect}"
+  #     }
+  #   end
+  #
+  #   class Foo
+  #     trace_def
+  #     def bar
+  #       # ...
+  #     end
+  #   end
+  #   # prints: Method :bar defined in Foo
+  def self.decorate(decorator = nil, &block)
+    if decorator.nil?
+      raise "decorator argument or block required" if block.nil?
+      decorator = BlockDecorator.new(block)
+    elsif block
+      raise "won't accept block if decorator argument is given"
+    end
+    push_decorator(decorator)
+  end
+
+  # Apply the current threads decorator stack to the specified method.
+  #
+  # Decorate hooks into Module#method_added and
+  # Object#singleton_method_added to call this method.
+  def self.process_decorators(klass, method_name)
+    Decorate.clear_decorators.reverse!.each { |decorator|
+      decorator.decorate(klass, method_name)
+    }
+  end
+
+end
+
+class Module
+
+  private
+
+  alias _method_added_without_decorate method_added
+
+  def method_added(method_name)
+    #puts "method_added: #{self.inspect}[#{object_id}] #{method_name}"
+    _method_added_without_decorate(method_name)
+    Decorate.process_decorators(self, method_name)
+  end
+
+end
+
+class Object
+
+  private
+
+  alias _singleton_method_added_without_decorate singleton_method_added
+
+  def singleton_method_added(method_name)
+    _singleton_method_added_without_decorate(method_name)
+    klass = class << self; self; end
+    #puts "singleton_method_added: #{klass.inspect}[#{klass.object_id}] #{method_name}"
+    Decorate.process_decorators(klass, method_name)
+  end
+
+end

data/lib/decorate/around_decorator.rb

@@ -0,0 +1,107 @@
+require "decorate"
+require "decorate/create_alias"
+
+module Decorate::AroundDecorator
+
+  # An AroundCall holds the auxiliary information that is passed as
+  # argument to an around method.
+  class AroundCall
+
+    # Receiving object.
+    attr_reader :receiver
+
+    # The message that was sent resulting in this around call.
+    attr_reader :message
+
+    # The name of the method that constitutes the "core" behaviour
+    # (behaviour without the around logic).
+    attr_reader :wrapped_message
+
+    # Original argument list.
+    attr_reader :args
+
+    # Original block.
+    attr_reader :block
+
+    # Holds the result of a transfer to the wrapped method.
+    attr_reader :result
+
+    def initialize(receiver, message, wrapped_message, args, block)
+      @receiver = receiver
+      @message = message
+      @wrapped_message = wrapped_message
+      @args = args
+      @block = block
+      @result = nil
+    end
+
+    # Call the wrapped method. +args+ and +block+ default to original
+    # ones passed by client code. The return value of the wrapped
+    # method is stored in the +result+ attribute and also returned
+    # from transfer.
+    def transfer(args = @args, &block)
+      block ||= @block
+      @result = @receiver.__send__(@wrapped_message, *args, &block)
+    end
+
+  end
+  
+  # Example:
+  #   
+  #   require "decorate/around_decorator"
+  #
+  #   class Ad
+  #     extend Decorate::AroundDecorator
+  #   
+  #     around_decorator :wrap, :call => :wrap
+  #   
+  #     def wrap(call)
+  #       puts "Before #{call.inspect}"
+  #       call.transfer
+  #       puts "After #{call.inspect}"
+  #       call.result + 1
+  #     end
+  #   
+  #     wrap
+  #     def foo(*args, &block)
+  #       puts "foo: #{args.inspect}, block: #{block.inspect}"
+  #       rand 10
+  #     end
+  #   
+  #   end
+  #
+  #   >> o = Ad.new
+  #   => <Ad:0xb7bd1e80>
+  #   >> o.foo
+  #   Before #<Decorate::AroundDecorator::AroundCall:0xb7bd0828 @message=:foo, @result=nil, @receiver=#<Ad:0xb7bd1e80>, @args=[], @block=nil, @wrapped_message=:foo_without_wrap>
+  #   foo: [], block: nil
+  #   After #<Decorate::AroundDecorator::AroundCall:0xb7bd0828 @message=:foo, @result=5, @receiver=#<Ad:0xb7bd1e80>, @args=[], @block=nil, @wrapped_message=:foo_without_wrap>
+  #   => 6
+  def around_decorator(decorator_name, opts) #:doc:
+    around_method_name = opts[:call]
+    unless around_method_name.kind_of?(Symbol)
+      raise "Option :call with Symbol argument required"
+    end
+    unkown_opt = opts.keys.find { |opt| ![:call].include?(opt) }
+    if unkown_opt
+      raise "Unknown option #{unknown_opt.inspect}"
+    end
+
+    self.class.send(:define_method, decorator_name) {
+      Decorate.decorate { |klass, method_name|
+        wrapped_method_name =
+          Decorate.create_alias(klass, method_name, decorator_name)
+        klass.class_eval <<-EOF, __FILE__, __LINE__
+          def #{method_name}(*args, &block)
+            call = Decorate::AroundDecorator::AroundCall.new(
+                     self, :#{method_name}, :#{wrapped_method_name},
+                     args, block)
+            __send__(:#{around_method_name}, call)
+          end
+        EOF
+      }
+    }
+  end
+  private :around_decorator
+
+end

data/lib/decorate/before_decorator.rb

@@ -0,0 +1,66 @@
+require "decorate"
+require "decorate/create_alias"
+
+# This module is highly experimental and might change significantly or
+# be removed completely since its usefulness is highly questionable in
+# its current form.
+module Decorate::BeforeDecorator
+
+  # Example:
+  #
+  #   require "decorate/before_decorator"
+  #
+  #   class Bf
+  #     extend Decorate::BeforeDecorator
+  #
+  #     before_decorator :trace_call, :call => :trace_call
+  #
+  #     def trace_call(method_name, *args, &block)
+  #       puts "Before #{self}.#{method_name}, args: #{args.inspect}, block: #{block.inspect}"
+  #     end
+  #
+  #     def foo
+  #       puts "foo"
+  #     end
+  #
+  #     trace_call
+  #     def bar
+  #       puts "bar"
+  #     end
+  #
+  #   end
+  #
+  #   >> o = Bf.new
+  #   >> o.foo
+  #   foo
+  #   >> o.bar
+  #   Before #<Bf:0xb7b32dbc>.bar, args: [], block: nil
+  #   bar
+  def before_decorator(decorator_name, opts) #:doc:
+    before_method_name = opts[:call]
+    unless before_method_name.kind_of?(Symbol)
+      raise "Option :call with Symbol argument required"
+    end
+    unkown_opt = opts.keys.find { |opt| ![:call].include?(opt) }
+    if unkown_opt
+      raise "Unknown option #{unknown_opt.inspect}"
+    end
+
+    self.class.send(:define_method, decorator_name) {
+      Decorate.decorate { |klass, method_name|
+        wrapped_method_name =
+          Decorate.create_alias(klass, method_name, decorator_name)
+        klass.class_eval <<-EOF, __FILE__, __LINE__
+          def #{method_name}(*args, &block)
+            self.__send__(:#{before_method_name},
+                          :#{method_name}, *args, &block)
+            self.__send__(:#{wrapped_method_name},
+                          *args, &block)
+          end
+        EOF
+      }
+    }
+  end
+  private :before_decorator
+
+end

data/lib/decorate/create_alias.rb

@@ -0,0 +1,28 @@
+module Decorate
+
+  # Create a private alias for the instance method named +method_name+
+  # of class +klass+. The string representation of +id+ will be part
+  # of the alias to ease debugging. This method makes sure that the
+  # alias doesn't redefine an existing method.
+  #
+  # Returns the name of the new alias.
+  #
+  # In the simplest case, the alias will be
+  # <tt>"#{method_name}_without_#{id}"</tt>.
+  def self.create_alias(klass, method_name, id)
+    basename = "#{method_name}_without_#{id}"
+
+    i = 0
+    new_name = basename
+    loop {
+      break unless klass.method_defined?(new_name)
+      i += 1
+      new_name = "#{basename}_#{i}"
+    }
+
+    klass.send(:alias_method, new_name, method_name)
+    klass.send(:private, new_name)
+    new_name
+  end
+
+end

data/lib/decorate/memoize.rb

@@ -0,0 +1,39 @@
+require "decorate"
+require "decorate/create_alias"
+
+module Decorate::Memoize
+  
+  # A naive memoization decorator, using a plain Hash as cache.
+  #
+  # Example usage:
+  #
+  #   require "decorate/memoize"
+  #
+  #   Decorate::Memoize.memoize
+  #   def factorial(n)
+  #     n == 0 ? 1 : n * factorial(n - 1)
+  #   end
+  #   factorial(7) # => 5040
+  #
+  # Memoization takes the arguments as well as the instance itself
+  # into account. You can also extend a module/class with
+  # Decorate::Memoize to leave off the module prefix. Note that this
+  # decorator doesn't work for methods that take a block.
+  def memoize
+    Decorate.decorate { |klass, method_name|
+      wrapped_method_name = Decorate.create_alias(klass, method_name, :memoize)
+      # TODO: should use weak hash tables
+      cache = Hash.new { |hash, key| hash[key] = {} }
+      klass.send(:define_method, method_name) { |*args|
+        icache = cache[self]
+        if icache.has_key?(args)
+          icache[args]
+        else
+          icache[args] = send(wrapped_method_name, *args)
+        end
+      }
+    }
+  end
+  module_function :memoize
+
+end

data/lib/decorate/module_method.rb

@@ -0,0 +1,52 @@
+require "decorate"
+
+#--
+# I'm not sure if module_method is the right name...
+#++
+
+module Decorate::ModuleMethod
+
+  # module_method decorator - makes the next defined method a module
+  # function. This decorator is available at the class and module
+  # level. The effect is the same as calling Module#module_function
+  # with the method name after the method definition.
+  #
+  # Example:
+  #
+  #   require "decorate/module_method"
+  #
+  #   module Shell
+  #
+  #     module_method
+  #     def sh(command)
+  #       system(command)
+  #     end
+  #
+  #   end
+  #
+  # is equivalent to:
+  #
+  #   module Shell
+  #
+  #     def sh(command)
+  #       system(command)
+  #     end
+  #     module_function :sh
+  #
+  #   end
+  #
+  # In this example, +sh+ is now a method of the +Shell+ object as
+  # well as an instance method of the +Shell+ module. Read <tt>ri
+  # Module#module_function</tt> for more details.
+  def module_method #:doc:
+    Decorate.decorate { |klass, method_name|
+      klass.send :module_function, method_name
+    }
+  end
+  private :module_method
+  
+end
+
+class Module
+  include Decorate::ModuleMethod
+end

data/lib/decorate/private_method.rb

@@ -0,0 +1,50 @@
+require "decorate"
+
+module Decorate::PrivateMethod
+
+  # private_method decorator - makes the next defined method private.
+  # Can be used at the module-, class- and toplevel.
+  #
+  # Examples:
+  #
+  #   require "decorate/private_method"
+  #
+  #   class Foo
+  #     private_method
+  #     def bar
+  #       puts "Foo#bar called"
+  #     end
+  #     def foo
+  #       bar
+  #     end
+  #   end
+  #   f = Foo.new
+  #   f.foo # Foo#bar called
+  #   f.bar # NoMethodError: private method `bar' called for #<Foo:0xb7be2f64>
+  #
+  #   my_object = Object.new
+  #   private_method
+  #   def my_object.foo
+  #     puts "foo"
+  #   end
+  #   my_object.foo # => NoMethodError: private method `foo' called for #<Object:0xb7bdce20>
+  #
+  #   private_method
+  #   Foo.send(:define_method, :baz) { puts "baz" }
+  #   f.baz # => NoMethodError: private method `baz' called for #<Foo:0xb7ba7d38>
+  def private_method #:doc:
+    Decorate.decorate { |klass, method_name|
+      klass.send :private, method_name
+    }
+  end
+  private :private_method
+
+end
+
+# Make private_method available at the class/module level.
+class Module
+  include Decorate::PrivateMethod
+end
+
+# Make private_method available at the toplevel.
+extend Decorate::PrivateMethod

data/lib/decorate/protected_method.rb

@@ -0,0 +1,19 @@
+require "decorate"
+
+module Decorate::ProtectedMethod
+  # protected_method decorator - makes the next defined method
+  # protected. Otherwise works like
+  # Decorate::PrivateMethod#private_method.
+  def protected_method #:doc:
+    Decorate.decorate { |klass, method_name|
+      klass.send :protected, method_name
+    }
+  end
+  private :protected_method
+end
+
+class Module
+  include Decorate::ProtectedMethod
+end
+
+extend Decorate::ProtectedMethod

data/lib/decorate/public_method.rb

@@ -0,0 +1,18 @@
+require "decorate"
+
+module Decorate::PublicMethod
+  # public_method decorator - makes the next defined method public.
+  # Otherwise works like Decorate::PrivateMethod#private_method.
+  def public_method #:doc:
+    Decorate.decorate { |klass, method_name|
+      klass.send :public, method_name
+    }
+  end
+  private :public_method
+end
+
+class Module
+  include Decorate::PublicMethod
+end
+
+extend Decorate::PublicMethod

data/test.rb

@@ -0,0 +1,120 @@
+$:.unshift "lib"
+
+require "decorate/private_method"
+require "decorate/memoize"
+
+class Foo
+
+  def foo
+    puts "foo"
+    bar
+  end
+
+  private_method
+  def bar
+    puts "bar"
+  end
+
+end
+
+class M1
+  extend Decorate::Memoize
+
+  memoize
+  def m1(a, b)
+    puts "#{self}.m1(#{a}, #{b})"
+    case [a,b]
+    when [1,2]; 1
+    when [2,3]; 2
+    when [4,5]; 3
+    else -1
+    end
+  end
+
+  puts "defining class method m1"
+
+  # doesn't work (yet)
+  # Must hook into Object#singleton_method_added to make it work!
+  memoize
+  def self.m1(a, b)
+    puts "#{self}.m1(#{a}, #{b})"
+    case [a,b]
+    when [1,2]; 1
+    when [2,3]; 2
+    when [4,5]; 3
+    else -1
+    end
+  end
+
+end
+
+extend Decorate::Memoize
+
+memoize
+def mx(a, b)
+  puts "#{self}.m1(#{a}, #{b})"
+  case [a,b]
+  when [1,2]; 1
+  when [2,3]; 2
+  when [4,5]; 3
+  else -1
+  end
+end
+
+Decorate::Memoize.memoize
+def my(a, b)
+  puts "#{self}.m1(#{a}, #{b})"
+  case [a,b]
+  when [1,2]; 1
+  when [2,3]; 2
+  when [4,5]; 3
+  else -1
+  end
+end
+
+private_method
+def private_toplevel_method
+  puts "private_toplevel_method called"
+end
+
+require "decorate/before_decorator"
+class Bf
+  extend Decorate::BeforeDecorator
+
+  before_decorator :trace_call, :call => :trace_call
+
+  def trace_call(method_name, *args, &block)
+    puts "Before #{self}.#{method_name}, args: #{args.inspect}, block: #{block.inspect}"
+  end
+
+  def foo
+    puts "foo"
+  end
+
+  trace_call
+  def bar
+    puts "bar"
+  end
+
+end
+
+require "decorate/around_decorator"
+class Ad
+  extend Decorate::AroundDecorator
+
+  around_decorator :wrap, :call => :wrap
+
+  def wrap(call)
+    puts "Before #{call.inspect}"
+    call.transfer
+    puts "After #{call.inspect}"
+    call.result + 1
+  end
+
+  wrap
+  def foo(*args, &block)
+    puts "foo: #{args.inspect}, block: #{block.inspect}"
+    rand 10
+  end
+
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification 
+name: decorate
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 3
+  - 0
+  version: 0.3.0
+platform: ruby
+authors: 
+- Stefan Lang
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-01-31 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 8
+        - 0
+        version: 2.8.0
+  type: :development
+  version_requirements: *id001
+description: |-
+  Python style decorators for Ruby, some common decorators like
+  private_method are provided out of the box.
+  
+  Decorators that come with the decorate library:
+  
+  * Decorate::PrivateMethod
+  * Decorate::ProtectedMethod
+  * Decorate::PublicMethod
+  * Decorate::ModuleMethod
+  * Decorate::Memoize
+  
+  Helpers to create your own decorators:
+  
+  * Decorate::AroundDecorator
+  * Decorate::BeforeDecorator
+email: langstefan@gmx.at
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.txt
+- History.txt
+- Manifest.txt
+files: 
+- README.txt
+- History.txt
+- Manifest.txt
+- Rakefile
+- test.rb
+- docsrc/repo
+- lib/decorate.rb
+- lib/decorate/create_alias.rb
+- lib/decorate/private_method.rb
+- lib/decorate/protected_method.rb
+- lib/decorate/public_method.rb
+- lib/decorate/module_method.rb
+- lib/decorate/memoize.rb
+- lib/decorate/before_decorator.rb
+- lib/decorate/around_decorator.rb
+has_rdoc: true
+homepage: http://github.com/lang/decorate
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: decorate
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Python style decorators for Ruby, some common decorators like private_method are provided out of the box
+test_files: []
+