named-parameters 0.0.7 → 0.0.8

data/README.md

@@ -1,15 +1,7 @@
 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.
-
-See: the [Named Parameter](http://en.wikipedia.org/wiki/named_parameter) 
-article from Wikipedia for more information.
+Related: [Named Parameters in Ruby](http://www.jurisgalang.com/2010/11/09/named-parameters-in-ruby/)
 
 Get It
 ------
@@ -95,7 +87,7 @@ And is applicable to both class and instance methods:
         # ... do send mail stuff here ...
       end
       
-      has_named_parameters :archive, :optional => [ :method => 'zip' ]
+      has_named_parameters :'self.archive', :optional => [ :method => 'zip' ]
       def self.archive options = { }
         # ... do mail archiving stuff here ...
       end
@@ -104,23 +96,25 @@ And is applicable to both class and instance methods:
 Shortcuts
 ---------
 In addition to the `has_named_parameters` method, `NamedParameters` also comes
-with two convenience methods for applying a parameter spec for constructors:
+with two convenience methods for implicitly applying parameter specs for 
+constructors.
 
-Use the **`requires`** clause to declare what parameters a class expects when it
+Use the `requires` clause to declare what parameters a class expects when it
 is instantiated:
 
     class GoogleStorage
-      requires [ :'access-key', :'secret-key' ]
+      requires :'access-key', :'secret-key'
       
       def initialize options
         # ... do googly stuff here ...
       end
     end
 
-Use the **`recognizes`** clause to specify optional parameters for constructors:
+Use the `recognizes` clause to specify the optional parameters for a class
+when it is instantiated:
 
     class GoogleStorage
-      recognizes [ :'group-email', :'apps-domain' ]
+      recognizes :'group-email', :'apps-domain'
       
       def initialize options
         # ... do googly stuff here ...
@@ -130,14 +124,22 @@ Use the **`recognizes`** clause to specify optional parameters for constructors:
 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' ] ]
+      requires   :'access-key', :'secret-key'
+      recognizes [ :'group-email', 'group@example.org' ], [ :'apps-domain', 'example.org' ]
 
       def initialize options
         # ... do googly stuff here ...
       end
     end
 
+The `requires` and `recognizes` clause is equivalent to declaring the lines
+in a class definition:
+
+    has_named_parameters :'self.new', :required => params, :strict
+    has_named_parameters :initialize, :required => params, :strict
+    has_named_parameters :'self.new', :optional => params, :strict
+    has_named_parameters :initialize, :optional => params, :strict
+
 Permissive Mode
 ---------------
 When a method is declared with `has_named_parameters` that method will only 
@@ -173,15 +175,15 @@ The `:required` and `:oneof` parameters will still be expected:
 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:
+However, the `requires` and `recognizes` clauses does not accept the `mode` argument. 
+If you need to make a constructor's optional parameter spec permissive, use
+the `has_named_parameters` clause instead:
 
-    requires   [ :x ], :permissive
-    recognizes [ :y, :z ], :permissive
+    has_named_parameters :'self.new', :required => params, :permissive
+    has_named_parameters :initialize, :required => params, :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.
+For brevity, since the mode is `:permissive`, the `:optional` parameters list 
+is skipped.
 
 How It Works
 ------------
@@ -246,6 +248,69 @@ For the above case, it might be better to refactor:
 
     # result:
     # => path: /xxx, options: {}
+    
+Class vs Instance Methods
+-------------------------
+Parameter spec declarations are not shared between class and instance 
+methods even if they share the same name. 
+
+For example, the following `has_named_parameters` declaration below is only 
+applicable to the instance method `exec`:
+
+    class Command
+      has_named_parameters :exec, :required => :x
+      def self.exec opts
+        # ...
+      end
+
+      def exec opts
+        # ...
+      end
+    end
+
+    # the following will *not* raise an ArgumentError because
+    # the has_named_parameter declaration applies only to the
+    # instance method exec...
+    Command.exec      
+
+    # the following will raise an ArgumentError (as expected)
+    command = Command.new
+    command.exec  
+
+Prefix the method name with `self.` to apply parameter spec for class methods:
+
+    class Command
+      has_named_parameters :'self.exec', :required => :x
+      def self.exec opts
+        # ...
+      end
+    end
+
+    # the following will now raise an ArgumentError (as expected)
+    Command.exec
+
+In general, however, when a class has an instance and a class method using
+the same name, for most cases, one simply delegates to another and will share 
+the same requirements. So the examples cited above can be refactored:
+
+    class Command
+      has_named_parameters :'self.exec', :required => :x
+      def self.exec opts
+        # ...
+      end
+
+      def exec opts
+        Command.exec
+      end
+    end
+
+    # the following will raise an ArgumentError (as expected)
+    Command.exec
+
+    # the following will also raise an ArgumentError as it delegates to the 
+    # class method and violates the parameter requirements
+    command = Command.new
+    command.exec  
 
 Dependencies
 ------------

data/RELEASENOTES

@@ -1,3 +1,11 @@
+0.0.8 [Nov 22, 2010]
+- [INTERNAL] Parameter spec will no longer be shared between singleton and 
+  instance methods. Bonus performance improvement: it no longer needs to keep
+  track of the parameter specs after the class is declared.
+- [INTERNAL] The mode argument is no longer entertained by the requires and 
+  recognizes clause. Use the has_named_parameters clause on constructors if 
+  permissive behavior is required on optional parameters.
+
 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:

data/VERSION

@@ -1 +1 @@
-0.0.7
+0.0.8

data/lib/named-parameters/module.rb

@@ -122,45 +122,35 @@ module NamedParameters
     
     # Convenience method, equivalent to declaring:
     #
-    #     has_named_parameters :'self.new', :required => params
-    #     has_named_parameters :initialize, :required => params
+    #     has_named_parameters :'self.new', :required => params, :strict
+    #     has_named_parameters :initialize, :required => params, :strict
     # 
     # @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|
+    def requires *params
+      [ :'self.new', :initialize ].each do |method|
         spec = specs[key_for method] || { }
         spec.merge!(:required => params)
-        has_named_parameters method, spec, mode
+        has_named_parameters method, spec, :strict
       end
     end
     
     # Convenience method, equivalent to declaring:
     #
-    #     has_named_parameters :'self.new', :optional => params
-    #     has_named_parameters :initialize, :optional => params
+    #     has_named_parameters :'self.new', :optional => params, :strict
+    #     has_named_parameters :initialize, :optional => params, :strict
     # 
     # @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|
+    def recognizes *params
+      [ :'self.new', :initialize ].each do |method|
         spec = specs[key_for method] || { }
         spec.merge!(:optional => params)
-        has_named_parameters method, spec, mode
+        has_named_parameters method, spec, :strict
       end
     end
     
@@ -193,15 +183,15 @@ module NamedParameters
     #       ...
     #     end
     #
-    def validates_arguments method, param, &block
-      # TODO: IMPLEMENT
-    end
+    #def validates_arguments method, param, &block
+    #  # TODO: IMPLEMENT
+    #end
     
     # add instrumentation for class methods
     def singleton_method_added name  # :nodoc:
-      instrument name do
+      instrument :"self.#{name}" do
         method = self.eigenclass.instance_method name
-        spec   = specs[key_for :"self.#{name}"] || specs[key_for name]
+        spec   = specs.delete(key_for :"self.#{name}") 
         owner  = "#{self.name}::"
         eigenclass.instance_eval do
           intercept method, owner, name, spec
@@ -214,7 +204,7 @@ module NamedParameters
     def method_added name  # :nodoc:
       instrument name do
         method = instance_method name
-        spec   = specs[key_for name] || specs[key_for :"self.#{name}"]
+        spec   = specs.delete(key_for name)
         owner  = "#{self.name}#"
         intercept method, owner, name, spec
       end

data/named-parameters.gemspec

@@ -1,15 +1,15 @@
 # Generated by jeweler
 # DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
   s.name = %q{named-parameters}
-  s.version = "0.0.7"
+  s.version = "0.0.8"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Juris Galang"]
-  s.date = %q{2010-11-18}
+  s.date = %q{2010-11-22}
   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. 
 
@@ -26,29 +26,27 @@ Gem::Specification.new do |s|
   ]
   s.files = [
     ".document",
-     ".gitignore",
-     "GPL-LICENSE",
-     "MIT-LICENSE",
-     "README.md",
-     "RELEASENOTES",
-     "Rakefile",
-     "VERSION",
-     "lib/named-parameters.rb",
-     "lib/named-parameters/module.rb",
-     "lib/named-parameters/object.rb",
-     "named-parameters.gemspec",
-     "spec/named-parameters_spec.rb",
-     "spec/spec.opts",
-     "spec/spec_helper.rb"
+    "GPL-LICENSE",
+    "MIT-LICENSE",
+    "README.md",
+    "RELEASENOTES",
+    "Rakefile",
+    "VERSION",
+    "lib/named-parameters.rb",
+    "lib/named-parameters/module.rb",
+    "lib/named-parameters/object.rb",
+    "named-parameters.gemspec",
+    "spec/named-parameters_spec.rb",
+    "spec/spec.opts",
+    "spec/spec_helper.rb"
   ]
   s.homepage = %q{http://github.com/jurisgalang/named-parameters}
-  s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
   s.rubygems_version = %q{1.3.7}
   s.summary = %q{Poor man's named-parameters in Ruby}
   s.test_files = [
     "spec/named-parameters_spec.rb",
-     "spec/spec_helper.rb"
+    "spec/spec_helper.rb"
   ]
 
   if s.respond_to? :specification_version then

data/spec/named-parameters_spec.rb

@@ -1,17 +1,20 @@
 require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
+# TODO: reorganize the tests for clarity
+# TODO: need separate spec for the NamedParameters.validate_specs method
+# TODO: factor out specs for required, recognizes, and has_named_parameters
 describe "NamedParameters" do
   before :all 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
-
+      
       def method_two x, y, opts = {}; end
       
-      has_named_parameters :method_three, :required => :x, :optional => [ :y, :z ]
+      has_named_parameters :'self.method_three', :required => :x, :optional => [ :y, :z ]
       def self.method_three x, y, opts = {}; end
 
       def self.method_four x, y, opts = {}; end
@@ -35,7 +38,7 @@ describe "NamedParameters" do
       
       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
@@ -52,7 +55,7 @@ describe "NamedParameters" do
     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
@@ -64,7 +67,7 @@ describe "NamedParameters" do
     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
@@ -135,15 +138,15 @@ describe "NamedParameters" do
     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
@@ -151,11 +154,11 @@ describe "NamedParameters" do
     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
@@ -163,8 +166,10 @@ describe "NamedParameters" do
   
   it "should be able to instrument the class method new" do
     class Quux
-      has_named_parameters :new, :required => :x
-      def self.new opts = { }; end
+      has_named_parameters :'self.new', :required => :x
+      class << self
+        def new opts = { }; end
+      end
       def initialize opts = { }; end
     end
     lambda { Quux.new }.should raise_error ArgumentError
@@ -175,7 +180,7 @@ describe "NamedParameters" do
   
   it "should be able to specify optional parameters using the recognizes method" do
     class Recognizes
-      recognizes [ :x, :y ]
+      recognizes :x, :y
       def self.new opts = { }; end
       def initialize opts = { }; end
     end
@@ -185,10 +190,10 @@ describe "NamedParameters" do
     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 ]
+      requires :x, :y
       def self.new opts = { }; end
       def initialize opts = { }; end
     end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: named-parameters
 version: !ruby/object:Gem::Version 
-  hash: 17
+  hash: 15
   prerelease: false
   segments: 
   - 0
   - 0
-  - 7
-  version: 0.0.7
+  - 8
+  version: 0.0.8
 platform: ruby
 authors: 
 - Juris Galang
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-18 00:00:00 -08:00
+date: 2010-11-22 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -58,7 +58,6 @@ extra_rdoc_files:
 - README.md
 files: 
 - .document
-- .gitignore
 - GPL-LICENSE
 - MIT-LICENSE
 - README.md
@@ -77,8 +76,8 @@ homepage: http://github.com/jurisgalang/named-parameters
 licenses: []
 
 post_install_message: 
-rdoc_options: 
-- --charset=UTF-8
+rdoc_options: []
+
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 

data/.gitignore

@@ -1,21 +0,0 @@
-## MAC OS
-.DS_Store
-
-## TEXTMATE
-*.tmproj
-tmtags
-
-## EMACS
-*~
-\#*
-.\#*
-
-## VIM
-*.swp
-
-## PROJECT::GENERAL
-coverage
-rdoc
-pkg
-
-## PROJECT::SPECIFIC