named-parameters 0.0.11 → 0.0.12

data/README.md

@@ -164,6 +164,34 @@ method:
 `declared_parameters` is also available from the class methods of user defined
 classes.
 
+Filtering Arguments
+-------------------
+Sometimes you'll have a `Hash` object that will have a bunch of keys that may 
+or may not comply to the parameter declaration of a method, but you may to use 
+the same object everywhere without having to figure out what keys are 
+applicable to a method call:
+
+    options = { :x => 1, :y => :z, :a => 'somevalue' }
+
+    has_named_parameters :foo, :required => [ :x ]
+    def foo options = { }
+      options.inspect
+    end
+
+    has_named_parameters :bar, :required => [ :y ], :optional => [ :a ]
+    def bar options = { }
+      options.inspect
+    end
+    
+    foo options   # => ArgumentError! :y and :a not recognized
+    bar options   # => ArgumentError! :x not recognized
+    
+Use the `filter_parameters` method against the options object to make it 
+comply to the declaration:
+
+    foo filter_parameters(options)   # => [ :x ]
+    bar filter_parameters(options)   # => [ :a, :y ]
+
 Permissive Mode
 ---------------
 When a method is declared with `has_named_parameters` that method will only 

data/RELEASENOTES

@@ -1,3 +1,6 @@
+0.0.12 [Nov 25, 2010]
+- [FEATURE] Added apply_filters method.
+
 0.0.11 [Nov 24, 2010]
 - [BUGFIX] declared_parameters returns nil if called from an uninstrumented
   method; it will now return an empty Array.

data/VERSION

@@ -1 +1 @@
-0.0.11
+0.0.12

data/lib/named-parameters/module.rb

@@ -33,14 +33,15 @@ module NamedParameters
   # declared in the the `has_named_parameters` clause, or the list specified 
   # in either the `requires` and `recognizes` clause.
   #
-  # @returns [Array] list of symbols representing the name of the declared 
+  # @return [Array<Symbol>] the list of symbols representing the name of the declared 
   #   parameters.
   #
   def declared_parameters
     klazz  = self.instance_of?(Class) ? self : self.class
     specs  = klazz.send :specs
     
-    method = self.instance_of?(Class) ? :"self.#{calling_method}" : calling_method
+    caller = block_given? ? yield : calling_method # insane-fucker! :-)
+    method = self.instance_of?(Class) ? :"self.#{caller}" : caller
     spec   = specs[klazz.send(:key_for, method)]
     return [] if spec.nil?
 
@@ -50,13 +51,44 @@ module NamedParameters
     [ :required, :optional, :oneof ].map{ |k| spec[k].map(&mapper) }.flatten.sort(&sorter)
   end
   
+  # Filter out keys from `options` that are not declared as parameter to the
+  # method:
+  #   
+  #     has_named_parameters :foo, :requires => :x
+  #     def foo options = { }
+  #       options.inspect
+  #     end
+  #
+  #     options = { :x => 1, :y => 2, :z => 3 } 
+  #     
+  #     # the following will fail because :y and :z is not recognized/declared
+  #     foo options   # => ArgumentError! 
+  #
+  #     # the following will not fail because we've applied the filter
+  #     foo filter_parameters(options)   # => [ :x ]
+  #
+  # @param [Hash] options the options argument to the method.
+  #
+  # @param [Array<Symbol>] the list of symbols representing the declared
+  #   parameters used to filter `options`. Optional, the list returned by
+  #   `declared_parameters` is used by default.
+  #
+  # @return [Hash] a `Hash` whose keys are limited to what's declared as
+  #   as parameter to the method.
+  #
+  def filter_parameters options, filter = nil
+    caller = calling_method
+    filter ||= declared_parameters{ caller } 
+    options.reject{ |key, value| !filter.include?(key) }
+  end
+    
   # returns the name of the current method
-  def current_method
+  def current_method # :nodoc:
     caller[0][/`([^']*)'/, 1].to_sym
   end
 
   # returns the name of the calling method
-  def calling_method
+  def calling_method # :nodoc:
     caller[1][/`([^']*)'/, 1].to_sym
   end
     
@@ -157,7 +189,7 @@ module NamedParameters
     #     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 
+    # @param [Array<Symbol>] params the lists of parameters. The list is expected 
     #   to be an `Array` of symbols matching the names of the required 
     #   parameters.
     #
@@ -174,7 +206,7 @@ module NamedParameters
     #     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 
+    # @param [Array<Symbol>] params the lists of parameters. The list is expected 
     #   to be an `Array` of symbols matching the names of the optional
     #   parameters.
     #

data/named-parameters.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{named-parameters}
-  s.version = "0.0.11"
+  s.version = "0.0.12"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Juris Galang"]
-  s.date = %q{2010-11-24}
+  s.date = %q{2010-11-25}
   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

@@ -226,4 +226,24 @@ describe "NamedParameters" do
     o.parameters.should eql [ :a, :b, :c, :x, :y ]
     DeclaredParameters.singleton(:w => :w, :a => :a).should eql [ :a, :b, :c, :w, :x, :y, :z ]
   end
+
+  it "should not return nil when declared_parameters is called on uninstrumented method" do
+    class DeclaredParameters
+      has_named_parameters :'self.boogey', 
+        :required => [ :w ], 
+        :optional => [ :x, [ :y, 1 ], { :z => 1 } ],
+        :oneof    => [ :a, :b, :c ]
+      def self.boogey opts = { }
+        declared_parameters
+      end
+      
+      def boogey
+        declared_parameters
+      end
+    end
+    
+    o = DeclaredParameters.new(:x => :x, :y => :y)
+    o.boogey.should eql []
+    DeclaredParameters.boogey(:w => :w, :a => :a).should eql [ :a, :b, :c, :w, :x, :y, :z ]
+  end
 end

metadata

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