named-parameters 0.0.5 → 0.0.6

data/README.md

@@ -1,143 +1,144 @@
-NamedParameters Gem
-===================
-This gem enables/simulates named-parameters in Ruby.
+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. 
 
-See: http://en.wikipedia.org/wiki/named_parameter for more information on 
-Named Parameters in general.
+It does this by extending the language with a `has_named_parameters` clause 
+that allows a class to declare the parameters that are acceptable to a method.
 
-Installation
-------------
-
-    gem install named-parameters
+The `has_named_parameters` dictates how the presence of these parameters are
+enforced and raises an `ArgumentError` when a method invocation is made that
+violates the rules for those parameters.
 
-Usage
------    
-To enable it everywhere (recommended):
-
-    require 'named-parameters'
+See: the [Named Parameter](http://en.wikipedia.org/wiki/named_parameter) 
+article from Wikipedia for more information.
 
-And all your classes should be able to declare:
+Get It
+------
+You know you want it:
 
-    has_named_parameters :method, :optional => [ ... ], :required => [ ... ]
+    gem install named-parameters
 
-If you want to be selective about which classes will use it, do:
+Use It
+------
+Make it available everywhere:
 
+    require 'named-parameters'   
+    
+But if you want to be selective, do:
+    
     require 'named-parameters/module'
 
--- then mix-in the `NamedParameters` module into the class of your choice, for
-example:
+Then include the `NamedParameters` module into your class:
 
-    class FooBar
+    class YourClass
       include NamedParameters
-      # ...
     end
+    
+Either way, you would now be able to  use the  `has_named_parameters` clause 
+as needed:
 
-Using the has_named_parameters Method
--------------------------------------
-The `has_named_parameters` method is used to declare that a method accepts a
-`Hash` argument that should be treated like named-parameters:
-
-    class GoogleStorage
-      has_named_parameters :initialize, 
-        :required => [ :'access-key', :'secret-key' ]
-      def initialize opts = { }
-        # ...
-      end
-      
-      has_named_parameters :request, :optional => :timeout
-      def request path, opts = { }
-        # ...
+    class YourClass
+      has_named_parameters :your_method, :require => :param
+      def your_method options
+        puts options.inspect
       end
     end
-    
-Since the `GoogleStorage` class above declares that its initializer requires
-`:'access-key'` and  `:'secret-key'` to be specified, the following
-invocation will (correctly) raise an `ArgumentError` 
 
-    GoogleStorage.new   # ArgumentError, GoogleStorage#initialize requires: access-key, secret-key
+So when you invoke `your_method`, its parameter requirements will now be
+enforced:
 
-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 specifying an unrecognized parameter will do:
+    obj = YourClass.new
+    obj.your_method :param => 'Et tu, Babe?'  # will spit out: 'Et tu, Babe?'
+    obj.your_method                           # will raise an ArgumentError because the required :param was not specified
+        
+Abuse It
+--------
+Declare required parameters:
 
-    gs.request '/some/path', :ssl => true # ArgumentError, GoogleStorage#request unrecognized parameter: ssl
+    has_named_parameters :send_mail, :required => :to
+    has_named_parameters :send_mail, :required => [ :to, :subject ]
     
-The `has_named_parameters` declaration may be used for either class or 
-instance methods of a class:
-
-    class Point
-      has_named_parameters :initialize, :required => [ :x, :y ], :optional => :color
-      def initialize opts = { }
-        # ...
-      end
+Declare optional parameters:
 
-      has_named_parameters :load, :optional => :translations
-      def self.load filename, opts => { }
-        # ...
-      end
-    end
+    has_named_parameters :send_mail, :optional => :subject
+    has_named_parameters :send_mail, :optional => [ :subject, :bcc, :from ]
     
+Declare one of a set of parameters as required (ie: require one and only
+one from a list):
 
-Optional and Required Parameters
---------------------------------
-Optional and required parameters may be declared in a single 
-`has_named_parameters` declaration:
-
-    has_named_parameters :request, :required => :path, :optional => :timeout
+    has_named_parameters :send_mail, :oneof => [ :signature, :alias ]
+    
+Declare default values for optional parameters:
+    
+    has_named_parameters :send_mail, :optional => [ :subject, :bcc, { :from => 'yourself@example.org' } ]
+    has_named_parameters :send_mail, :optional => [ :subject, :bcc, [ :from, 'yourself@example.org' ] ]
 
-To specify more than one optional or required parameter, use an `Array`:
+You can also declare default values for `:required` and `:oneof` parameters, 
+but really, that's just silly.
 
-    has_named_parameters :request, :required => :path, :optional => [ :timeout, :ssl ]
+With `has_named_parameters`, you can mix-and-match parameter requirements:
 
-How It Works
-------------
-The `has_named_parameters` declaration simply looks for the first `Hash` 
-argument when a method that has been declared with `has_named_parameters` is 
-called.
+    has_named_parameters :send_mail, 
+      :required => [ :to, :subject, ],
+      :oneof    => [ :signature, :alias ],
+      :optional => [ :subject, :bcc, [ :from, 'yourself@example.org' ] ]
 
-It does not know the name of the `Hash` parameter for the method. So the 
-following variations:
+And is applicable to both class and instance methods:
 
-    def service opts = { }
-      # ...
+    require 'named-parameters'
+    
+    class Mailer
+      has_named_parameters :send_mail, 
+        :required => [ :to, :subject, ],
+        :oneof    => [ :signature, :alias ],
+        :optional => [ :subject, :bcc, [ :from, 'yourself@example.org' ] ]
+      def send_mail options
+        # ... do send mail stuff here ...
+      end
+      
+      has_named_parameters :archive, :optional => [ :method => 'zip' ]
+      def self.archive options = { }
+        # ... do mail archiving stuff here ...
+      end
     end
 
-    def service options = { } 
-      # ...
-    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.
 
-    def service params
-      # ...
-    end
+It really has no idea about the position of the argument that is supposed
+to carry the named parameters.
 
--- behave the same way, when the `has_named_parameter` clause is used:
+So you can mix-and-match argument types in a method, and still declare that
+it `has_named_parameters`:
 
-    # the following...
-    has_named_parameters :service, :optional => :timeout
-    def service params
-      # ...
+    has_named_parameters :request, :required => :accesskey
+    def request path, options
+      "path: #{path}, options: #{options.inspect}"
     end
+    
+    # invocation:
+    request "/xxx", :accesskey => '0925'  
+    
+    # result:
+    # => path: /xxx, options: {:accesskey => '0925'}
+    
+But be careful when you have something like the following:
 
-    # is essentially the same as...
-    has_named_parameters :service, :optional => :timeout
-    def service opts = { }
-      # ...
+    has_named_parameters :request, :required => :accesskey
+    def request path, options = { }
+      "path: #{path}, options: #{options.inspect}"
     end
 
-    # as well as...
-    has_named_parameters :service, :optional => :timeout
-    def service opts
-      # ...
-    end
+    # invocation:
+    request :accesskey => '0925'  
     
-Since when the method is invoked, each one of the above could receive a `Hash`
+    # result isn't what's expected:
+    # => path: {:accesskey => '0925'}, options: {}
 
-    service :timeout => '500ms'
+The next release of the gem will adopt the convention of having the `Hash` 
+argument as the last argument passed to the method.
 
 Dependencies
 ------------

data/RELEASENOTES

@@ -1,3 +1,12 @@
+0.0.6 [Nov 13, 2010]
+- [FEATURE] Added support for requiring one-of from a list of named 
+  parameters.
+- [FEATURE] Added support for declaring default values for parameters.
+- [INTERNAL] spec is now normalized inside the has_named_parameters 
+  declaration allowing more flexible notation when when specifying default
+  values for parameters.
+- [INTERNAL] Updated tests.
+
 0.0.5 [Nov 11, 2010]
 --------------------
 - [BUGFIX] Same as 0.0.4 - except this time it's really fixed :-)
@@ -8,7 +17,8 @@
 
 0.0.3 [Nov 11, 2010]
 --------------------
-- Added support for has_named_parameter declaration for class methods.
+- [FEATURE] Added support for has_named_parameter declaration for class 
+  methods.
 
 0.0.2 [Nov 10, 2010]
 --------------------

data/Rakefile

@@ -6,7 +6,16 @@ begin
   Jeweler::Tasks.new do |gem|
     gem.name = "named-parameters"
     gem.summary = %Q{Poor man's named-parameters in Ruby}
-    gem.description = %Q{This gem enables/simulates named-parameters in Ruby}
+    gem.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. 
+
+    It does this by extending the language with a `has_named_parameters` clause 
+    that allows a class to declare the parameters that are acceptable to a method.
+
+    The `has_named_parameters` dictates how the presence of these parameters are
+    enforced and raises an `ArgumentError` when a method invocation is made that
+    violates the rules for those parameters.
+    }
     gem.email = "jurisgalang@gmail.com"
     gem.homepage = "http://github.com/jurisgalang/named-parameters"
     gem.authors = ["Juris Galang"]

data/VERSION

@@ -1 +1 @@
-0.0.5
+0.0.6

data/lib/named-parameters.rb

@@ -1,2 +1,6 @@
+require 'named-parameters/object'
 require 'named-parameters/module'
-require 'named-parameters/object'
+
+# Extend object to automatically make it available for all
+# user defined classes...
+Object.extend NamedParameters::ClassMethods

data/lib/named-parameters/module.rb

@@ -1,5 +1,8 @@
-# When mixed-in, this module adds has_named_parameters class method, which
-# can be used to declare methods that are supposed to accepts named-parameters.
+# named-parameters.rb
+# 
+# When mixed-in, the `NamedParameters` module adds has_named_parameters class 
+# method, which can be used to declare methods that are supposed to accepts 
+# named-parameters.
 # 
 # Sample usage:
 #
@@ -16,14 +19,10 @@
 #   FooBar.new :y => '...' # ArgumentError - since :x was not specified
 #
 # @author Juris Galang
+# @copyright 2010 Juris Galang. All Rights Reserved
 #
-class Object  
-  def eigenclass # :nodoc:
-    class << self; self; end  
-  end  
-end
-
 module NamedParameters
+  protected
   def self.included base # :nodoc:
     base.extend ClassMethods
   end
@@ -32,31 +31,47 @@ module NamedParameters
   # 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] ||= []
+  def self.validate_specs name, params, spec  # :nodoc:
+    mapper   = lambda{ |n| n.instance_of?(Hash) ? n.keys.first : n }
+    optional = spec[:optional].map &mapper
+    required = spec[:required].map &mapper
+    oneof    = spec[:oneof].map &mapper
     
-    spec = Hash[ spec.map{ |k, v| 
-      v = [ v ] unless v.instance_of? Array
-      [ k, v ]
-    } ]
+    # determine what keys are allowed
+    order    = lambda{ |x, y| x.to_s <=> y.to_s }
+    allowed  = (optional + required + oneof).sort &order
     
-    sorter  = lambda{ |x, y| x.to_s <=> y.to_s }
-    allowed = (spec[:optional] + spec[:required]).sort &sorter
-    keys    = params.keys.map{ |k| k.to_sym }
-    
-    keys.sort! &sorter
-    spec[:required].sort! &sorter
+    # 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.sort! &order
+    required.sort! &order
     
+    # this lambda is used to present the list of parameters as a string
     list = lambda{ |params| params.join(", ") }
+        
+    # require that all of :required parameters are specified
+    unless required.empty? 
+      k = required & keys
+      raise ArgumentError, \
+        "#{name} requires the following parameters: #{list[required - k]}" \
+        unless k == required
+    end
     
-    unless spec[:required].empty? 
-      k = spec[:required] & keys
+    # require that one (and only one) of :oneof parameters is specified
+    unless oneof.empty?
+      k = oneof & keys
+      raise ArgumentError, \
+        "#{name} requires at least one of the following parameters: #{list[oneof]}" \
+        if k.empty?
       raise ArgumentError, \
-        "#{name} requires arguments for parameters: #{list[spec[:required] - k]}" \
-        unless k == spec[:required]
+        "#{name} may specify only one of the following parameters: #{list[oneof]}" \
+        if k.length > 1
     end
     
+    # enforce that only declared parameters (:required, :optional, and :oneof)
+    # may be specified
     k = keys - allowed    
     raise ArgumentError, \
       "Unrecognized parameter specified on call to #{name}: #{list[k]}" \
@@ -64,28 +79,74 @@ module NamedParameters
   end
   
   module ClassMethods
-    protected
     # 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.
+    # 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
+    #     has_named_parameters :point, :required => [ :x, :y ], :optional => :color
     #
-    # @param [Symbol] `method` the name of the method that is supposed to 
+    # @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. 
+    # @param [Hash] spec a `Hash` to specify the list of required and optional 
+    #   parameters for the method. Use either the `:required`, `:optional`, or
+    #   `:oneof` key to specify the lists of parameters. The list is expected 
+    #   to be an `Array` of symbols matching the names of the expected and 
+    #   optional parameters.
     #
-    # @return [Hash] the specified `spec` 
+    #   Parameters are evaluated according their classification:
+    #
+    #   * `:required` means that all of these parameters must be specified.
+    #   * `: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 = { }
+      # ensure spec entries are initialized and the proper types
+      [ :required, :optional, :oneof ].each{ |k| spec[k] ||= [] }
+      spec = Hash[ spec.map{ |k, v| 
+        v = [ v ] unless v.instance_of? Array
+        v.map!{ |entry| entry.instance_of?(Array) ? Hash[*entry] : entry }
+        [ k, v ]
+      } ]
       specs[method] = spec
     end
     
+    protected
+    # Attach a validation block for a specific parameter that will be invoked 
+    # before the actual `method` call.
+    #
+    # @param [Symbol] method the name of the method.
+    #
+    # @param [Symbol] param the name of the parameter whose value is to be
+    #   validated.
+    #
+    # @param [lambda, Proc] &block the chunk of code that will perform the 
+    #   actual validation. It is expected to raise an error or return false
+    #   if the validation fails. It receives argument for `param` on 
+    #   invocation.
+    # 
+    #   If `&block` is not specified then it assumes that an implicit 
+    #   validation method is defined. It calculates the name of this method
+    #   by concatenating the values supplied for `method` and `param`, 
+    #   suffixed with the word `validation`, eg:
+    #
+    #     validates_arguments_for :request, :timeout
+    #     def request, opts = { }
+    #       ...
+    #     end
+    #    
+    #     private
+    #     def request_timeout_validation value
+    #       ...
+    #     end
+    #
+    def validates_arguments method, param, &block
+      # TODO: IMPLEMENT
+    end
+    
     # add instrumentation for class methods
     def singleton_method_added name  # :nodoc:
       instrument name do
@@ -122,10 +183,27 @@ module NamedParameters
     
     # insert parameter validation prior to executing the instrumented method
     def intercept method, owner, name, spec  # :nodoc:
+      fullname = "#{owner}#{name}"
       define_method name do |*args, &block|
-        params   = args.find{ |arg| arg.instance_of? Hash }
-        fullname = "#{owner}#{name}"
-        NamedParameters::validate fullname, params || {}, spec
+        # 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?
+
+        # merge the declared default values for params into the arguments
+        # used when the method is invoked
+        defaults = { }
+        spec.each do |k, v|
+          v.each{ |entry| defaults.merge! entry if entry.instance_of? Hash }
+        end
+        params = defaults.merge params
+        
+        # validate the parameters against the spec
+        NamedParameters::validate_specs fullname, params, spec
+        
+        # inject the updated argument values for params into the arguments
+        # before actually making method invocation
+        args.map!{ |arg| arg.instance_of?(Hash) ? params : arg }
         method.bind(self).call(*args, &block)
       end
     end

data/lib/named-parameters/object.rb

@@ -1,3 +1,7 @@
-# Extend object to automatically make it available for all
-# user defined classes...
-Object.extend NamedParameters::ClassMethods
+# Do the eigenclass thingy
+class Object
+  protected
+  def eigenclass # :nodoc:
+    class << self; self; end  
+  end  
+end

data/named-parameters.gemspec

@@ -5,12 +5,21 @@
 
 Gem::Specification.new do |s|
   s.name = %q{named-parameters}
-  s.version = "0.0.5"
+  s.version = "0.0.6"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Juris Galang"]
-  s.date = %q{2010-11-11}
-  s.description = %q{This gem enables/simulates named-parameters in Ruby}
+  s.date = %q{2010-11-13}
+  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. 
+
+    It does this by extending the language with a `has_named_parameters` clause 
+    that allows a class to declare the parameters that are acceptable to a method.
+
+    The `has_named_parameters` dictates how the presence of these parameters are
+    enforced and raises an `ArgumentError` when a method invocation is made that
+    violates the rules for those parameters.
+    }
   s.email = %q{jurisgalang@gmail.com}
   s.extra_rdoc_files = [
     "README.md"

data/spec/named-parameters_spec.rb

@@ -2,45 +2,174 @@ require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
 describe "NamedParameters" do
   before :all do
-    class FooBar
+    class Foo
       has_named_parameters :initialize, :required => :x, :optional => [ :y, :z ]
-      def initialize(opts = {}); end
+      def initialize opts = {}; end
       
       has_named_parameters :method_one, :required => :x, :optional => [ :y, :z ]
-      def method_one(x, y, opts = {}); end
+      def method_one x, y, opts = {}; end
 
-      def method_two(x, y, opts = {}); end
+      def method_two x, y, opts = {}; end
+      
+      has_named_parameters :method_three, :required => :x, :optional => [ :y, :z ]
+      def self.method_three x, y, opts = {}; end
+
+      def self.method_four x, y, opts = {}; end
+    end
+
+    class Bar
+      has_named_parameters :method_with_one_required, :required => :x
+      def method_with_one_required opts = {}; end
+      
+      has_named_parameters :method_with_many_required, :required => [ :x, :y ]
+      def method_with_many_required opts = {}; end
+      
+      has_named_parameters :method_with_one_oneof, :oneof => :x
+      def method_with_one_oneof opts = {}; end
+      
+      has_named_parameters :method_with_many_oneof, :oneof => [ :x, :y ]
+      def method_with_many_oneof opts = {}; end
+      
+      has_named_parameters :method_with_one_optional, :optional => :x
+      def method_with_one_optional opts = {}; end
+      
+      has_named_parameters :method_with_many_optional, :optional => [ :x, :y ]
+      def method_with_many_optional opts = {}; end
+
+      has_named_parameters :method_with_one_of_each_requirement, :required => :w, :oneof => [ :x, :y ], :optional => :z
+      def method_with_one_of_each_requirement opts = {}; end
     end
   end
   
   it "should allow declaration of has_named_parameters" do
-    FooBar.should respond_to :has_named_parameters
+    Foo.should respond_to :has_named_parameters
   end
   
   it "should enforce named parameters for constructor" do
-    lambda{ FooBar.new }.should raise_error ArgumentError
-    lambda{ FooBar.new :w => :w }.should raise_error ArgumentError
-    lambda{ FooBar.new :x => :x }.should_not raise_error
-    lambda{ FooBar.new :x => :x, :y => :y }.should_not raise_error
-    lambda{ FooBar.new :x => :x, :y => :y, :z => :z }.should_not raise_error
-  end
-
-  it "should enforce named parameters for instrumented methods" do
-    lambda{ @foobar = FooBar.new :x => :x, :y => :y, :z => :z }.should_not raise_error
-    lambda{ @foobar.method_one :x }.should raise_error ArgumentError
-    lambda{ @foobar.method_one :x, :y }.should raise_error ArgumentError
-    lambda{ @foobar.method_one :x, :y, :x => :x, :y => :y, :z => :z, :w => :w }.should raise_error ArgumentError
-    lambda{ @foobar.method_one :x => :x, :y => :y, :z => :z }.should raise_error ArgumentError
-    lambda{ @foobar.method_one :x, :y, :w => :w }.should raise_error ArgumentError
-    lambda{ @foobar.method_one :x, :y, :x => :x }.should_not raise_error
-    lambda{ @foobar.method_one :x, :y, :x => :x, :y => :y }.should_not raise_error
-    lambda{ @foobar.method_one :x, :y, :x => :x, :y => :y, :z => :z }.should_not raise_error
-  end
-
-  it "should not enforce named parameters for un-instrumented methods" do
-    lambda{ @foobar = FooBar.new :x => :x, :y => :y, :z => :z }.should_not raise_error
-    lambda{ @foobar.method_two :x }.should raise_error ArgumentError
-    lambda{ @foobar.method_two :x, :y }.should_not raise_error ArgumentError
-    lambda{ @foobar.method_two :x, :y, :w => :w }.should_not raise_error ArgumentError
+    lambda{ Foo.new }.should raise_error ArgumentError
+    lambda{ Foo.new :w => :w }.should raise_error ArgumentError
+    lambda{ Foo.new :x => :x }.should_not raise_error
+    lambda{ Foo.new :x => :x, :y => :y }.should_not raise_error
+    lambda{ Foo.new :x => :x, :y => :y, :z => :z }.should_not raise_error
+  end
+
+  it "should enforce named parameters for instrumented instance methods" do
+    lambda{ @foo = Foo.new :x => :x, :y => :y, :z => :z }.should_not raise_error
+    lambda{ @foo.method_one :x }.should raise_error ArgumentError
+    lambda{ @foo.method_one :x, :y }.should raise_error ArgumentError
+    lambda{ @foo.method_one :x, :y, :x => :x, :y => :y, :z => :z, :w => :w }.should raise_error ArgumentError
+    lambda{ @foo.method_one :x => :x, :y => :y, :z => :z }.should raise_error ArgumentError
+    lambda{ @foo.method_one :x, :y, :w => :w }.should raise_error ArgumentError
+    lambda{ @foo.method_one :x, :y, :x => :x }.should_not raise_error
+    lambda{ @foo.method_one :x, :y, :x => :x, :y => :y }.should_not raise_error
+    lambda{ @foo.method_one :x, :y, :x => :x, :y => :y, :z => :z }.should_not raise_error
+  end
+
+  it "should not enforce named parameters for un-instrumented instance methods" do
+    lambda{ @foo = Foo.new :x => :x, :y => :y, :z => :z }.should_not raise_error
+    lambda{ @foo.method_two :x }.should raise_error ArgumentError
+    lambda{ @foo.method_two :x, :y }.should_not raise_error ArgumentError
+    lambda{ @foo.method_two :x, :y, :w => :w }.should_not raise_error ArgumentError
+  end
+
+  it "should enforce named parameters for instrumented class methods" do
+    lambda{ Foo.method_three :x }.should raise_error ArgumentError
+    lambda{ Foo.method_three :x, :y }.should raise_error ArgumentError
+    lambda{ Foo.method_three :x, :y, :x => :x, :y => :y, :z => :z, :w => :w }.should raise_error ArgumentError
+    lambda{ Foo.method_three :x => :x, :y => :y, :z => :z }.should raise_error ArgumentError
+    lambda{ Foo.method_three :x, :y, :w => :w }.should raise_error ArgumentError
+    lambda{ Foo.method_three :x, :y, :x => :x }.should_not raise_error
+    lambda{ Foo.method_three :x, :y, :x => :x, :y => :y }.should_not raise_error
+    lambda{ Foo.method_three :x, :y, :x => :x, :y => :y, :z => :z }.should_not raise_error
+  end
+
+  it "should not enforce named parameters for un-instrumented class methods" do
+    lambda{ Foo.method_four :x }.should raise_error ArgumentError
+    lambda{ Foo.method_four :x, :y }.should_not raise_error ArgumentError
+    lambda{ Foo.method_four :x, :y, :w => :w }.should_not raise_error ArgumentError
+  end
+  
+  it "should require all :required parameters" do
+    bar = Bar.new
+    lambda{ bar.method_with_one_required }.should raise_error ArgumentError
+    lambda{ bar.method_with_one_required :a => :a }.should raise_error ArgumentError
+    lambda{ bar.method_with_one_required :x => :x }.should_not raise_error
+            
+    lambda{ bar.method_with_many_required }.should raise_error ArgumentError
+    lambda{ bar.method_with_many_required :x => :x }.should raise_error ArgumentError
+    lambda{ bar.method_with_many_required :x => :x, :y => :y }.should_not raise_error
+  end
+  
+  it "should require one and only one of :oneof parameters" do
+    bar = Bar.new
+    lambda{ bar.method_with_one_oneof }.should raise_error ArgumentError
+    lambda{ bar.method_with_one_oneof :a => :a }.should raise_error ArgumentError
+    lambda{ bar.method_with_one_oneof :x => :x }.should_not raise_error
+            
+    lambda{ bar.method_with_many_oneof }.should raise_error ArgumentError
+    lambda{ bar.method_with_many_oneof :a => :a }.should raise_error ArgumentError
+    lambda{ bar.method_with_many_oneof :x => :x }.should_not raise_error
+    lambda{ bar.method_with_many_oneof :y => :y }.should_not raise_error
+    lambda{ bar.method_with_many_oneof :x => :x, :y => :y }.should raise_error ArgumentError
+  end
+  
+  it "should reject parameters not declared in :required, :optional, or :oneof" do
+    bar = Bar.new
+    lambda{ bar.method_with_one_optional }.should_not raise_error
+    lambda{ bar.method_with_one_optional :x => :x }.should_not raise_error
+    lambda{ bar.method_with_one_optional :a => :a }.should raise_error ArgumentError
+    lambda{ bar.method_with_one_optional :x => :x, :y => :y }.should raise_error ArgumentError
+            
+    lambda{ bar.method_with_many_optional }.should_not raise_error
+    lambda{ bar.method_with_many_optional :x => :x }.should_not raise_error
+    lambda{ bar.method_with_many_optional :y => :y }.should_not raise_error
+    lambda{ bar.method_with_many_optional :x => :x, :y => :y }.should_not raise_error
+    lambda{ bar.method_with_many_optional :x => :x, :y => :y, :z => :z }.should raise_error ArgumentError
+            
+    lambda{ bar.method_with_one_of_each_requirement }.should raise_error ArgumentError
+    lambda{ bar.method_with_one_of_each_requirement :w => :w }.should raise_error ArgumentError
+    lambda{ bar.method_with_one_of_each_requirement :w => :w, :x => :x }.should_not raise_error
+    lambda{ bar.method_with_one_of_each_requirement :w => :w, :y => :y }.should_not raise_error
+    lambda{ bar.method_with_one_of_each_requirement :w => :w, :x => :x, :y => :y }.should raise_error ArgumentError
+    lambda{ bar.method_with_one_of_each_requirement :w => :w, :x => :x, :z => :z }.should_not raise_error
+    lambda{ bar.method_with_one_of_each_requirement :w => :w, :y => :y, :z => :z }.should_not raise_error
+    lambda{ bar.method_with_one_of_each_requirement :w => :w, :x => :x, :z => :z, :a => :a }.should raise_error ArgumentError
+  end
+
+  it "should be able to supply the default values for optional parameters" do
+    class Zoo
+      has_named_parameters :method_with_one_optional_parameter, :optional => { :x => 1 }
+      def method_with_one_optional_parameter opts = { }; opts[:x]; end
+
+      has_named_parameters :method_with_many_optional_parameters, :optional => [ [ :x, 1 ], [ :y, 2 ] ]
+      def method_with_many_optional_parameters opts = { }; opts[:x] + opts[:y]; end
+
+      has_named_parameters :method_with_many_optional_parameters_too, :optional => [ { :x => 1 }, { :y => 2 } ]
+      def method_with_many_optional_parameters_too opts = { }; opts[:x] + opts[:y]; end
+    end
+    
+    zoo = Zoo.new
+    zoo.method_with_one_optional_parameter.should eql 1
+    zoo.method_with_one_optional_parameter(:x => 2).should eql 2
+
+    zoo.method_with_many_optional_parameters.should eql 3
+    zoo.method_with_many_optional_parameters(:x => 2).should eql 4
+    zoo.method_with_many_optional_parameters(:x => 2, :y => 3).should eql 5
+
+    zoo.method_with_many_optional_parameters_too.should eql 3
+    zoo.method_with_many_optional_parameters_too(:x => 2).should eql 4
+    zoo.method_with_many_optional_parameters_too(:x => 2, :y => 3).should eql 5
+  end
+  
+  it "should be able to instrument the class method new" do
+    class Quux
+      has_named_parameters :new, :required => :x
+      def self.new opts = { }; end
+      def initialize opts = { }; end
+    end
+    lambda { Quux.new }.should raise_error ArgumentError
+    lambda { Quux.new :y => :y }.should raise_error ArgumentError
+    lambda { Quux.new :x => :x, :y => :y }.should raise_error ArgumentError
+    lambda { Quux.new :x => :x }.should_not raise_error
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: named-parameters
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 19
   prerelease: false
   segments: 
   - 0
   - 0
-  - 5
-  version: 0.0.5
+  - 6
+  version: 0.0.6
 platform: ruby
 authors: 
 - Juris Galang
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-11 00:00:00 -08:00
+date: 2010-11-13 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -48,7 +48,7 @@ dependencies:
         version: "0"
   type: :development
   version_requirements: *id002
-description: This gem enables/simulates named-parameters in Ruby
+description: "This gem simulates named-parameters in Ruby. It's a complement to the common \n    Ruby idiom of using `Hash` args to emulate the use of named parameters. \n\n    It does this by extending the language with a `has_named_parameters` clause \n    that allows a class to declare the parameters that are acceptable to a method.\n\n    The `has_named_parameters` dictates how the presence of these parameters are\n    enforced and raises an `ArgumentError` when a method invocation is made that\n    violates the rules for those parameters.\n    "
 email: jurisgalang@gmail.com
 executables: []