named-parameters 0.0.6 → 0.0.7

data/README.md

@@ -33,7 +33,7 @@ Then include the `NamedParameters` module into your class:
       include NamedParameters
     end
     
-Either way, you would now be able to  use the  `has_named_parameters` clause 
+Either way, you would now be able to  use the **`has_named_parameters`** clause 
 as needed:
 
     class YourClass
@@ -101,44 +101,151 @@ And is applicable to both class and instance methods:
       end
     end
 
-Gotchas
--------
-When `has_named_parameters` is declared in a class, it instruments the class
-so that when the method in the declaration is invoked, a validation is 
-performed on the first `Hash` argument that was received by the method.
+Shortcuts
+---------
+In addition to the `has_named_parameters` method, `NamedParameters` also comes
+with two convenience methods for applying a parameter spec for constructors:
+
+Use the **`requires`** clause to declare what parameters a class expects when it
+is instantiated:
+
+    class GoogleStorage
+      requires [ :'access-key', :'secret-key' ]
+      
+      def initialize options
+        # ... do googly stuff here ...
+      end
+    end
+
+Use the **`recognizes`** clause to specify optional parameters for constructors:
+
+    class GoogleStorage
+      recognizes [ :'group-email', :'apps-domain' ]
+      
+      def initialize options
+        # ... do googly stuff here ...
+      end
+    end
+
+You may also specify default values for parameters when using these clauses:
+
+    class GoogleStorage
+      requires   [ :'access-key', :'secret-key' ]
+      recognizes [ [ :'group-email', 'group@example.org' ], [ :'apps-domain', 'example.org' ] ]
+
+      def initialize options
+        # ... do googly stuff here ...
+      end
+    end
+
+Permissive Mode
+---------------
+When a method is declared with `has_named_parameters` that method will only 
+accept keys that were listed as `:required`, `:optional`, or `:oneof` - 
+passing any other key to the `Hash` arg will raise an `ArgumentError` on
+method call:
+
+    has_named_parameters :exec, :required => :w, :optional => [ :x, :y ]
+    def exec opts 
+      # ...
+    end
+    
+    # the following will raise an ArgumentError since :z was not declared
+    exec :w => 1, :x => 2, :y => 3, :z => 4
+
+But sometimes you need to be able to pass additional keys and you don't know 
+what those keys are. Setting the optional `mode` parameter for 
+`has_named_parameters` to `:permissive` will relax this restriction:
+
+    has_named_parameters :exec, { :required => :w, :optional => [ :x, :y ] }, :permissive
+    def exec opts 
+      # ...
+    end
 
-It really has no idea about the position of the argument that is supposed
-to carry the named parameters.
+    # the following will no longer raise an ArgumentError
+    exec :w => 1, :x => 2, :y => 3, :z => 4
+
+The `:required` and `:oneof` parameters will still be expected:
+
+    # the following will still raise an ArgumentError since :w is required
+    exec :x => 2, :y => 3, :z => 4
+
+For clarity you should skip the `:optional` parameters list altogether when 
+using the `:permissive` mode.
+
+The `requires` and `recognizes` clause for constructors will also accept a 
+`mode` setting:
+
+    requires   [ :x ], :permissive
+    recognizes [ :y, :z ], :permissive
+
+And just like the `:optional` parameter list in the `has_named_parameters` 
+clause, when `:permissive` mode is used, it's clearer to omit the `recognizes`
+clause altogether.
+
+How It Works
+------------
+When the `has_named_parameters` is declared in a class, it instruments the 
+class so that when the method in the declaration is invoked, a validation is 
+performed on the last `Hash` argument that was received by the method.
+
+It expects that the last argument is the the `Hash` args representing the 
+named parameters when a method is invoked. If no `Hash` args was supplied
+then it creates one.
 
 So you can mix-and-match argument types in a method, and still declare that
 it `has_named_parameters`:
 
-    has_named_parameters :request, :required => :accesskey
+    has_named_parameters :request, 
+      :required => :key, 
+      :optional => [ :etc, 'howl' ]
     def request path, options
       "path: #{path}, options: #{options.inspect}"
     end
     
     # invocation:
-    request "/xxx", :accesskey => '0925'  
+    request "/xxx", :key => '0925'  
     
     # result:
-    # => path: /xxx, options: {:accesskey => '0925'}
-    
-But be careful when you have something like the following:
+    # => path: /xxx, options: {:key => '0925', :etc => 'howl'}
+
+Gotchas
+-------    
+It has no idea if the last argument really is the last argument. So be careful 
+when you have something similar to the following:
 
-    has_named_parameters :request, :required => :accesskey
-    def request path, options = { }
+    has_named_parameters :request, :optional => :key
+    def request path = "/xxx", options = { }
       "path: #{path}, options: #{options.inspect}"
     end
 
     # invocation:
-    request :accesskey => '0925'  
+    request :key => '0925'  
     
-    # result isn't what's expected:
+    # expecting:
+    # => path: /xxx, options: {:key => '0925'}
+    
+    # but actual result is:
     # => path: {:accesskey => '0925'}, options: {}
 
-The next release of the gem will adopt the convention of having the `Hash` 
-argument as the last argument passed to the method.
+For the above case, it might be better to refactor:
+
+    has_named_parameters :request, :optional => [ :key, [ :path, "/xxx" ] ]
+    def request options = { }
+      "path: #{options.delete :path}, options: #{options.inspect}"
+    end
+
+    # invocation:
+    request :key => '0925'  
+
+    # result:
+    # => path: /xxx, options: {:key => '0925'}
+
+    # invocation:
+    request
+
+    # result:
+    # => path: /xxx, options: {}
 
 Dependencies
 ------------

data/RELEASENOTES

@@ -1,3 +1,27 @@
+0.0.7 [Nov 18, 2010]
+- [FEATURE] Added support to distinguish named parameters declaration for 
+  class and instance methods that uses the same names. So now you could do:
+  
+      class Mailer
+        has_named_parameters :send_mail, 
+          :required => :to, 
+          :optional => [ :from, 'yourself@example.org' ]
+        def send_mail options = { }
+          Mailer.send_mail options
+        end
+
+        has_named_parameters :'self.send_mail', :required => [ :to, :from ]
+        def self.send_mail options = { }
+          # ... do mail sending stuff here ...
+        end
+      end
+      
+- [FEATURE] Added support for requires clause.
+- [FEATURE] Added support for recognizes clause.
+- [FEATURE] Added support for permissive evaluation of optional parameters.
+- [INTERNAL] Will now expect that the Hash args for the named parameters is 
+  the last argument of the method.
+
 0.0.6 [Nov 13, 2010]
 - [FEATURE] Added support for requiring one-of from a list of named 
   parameters.
@@ -8,27 +32,21 @@
 - [INTERNAL] Updated tests.
 
 0.0.5 [Nov 11, 2010]
---------------------
 - [BUGFIX] Same as 0.0.4 - except this time it's really fixed :-)
 
 0.0.4 [Nov 11, 2010]
---------------------
 - [BUGFIX] Reported method name when ArgumentError is raised was ugly. 
 
 0.0.3 [Nov 11, 2010]
---------------------
 - [FEATURE] 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
   that raised it.
 
 0.0.1 [Nov 10, 2010]
---------------------
 - Initial release.
 
 0.0.0 [Nov 10, 2010]
---------------------
 - Initial release. (yanked)

data/VERSION

@@ -1 +1 @@
-0.0.6
+0.0.7

data/lib/named-parameters/module.rb

@@ -37,14 +37,14 @@ module NamedParameters
     required = spec[:required].map &mapper
     oneof    = spec[:oneof].map &mapper
     
-    # determine what keys are allowed
-    order    = lambda{ |x, y| x.to_s <=> y.to_s }
-    allowed  = (optional + required + oneof).sort &order
+    # determine what keys are allowed, unless mode is :permissive
+    # in which case we don't care unless its listed as required or oneof
+    order   = lambda{ |x, y| x.to_s <=> y.to_s }
+    allowed = spec[:mode] == :permissive ? [] : (optional + required + oneof).sort(&order)
     
     # determine what keys were passed;
     # also, plugin the names of parameters assigned with default values
-    #keys     = (params.keys.map{ |k| k.to_sym } + defaults.keys).uniq
-    keys     = params.keys.map{ |k| k.to_sym }
+    keys = params.keys.map{ |k| k.to_sym }
     keys.sort! &order
     required.sort! &order
     
@@ -103,7 +103,12 @@ module NamedParameters
     #   * `:optional` means that all or none of these parameters may be used.
     #   * `:oneof` means that one of these parameters must be specified.
     #
-    def has_named_parameters method, spec = { }
+    # @param [Symbol] mode enforces that only parameters that were named in
+    #   either the `:required`, `:optional`, and `:oneof` list may be allowed.
+    #   Set it to `:permissive` to relax the requirement - `:required` and `:oneof`
+    #   parameters will still be expected.
+    #
+    def has_named_parameters method, spec, mode = :strict
       # ensure spec entries are initialized and the proper types
       [ :required, :optional, :oneof ].each{ |k| spec[k] ||= [] }
       spec = Hash[ spec.map{ |k, v| 
@@ -111,7 +116,52 @@ module NamedParameters
         v.map!{ |entry| entry.instance_of?(Array) ? Hash[*entry] : entry }
         [ k, v ]
       } ]
-      specs[method] = spec
+      spec[:mode] = mode
+      specs[key_for(method)] = spec
+    end
+    
+    # Convenience method, equivalent to declaring:
+    #
+    #     has_named_parameters :'self.new', :required => params
+    #     has_named_parameters :initialize, :required => params
+    # 
+    # @param [Array] params the lists of parameters. The list is expected 
+    #   to be an `Array` of symbols matching the names of the required 
+    #   parameters.
+    #
+    # @param [Symbol] mode enforces that only parameters that were named in
+    #   either the `:required`, `:optional`, and `:oneof` list may be allowed.
+    #   Set it to `:permissive` to relax the requirement - `:required` and `:oneof`
+    #   parameters will still be expected.
+    #
+    def requires params, mode = :strict
+      [ :new, :initialize ].each do |method|
+        spec = specs[key_for method] || { }
+        spec.merge!(:required => params)
+        has_named_parameters method, spec, mode
+      end
+    end
+    
+    # Convenience method, equivalent to declaring:
+    #
+    #     has_named_parameters :'self.new', :optional => params
+    #     has_named_parameters :initialize, :optional => params
+    # 
+    # @param [Array] params the lists of parameters. The list is expected 
+    #   to be an `Array` of symbols matching the names of the optional
+    #   parameters.
+    #
+    # @param [Symbol] mode enforces that only parameters that were named in
+    #   either the `:required`, `:optional`, and `:oneof` list may be allowed.
+    #   Set it to `:permissive` to relax the requirement - `:required` and `:oneof`
+    #   parameters will still be expected.
+    #
+    def recognizes params, mode = :strict
+      [ :new, :initialize ].each do |method|
+        spec = specs[key_for method] || { }
+        spec.merge!(:optional => params)
+        has_named_parameters method, spec, mode
+      end
     end
     
     protected
@@ -151,7 +201,7 @@ module NamedParameters
     def singleton_method_added name  # :nodoc:
       instrument name do
         method = self.eigenclass.instance_method name
-        spec   = specs.delete name
+        spec   = specs[key_for :"self.#{name}"] || specs[key_for name]
         owner  = "#{self.name}::"
         eigenclass.instance_eval do
           intercept method, owner, name, spec
@@ -164,7 +214,7 @@ module NamedParameters
     def method_added name  # :nodoc:
       instrument name do
         method = instance_method name
-        spec   = specs.delete name
+        spec   = specs[key_for name] || specs[key_for :"self.#{name}"]
         owner  = "#{self.name}#"
         intercept method, owner, name, spec
       end
@@ -174,7 +224,7 @@ module NamedParameters
     private
     # apply instrumentation to method
     def instrument method  # :nodoc:
-      if specs.include? method and !instrumenting?
+      if specs.include? key_for(method) and !instrumenting?
         @instrumenting = true
         yield method
         @instrumenting = false
@@ -187,13 +237,14 @@ module NamedParameters
       define_method name do |*args, &block|
         # locate the argument representing the named parameters value
         # for the method invocation
-        params = args.find{ |arg| arg.instance_of? Hash }
-        args << (params = { }) if params.nil?
+        params = args.last
+        args << (params = { }) unless params.instance_of? Hash
 
         # merge the declared default values for params into the arguments
         # used when the method is invoked
         defaults = { }
         spec.each do |k, v|
+          next if k == :mode
           v.each{ |entry| defaults.merge! entry if entry.instance_of? Hash }
         end
         params = defaults.merge params
@@ -203,7 +254,7 @@ module NamedParameters
         
         # inject the updated argument values for params into the arguments
         # before actually making method invocation
-        args.map!{ |arg| arg.instance_of?(Hash) ? params : arg }
+        args[args.length - 1] = params
         method.bind(self).call(*args, &block)
       end
     end
@@ -213,6 +264,11 @@ module NamedParameters
       @specs ||= { }
     end
     
+    def key_for method
+      type = method.to_s =~ /^self\./ ? :singleton : :instance
+      :"#{self.name}::#{type}.#{method}"
+    end
+    
     # check if in the process of instrumenting a method
     def instrumenting?  # :nodoc:
       @instrumenting

data/named-parameters.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{named-parameters}
-  s.version = "0.0.6"
+  s.version = "0.0.7"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Juris Galang"]
-  s.date = %q{2010-11-13}
+  s.date = %q{2010-11-18}
   s.description = %q{This gem simulates named-parameters in Ruby. It's a complement to the common 
     Ruby idiom of using `Hash` args to emulate the use of named parameters. 
 

data/spec/named-parameters_spec.rb

@@ -5,7 +5,7 @@ describe "NamedParameters" do
     class Foo
       has_named_parameters :initialize, :required => :x, :optional => [ :y, :z ]
       def initialize opts = {}; end
-      
+
       has_named_parameters :method_one, :required => :x, :optional => [ :y, :z ]
       def method_one x, y, opts = {}; end
 
@@ -172,4 +172,29 @@ describe "NamedParameters" do
     lambda { Quux.new :x => :x, :y => :y }.should raise_error ArgumentError
     lambda { Quux.new :x => :x }.should_not raise_error
   end
+  
+  it "should be able to specify optional parameters using the recognizes method" do
+    class Recognizes
+      recognizes [ :x, :y ]
+      def self.new opts = { }; end
+      def initialize opts = { }; end
+    end
+    lambda { Recognizes.new }.should_not raise_error
+    lambda { Recognizes.new :x => :x }.should_not raise_error
+    lambda { Recognizes.new :y => :y }.should_not raise_error
+    lambda { Recognizes.new :x => :x, :y => :y }.should_not raise_error
+    lambda { Recognizes.new :z => :z }.should raise_error ArgumentError
+  end
+
+  it "should be able to specify required parameters using the recognizes method" do
+    class Required
+      requires [ :x, :y ]
+      def self.new opts = { }; end
+      def initialize opts = { }; end
+    end
+    lambda { Required.new }.should raise_error ArgumentError
+    lambda { Required.new :x => :x }.should raise_error ArgumentError
+    lambda { Required.new :y => :y }.should raise_error ArgumentError
+    lambda { Required.new :x => :x, :y => :y }.should_not raise_error
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: named-parameters
 version: !ruby/object:Gem::Version 
-  hash: 19
+  hash: 17
   prerelease: false
   segments: 
   - 0
   - 0
-  - 6
-  version: 0.0.6
+  - 7
+  version: 0.0.7
 platform: ruby
 authors: 
 - Juris Galang
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-13 00:00:00 -08:00
+date: 2010-11-18 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency