named-parameters 0.0.2 → 0.0.3

data/README.md

@@ -2,6 +2,9 @@ NamedParameters Gem
 ===================
 This gem enables/simulates named-parameters in Ruby.
 
+See: http://en.wikipedia.org/wiki/named_parameter for more information on 
+Named Parameters in general.
+
 Installation
 ------------
 
@@ -53,14 +56,14 @@ invocation will (correctly) raise an `ArgumentError`
 
     GoogleStorage.new   # ArgumentError, GoogleStorage#initialize requires: access-key, secret-key
 
-On the other-hand, it declares that the `request` method may accept a parameter
-named `timeout`; so the following invocations will not raise error:
+On the other-hand, it declares that the `request` method may optionally accept 
+a parameter named `timeout` - so the following invocations will not raise error:
 
     gs = GoogleStorage.new :'access-key' => '...', :'secret-key' => '...'
     gs.request '/some/path'
     gs.request '/some/path', :timeout => '500ms'
 
-But specifiying an unrecognized parameter, will raise an error:
+But specifying an unrecognized parameter will do:
 
     gs.request '/some/path', :ssl => true # ArgumentError, GoogleStorage#request unrecognized parameter: ssl
 
@@ -82,7 +85,7 @@ argument when a method that has been declared with `has_named_parameters` is
 called.
 
 It does not know the name of the `Hash` parameter for the method. So the 
-following method declarations:
+following variations:
 
     def service opts = { }
       # ...

data/RELEASENOTES

@@ -1,3 +1,7 @@
+0.0.3 [Nov 11, 2010]
+--------------------
+- Added support for has_named_parameter declaration for class methods.
+
 0.0.2 [Nov 10, 2010]
 --------------------
 - [BUGFIX] ArgumentError incorrectly references Module instead of actual class

data/VERSION

@@ -1 +1 @@
-0.0.2
+0.0.3

data/lib/named-parameters/module.rb

@@ -15,13 +15,24 @@
 #   FooBar.new :x => '...' # instantiates FooBar
 #   FooBar.new :y => '...' # ArgumentError - since :x was not specified
 #
+# @author Juris Galang
+#
+class Object  
+  def eigenclass # :nodoc:
+    class << self; self; end  
+  end  
+end
+
 module NamedParameters
-  def self.included base
+  def self.included base # :nodoc:
     base.extend ClassMethods
   end
 
   private
-  def self.validate name, params, spec
+  # this is the method used to validate the name of the received parameters 
+  # (based on the defined spec) when an instrumented method is invoked.
+  #
+  def self.validate name, params, spec  # :nodoc:
     spec[:required] ||= []
     spec[:optional] ||= []
     
@@ -54,36 +65,83 @@ module NamedParameters
   
   module ClassMethods
     protected
-    def method_added name
-      if specs.include?(name) && !instrumenting?
-        @instrumenting = true
-        method = instance_method(name)
-        spec   = specs.delete(name)
-        define_method name do |*args, &block|
-          params = args.find{ |arg| arg.instance_of? Hash }
-          name   = "#{self.class.name}##{name}"
-          NamedParameters::validate name, params || {}, spec
-          method.bind(self).call(*args, &block)
+    # Declares that `method` will enforce named parameters behavior as 
+    # described in `spec`; a method declared with `required` and/or `optional`
+    # parameters will raise an `ArgumentError` if it is invoked without its
+    # required parameters or receives an unrecognized parameter.
+    #
+    # Sample usage:
+    #
+    #     has_named_parameters :point, :required => [ :x, :y ], 
+    #       :optional => :color
+    #
+    # @param [Symbol] `method` the name of the method that is supposed to 
+    #   enforce named parameters behavior.
+    #
+    # @param [Hash] `spec` the list of required and optional parameters. 
+    #
+    # @return [Hash] the specified `spec` 
+    #
+    def has_named_parameters method, spec = { }
+      specs[method] = spec
+    end
+    
+    # add instrumentation for class methods
+    def singleton_method_added name  # :nodoc:
+      instrument name do
+        method = self.eigenclass.instance_method name
+        spec   = specs.delete name
+        owner  = "#{self.name}."
+        eigenclass.instance_eval do
+          intercept method, owner, name, spec
         end
-        @instrumenting = false
+      end
+      super
+    end
+    
+    # add instrumentation for instance methods
+    def method_added name  # :nodoc:
+      instrument name do
+        method = instance_method name
+        spec   = specs.delete name
+        owner  = "#{self.name}#"
+        intercept method, owner, name, spec
       end
       super
     end
 
-    def has_named_parameters method, spec = { }
-      specs[method] = spec
+    private
+    # apply instrumentation to method
+    def instrument method  # :nodoc:
+      if specs.include? method and !instrumenting?
+        @instrumenting = true
+        yield method
+        @instrumenting = false
+      end
     end
     
-    private
-    def specs
+    # insert parameter validation prior to executing the instrumented method
+    def intercept method, owner, name, spec  # :nodoc:
+      define_method name do |*args, &block|
+        params = args.find{ |arg| arg.instance_of? Hash }
+        name   = "#{owner}#{name}"
+        NamedParameters::validate name, params || {}, spec
+        method.bind(self).call(*args, &block)
+      end
+    end
+    
+    # initialize specs table as needed 
+    def specs  # :nodoc:
       @specs ||= { }
     end
     
-    def instrumenting?
+    # check if in the process of instrumenting a method
+    def instrumenting?  # :nodoc:
       @instrumenting
     end
     
-    def self.extended base
+    # initialize the @instrumenting instance variable (housekeeping)
+    def self.extended base  # :nodoc:
       base.instance_variable_set :@instrumenting , false
     end
   end

data/named-parameters.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{named-parameters}
-  s.version = "0.0.2"
+  s.version = "0.0.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Juris Galang"]
-  s.date = %q{2010-11-10}
+  s.date = %q{2010-11-11}
   s.description = %q{This gem enables/simulates named-parameters in Ruby}
   s.email = %q{jurisgalang@gmail.com}
   s.extra_rdoc_files = [

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: named-parameters
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 25
   prerelease: false
   segments: 
   - 0
   - 0
-  - 2
-  version: 0.0.2
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - Juris Galang
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-10 00:00:00 -08:00
+date: 2010-11-11 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency