named_parameters 0.1.4 → 1.0.0

data/README

@@ -6,8 +6,6 @@ Surprisingly it is this easy:
 
     gem install named_parameters
 
----
-
 == Use it
 === First, include NamedParameters:
     class AnyClass
@@ -58,7 +56,7 @@ The call is just the same:
 
 == Optional and mandatory parameters
 You can have both optional and mandatory parameters for the same method.
-All paramaters with no default value are mandatory:
+All parameters with no default value are mandatory:
 
     class AnyClass
         named_parameters(a: "default a")
@@ -85,8 +83,52 @@ Blocks are not interfered by named_parameters. You can just use them as usual.
 
     any_object.some_method(a: %w(hello world)) {|s| s.upcase!} # => ["HELLO", "WORLD"]
 
+== Strict mode
+Strict mode means, that keys in the named parameters hash, that are not part of the parameter definition of your
+method, will raise a RuntimeError. You can use it like this:
+    class AnyClass
+        named_parameters_strict(a: "default a")
+        def some_method(a)
+            a
+        end
+    end
 
----
+    any_object.some_method(a: "given",
+                           b: "more parameters") # => Error 'Parameter "b" is not accepted by method "some_method"'
+
+== Super mode
+Super mode means, that the super method will be called, with the named parameter hash as only parameter. This can be
+useful if some library, that makes use of named parameters, demands you to call super. Remember you cannot access the
+actual named parameters hash. Use the super mode like this:
+
+    class SomeLibraryClass
+        def setup(options)
+            #manual options parsing here
+            options
+        end
+    end
+
+    class AnyClass
+        named_parameters_super
+        def setup(a,b,c)
+            #do something with a, b and c
+        end
+    end
+
+    any_object.setup(a: "a",
+                     b: "b",
+                     c: "c",
+                     d: "d") # => {:a => "a", :b => "b", :c => "c", :d => "d"}
+
+== Combine super and strict
+In case you need to combine super and strict mode, do:
+
+    class AnyClass < SomeLibraryClass
+        named_parameters_strict_super # or named_parmeters_super_strict
+        def some_method(a,b,c)
+            # do something with a and b, maybe something with c will be done in super
+        end
+    end
 
 == Acknowledgements
 
@@ -94,6 +136,12 @@ Kudos to Juris Galang and his gem named-parameters. (http://www.rubygems.org/gem
 Defenitely have a look at this gem also, if you want to use named parameters.
 
 == Changelog
+[1.0.0] * Added strict and super modes
+        * Smoother implementation
+            * Better structured code
+            * More comments
+            * Proper around alias instead of rebinding the method
+        * Is not strict on default any more
 [0.1.4] * Changed visibility in documentation
 [0.1.3] * Made LICENSE visible to documentation (Sorry for that)
         * Made actual name space and NamedParameters#named_parameters macro visible to documentation

data/lib/named_parameters.rb

@@ -1,17 +1,7 @@
-module Kernel #:nodoc:
-              # @return [Class] the eigenclass / singletonclass / metaclass of self
-  def eigenclass
-    class << self
-      self
-    end
-  end
-end
-
 #
 # Include this module to enable the NamedParameters#named_parameters macro
 #
-module NamedParameters # :nodoc: all
-
+module NamedParameters
 
   # Makes all methods of this module to class or module methods of include
   def self.included base #:nodoc:
@@ -24,106 +14,112 @@ module NamedParameters # :nodoc: all
     private :method_added_before_named_parameters
   end
 
-
-  # @param defaults [Hash] Containing defaults values for optional parameters.
-  # Parameters that are not listet here are mandatory.
-  def named_parameters (defaults = { }) #:doc:
-    defaults.empty? ? all_required : some_defaults(defaults)
+  def method_added(method_name)
+    # redefine the method
+    if @redefine_next
+      @redefine_next = false
+      _redefine_with_named_parameters(method_name,
+                                      @named_parameters_optionals,
+                                      @named_parameters_strict,
+                                      @named_parameters_super)
+    end
+    # call old method_added
+    method_added_before_named_parameters method_name
   end
 
-  private
+  # Makes the next method callable via named parameters (options hash)
+  # The caller hash may contain keys that are not contained in the parameters of the next method
+  # @param [Hash[Symbol,Object]] optionals Optional default values for the parameters
+  #   Parameters, that are not
+  def named_parameters(optionals = { })
+    _named_parameters optionals, false, false
+  end
 
-  # :nodoc:
-  # [Symbol] is in [:nothing, :all_required, :defaults]
-  @@next_method_modifier = :nothing
+  # Makes the next method callable via named parameters (options hash)
+  # The caller hash may only contain keys that are in the parameters of the next method
+  # @param [Hash[Symbol,Object]] optionals Optional default values for the parameters
+  def named_parameters_strict(optionals = { })
+    _named_parameters optionals, true, false
+  end
 
-  def all_required
-    @@next_method_modifier = :all_required
+  # Makes the next method callable via named parameters (options hash) and calls super with this options hash as the
+  #   only parameter
+  # The caller hash may contain keys that are not contained in the parameters of the next method
+  # @param [Hash[Symbol,Object]] optionals Optional default values for the parameters
+  def named_parameters_super(optionals = { })
+    _named_parameters optionals, false, true
   end
 
-  def some_defaults (defaults)
-    @@next_method_modifier = :defaults
-    @@defaults             = defaults
+  # Makes the next method callable via named parameters (options hash) and calls super with this options hash as the
+  #   only parameter
+  # The caller hash may only contain keys that are in the parameters of the next method
+  # @param [Hash[Symbol,Object]] optionals Optional default values for the parameters
+  def named_parameters_strict_super(optionals = { })
+    _named_parameters optionals, true, true
   end
 
+  alias_method :named_parameters_super_strict, :named_parameters_strict_super
 
-  # @param method_name [Symbol]
-  def method_added(method_name)
-    if @@next_method_modifier == :all_required
-      @@next_method_modifier = :nothing
-      redefine_all_required_method(method_name)
-    elsif @@next_method_modifier == :defaults
-      @@next_method_modifier = :nothing
-      redefine_defaults_method(method_name, @@defaults)
-      @@defaults = nil
-    end
-    method_added_before_named_parameters method_name
+  private
 
+  # @param [Hash[Symbol,Object]] optionals Optional default values for the parameters
+  # @param [Boolean] strict Shall keys in the caller options hash, that are not in the parameter list, throw an error?
+  # @param [Boolean] call_super Shall super be called with the caller option hash as the only parameter?
+  def _named_parameters(optionals, strict, call_super)
+    # remember the preferences for the next method, that is added
+    @named_parameters_optionals = optionals
+    @named_parameters_strict    = strict
+    @named_parameters_super     = call_super
+    # make sure only one method is redefined after the named_parameters macro was called
+    @redefine_next              = true
   end
 
-  # @param method_name [Symbol]
-  # @return [Object] Not important
-  def redefine_all_required_method(method_name, &block)
-    method               = instance_method method_name
-    parameter_definition = method.parameters.collect { |_, b| b }
-    old_name             = (method_name.to_s+"_before_named_parameters").to_sym
-    alias_method old_name, method_name
-    module_eval do
-      define_method method_name do |options, &block|
-        missing = parameter_definition-(options.keys)
-        unless missing.empty?
-          raise RuntimeError.new("Missing arguments: #{missing}")
-        end
-        unexpected = options.keys - parameter_definition
-        unless unexpected.empty?
-          raise RuntimeError.new("Unexpected arguments: #{unexpected}")
-        end
-        parameters = []
-        parameter_definition.each { |parameter| parameters << options[parameter] }
-        eval <<-STRING
-        obj = self
-        method.bind(obj).call *parameters, &block
-        STRING
-      end
+  # Redefines a method so the caller can use named parameters instead of ordinary parameters
+  # @param [Symbol] method_name
+  # @param [Hash[Symbol,Object]] optionals Optional default values for the parameters
+  # @param [Boolean] strict Shall keys in the caller options hash, that are not in the parameter list, throw an error?
+  # @param [Boolean] call_super Shall super be called with the caller option hash as the only parameter?
+  def _redefine_with_named_parameters(method_name, optionals, strict, call_super)
+    # the method as defined in the class/module
+    original_method              ||= instance_method method_name
+    # names of the parameters as defined in the class/module
+    parameter_names              ||= original_method.parameters.collect { |_, b| b }
+    new_name_for_original_method ||= (method_name.to_s + '_before_named_parameters').to_sym
+
+    # "safe" original method
+    alias_method new_name_for_original_method, method_name
+
+    # redefine old method with new logic redirecting to original method
+    define_method method_name do |options = { }, &block|
+      # check parameters if strict
+      _check_for_not_needed_options options, parameter_names, method_name if strict
+      # call super if so wanted
+      super(options) if call_super
+
+      # build parameter array from options and optionals
+      parameters ||= _parameters_from_options options, optionals, parameter_names, method_name
+
+      # redirect to original method
+      send new_name_for_original_method, *parameters, &block
     end
   end
 
-  # @param method_name [Symbol]
-  # @param defaults [Hash]
-  # @return [Object] Not important
-  def redefine_defaults_method(method_name, defaults)
-    method               = instance_method method_name
-    parameter_definition = method.parameters.collect { |_, b| b }
-
-    defaults.keys.each do |default_key|
-      raise RuntimeError.new("A default value for #{default_key} has been defined,
-but it is not a parameter of #{method_name}") unless parameter_definition.include? default_key
+  # Builds the actual parameter array for the redirected call to the original method
+  def _parameters_from_options(options, optionals, parameter_names, method_name)
+    parameters ||= []
+    parameter_names.each do |name|
+      parameters << options.fetch(name) { optionals.fetch(name) { raise "Mandatory parameter #{name} is not passed to
+method #{method_name}" } }
     end
+    parameters
+  end
 
-    old_name = (method_name.to_s+"_before_named_parameters").to_sym
-    alias_method old_name, method_name
-    module_eval do
-      define_method method_name do |options = { }, &block|
-        unexpected = options.keys - parameter_definition
-        unless unexpected.empty?
-          raise RuntimeError.new("Unexpected arguments: #{unexpected}")
-        end
-
-        parameters = []
-        mandatory  = parameter_definition-(defaults.keys)
-        parameter_definition.each do |parameter|
-          if mandatory.member? parameter
-            parameters << options.fetch(parameter) { raise RuntimeError.new("Mandatory parameter #{parameter} not
-given") }
-          else
-            parameters << options.fetch(parameter, defaults[parameter])
-          end
-        end
-        eval <<-STRING
-        obj = self
-        method.bind(obj).call *parameters, &block
-        STRING
-      end
+  # Checks whether there are keys in the options, that are not in the parameter_names. Throws a user friendly
+  # RuntimeError in that case
+  def _check_for_not_needed_options(options, parameter_names, method_name)
+    options.each do |name, _|
+      raise ("Parameter '#{name}' is not accepted by '#{method_name}'") unless parameter_names.member? name
     end
   end
-end
+
+end

data/spec/named_parameters_spec.rb

@@ -1,104 +1,176 @@
-require_relative "../src/named_parameters"
+require_relative '../lib/named_parameters'
+
+
+class Item
+
+  attr_reader :id
+
+  def setup(options = { })
+    @id = options[:id]
+  end
+
+  def setup_only_valid_attributes(options = { })
+    @id = options[:id]
+  end
+
+end
+
+
+class Book < Item
 
-class Book
   include NamedParameters
 
-  attr_reader :author, :title, :year
+  attr_reader :author, :title
+
 
-  named_parameters
+  named_parameters(author: 'unknown')
 
-  def initialize(author, title, year)
+  def edit_attributes(author, title)
     @author = author
     @title  = title
-    @year   = year
   end
 
-  named_parameters
 
-  def foo (bar, baz)
-    [bar, baz]
+  named_parameters_strict(author: 'unknown')
+
+  def edit_only_valid_attributes(author, title)
+    @author = author if author.is_a? String
+    @title = title if title.is_a? String
   end
 
-  named_parameters(foo: "foo", bar: "bar")
 
-  def method_with_defaults_only (foo, bar)
-    [foo, bar]
+  named_parameters_super(author: 'unknown')
+
+  def setup(author, title)
+    edit_attributes(author: author,
+                    title:  title)
   end
 
-  named_parameters(optional: "optional")
-  def method_with_defaults_and_mandatory (optional, mandatory)
-    [optional, mandatory]
+  named_parameters_strict_super(author: 'unknown')
+
+  def setup_only_valid_attributes(author, title, id)
+    edit_attributes(author: author,
+                    title:  title)
   end
 
-  named_parameters
+  named_parameters(attributes: [])
 
-  def method_with_block (array)
-    array.each { |e| yield e }
+  def change_attributes(attributes)
+    attributes.each do |attribute|
+      instance_variable_set("@#{attribute}", yield(send(attribute)))
+    end
   end
 
 end
 
-describe Book do
+describe NamedParameters do
 
   attr_reader :book
   before :each do
-    @book = Book.new(title:  "Enders Game",
-                     author: "Orson Scott Card",
-                     year:   1992)
+    @book = Book.new
   end
 
+  describe 'default' do
+    it 'should work with all parameters given' do
+      book.edit_attributes(author: 'Orson Scott Card',
+                           title:  'Enders Game')
+      book.title.should == 'Enders Game'
+      book.author.should == 'Orson Scott Card'
+    end
 
-  it "should be a book" do
-    book.should be_instance_of Book
-  end
+    it 'should work with only mandatory parameters given' do
+      book.edit_attributes(title: 'Enders Game')
+      book.title.should == 'Enders Game'
+      book.author.should == 'unknown'
+    end
 
-  it "attributes should be readable" do
-    book.title.should == "Enders Game"
-    book.author.should == "Orson Scott Card"
-    book.year.should == 1992
-  end
+    it 'should throw an error when a mandatory parameter misses' do
+      -> { book.edit_attributes(author: 'Orson Scott Card') }.should raise_error(RuntimeError)
+    end
 
-  it "should accept a second method defined" do
-    book.foo(bar: "bar",
-             baz: "baz").should == ["bar", "baz"]
+    it 'should ignore options that are not part of the parameters' do
+      book.edit_attributes(author: 'Orson Scott Card',
+                           title:  'Enders Game',
+                           year:   1985)
+      book.title.should == 'Enders Game'
+      book.author.should == 'Orson Scott Card'
+    end
   end
 
-  it "should raise an error on false parameters" do
-    -> { book.foo(bar: "bar") }.should raise_error(RuntimeError)
-    -> { book.foo(baz: "baz") }.should raise_error(RuntimeError)
-    -> { book.foo(bar:   "bar",
-                  baz:   "baz",
-                  other: "other") }.should raise_error(RuntimeError)
-  end
 
-  it "should accept a method with only optional parameters" do
-    #book.method_with_defaults_only.should == ["foo", "bar"]
-    book.method_with_defaults_only(foo: "FOO").should == ["FOO", "bar"]
-  end
+  describe 'strict named parameters' do
 
-  it "should not accept inconsistent method definition" do
-    code = -> do
-      class Book
-        some_defaults(a: "a", b: "b")
-        def a_method (a, c)
-          #... do something
-        end
-      end
+    it 'should work with all parameters given' do
+      book.edit_only_valid_attributes(author: 'Orson Scott Card',
+                                      title:  'Enders Game')
+      book.title.should == 'Enders Game'
+      book.author.should == 'Orson Scott Card'
+    end
+
+    it 'should work with only mandatory parameters given' do
+      book.edit_only_valid_attributes(title: 'Enders Game')
+      book.title.should == 'Enders Game'
+      book.author.should == 'unknown'
+    end
+
+    it 'should throw an error when a mandatory parameter misses' do
+      -> { book.edit_only_valid_attributes(author: 'Orson Scott Card') }.should raise_error(RuntimeError)
     end
-    code.should raise_error(RuntimeError)
+
+    it 'should throw an error when there are options that are not part of the parameters' do
+      -> { book.edit_only_valid_attributes(author: 'Orson Scott Card',
+                                           title:  'Enders Game',
+                                           year:   1985) }.should raise_error(RuntimeError)
+    end
+
   end
 
-  it "should accept a method with mixed parameters" do
-    book.method_with_defaults_and_mandatory(mandatory: "given").should == ["optional", "given"]
-    -> { book.method_with_defaults_and_mandatory(
-        optional: "only optional is given") }.should raise_error(RuntimeError)
+
+  describe 'with super' do
+
+    it 'should call super with all options as the only parameter' do
+      book.setup(author: 'Orson Scott Card',
+                 title:  'Enders Game',
+                 year:   1985,
+                 id:     1)
+      book.title.should == 'Enders Game'
+      book.author.should == 'Orson Scott Card'
+      book.id.should == 1
+    end
+
   end
 
-  it "should accept blocks for methods" do
-    array = []
-    book.method_with_block(array: [1, 2, 3]) { |e| array << e }
-    array.should == [1, 2, 3]
+  describe 'with super and strict' do
+
+    it 'should call super' do
+      book.setup_only_valid_attributes(author: 'Orson Scott Card',
+                                       title:  'Enders Game',
+                                       id:     1)
+      book.title.should == 'Enders Game'
+      book.author.should == 'Orson Scott Card'
+      book.id.should == 1
+    end
+
+    it 'should throw error when there are unwanted options' do
+      -> { book.setup_only_valid_attributes(author: 'Orson Scott Card',
+                                            title:  'Enders Game',
+                                            year:   1985,
+                                            id:     1) }.should raise_error(RuntimeError)
+    end
+
   end
 
+  describe 'with block' do
+    it 'should forward blocks' do
+      book.edit_attributes(author: 'Orson Scott Card',
+                           title:  'Enders Game')
+      book.change_attributes(attributes: [:author, :title]) do |attribute|
+        attribute.to_s.upcase
+      end
+      book.author.should == 'ORSON SCOTT CARD'
+      book.title.should == 'ENDERS GAME'
+    end
 
-end
+  end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: named_parameters
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-16 00:00:00.000000000 Z
+date: 2012-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &25932288 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -24,7 +24,15 @@ dependencies:
         version: 3.0.0
   type: :development
   prerelease: false
-  version_requirements: *25932288
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.9.0
+    - - <
+      - !ruby/object:Gem::Version
+        version: 3.0.0
 description: ! 'By including the NamedParameters module into your class/module the
   ''named_parameters'' macro is
 
@@ -69,9 +77,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.17
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Makes your methods callable with named parameters
 test_files:
 - spec/named_parameters_spec.rb
+has_rdoc: