named_parameters 0.1.0

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2012 Marvin Ede
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README

@@ -0,0 +1,76 @@
+= Named Parameters
+Makes your methods callable with named parameters
+
+== Get it
+Surprisingly it is this easy:
+
+    gem install named_parameters
+
+---
+
+== Use it
+= First, include NamedParameters:
+    class AnyClass
+        include NamedParameters
+    end
+
+= Second, call the macro:
+
+
+    class AnyClass
+        include NamedParameters
+
+        named_parameters
+    end
+
+
+= Last, but not least, define your method:
+    class AnyClass
+        include NamedParameters
+
+        named_parameters
+        def some_method(a,b,c)
+            #... do something
+        end
+    end
+
+== Call it
+    any_object = AnyClass.new
+    any_object.some_method(a: "here comes the 'a' parameter",
+                           c: "this is for c"
+                           b: 42)
+
+
+
+---
+== Optional parameters
+You may also define optional parameters with defaults values:
+    class AnyClass
+        named_parameters(a: "default a", b: "default b")
+        def some_method(a,b)
+            [a,b]
+        end
+    end
+The call is just the same:
+    any_object.some_method(a: "actual a") # =>  ["actual a", "default b"]
+    any_object.some_method(b: "actual b") # =>  ["default a", "actual b"]
+    any_object.some_method                # =>  ["default a", "default b"]
+
+== Optional and mandatory parameters
+You can have both optional and mandatory parameters for the same method.
+All paramaters with no default value are mandatory:
+
+    class AnyClass
+        named_parameters(a: "default a")
+        def some_method(a,b,c)
+            [a,b,c]
+        end
+    end
+
+    any_object.some_method(b: "given",
+                           c: nil) # => ["default a", "given", nil]
+
+    any_object.some_method(b: "given",
+                           a: "overwritten") # =>  Error: Mandatory parameter 'c' not given
+
+

data/spec/named_parameters_spec.rb

@@ -0,0 +1,94 @@
+require_relative "../src/named_parameters"
+
+class Book
+  include NamedParameters
+
+  attr_reader :author, :title, :year
+
+  named_parameters
+
+  def initialize author, title, year
+    @author = author
+    @title  = title
+    @year   = year
+  end
+
+  named_parameters
+
+  def foo bar, baz
+    [bar, baz]
+  end
+
+  named_parameters(foo: "foo", bar: "bar")
+
+  def method_with_defaults_only foo, bar
+    [foo, bar]
+  end
+
+  named_parameters(optional: "optional")
+
+  def method_with_defaults_and_mandatory optional, mandatory
+    [optional, mandatory]
+  end
+
+end
+
+describe Book do
+
+  attr_reader :book
+  before :each do
+    @book = Book.new(title:  "Enders Game",
+                     author: "Orson Scott Card",
+                     year:   1992)
+  end
+
+
+  it "should be a book" do
+    book.should be_instance_of Book
+  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 accept a second method defined" do
+    book.foo(bar: "bar",
+             baz: "baz").should == ["bar", "baz"]
+  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
+
+  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
+    end
+    code.should raise_error(RuntimeError)
+  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)
+  end
+
+
+end

data/src/named_parameters.rb

@@ -0,0 +1,128 @@
+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 named_parameters macro
+#
+module NamedParameters
+
+  # :nodoc:
+  # Makes all methods of this module to class or module methods of include
+  def self.included base
+    base.extend(self)
+  end
+
+  #noinspection RubyArgCount
+  self.class.class_eval do
+    alias :method_added_before_named_parameters :method_added #:nodoc:
+    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 = { }
+    defaults.empty? ? all_required : some_defaults(defaults)
+  end
+
+  private
+
+  # [Symbol] is in [:nothing, :all_required, :defaults]
+  @@next_method_modifier = :nothing
+
+  def all_required
+    @@next_method_modifier = :all_required
+  end
+
+  def some_defaults defaults
+    @@next_method_modifier = :defaults
+    @@defaults             = defaults
+  end
+
+
+  # @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
+
+  end
+
+  # @param method_name [Symbol]
+  # @return [Object] Not important
+  def redefine_all_required_method(method_name)
+    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|
+        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
+        STRING
+      end
+    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
+    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 = { }|
+        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
+        STRING
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: named_parameters
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Marvin Ede
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-04-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &25860360 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.9.0
+    - - <
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *25860360
+description: ! 'By including the NamedParameters module into your class/module the
+  ''named_parameters'' macro is
+
+  available. Optional parameters with default values can be as easily defined as mandatory
+  parameters. Your actual
+
+  method definition does not change at all'
+email: marvinede@gmx.net
+executables: []
+extensions: []
+extra_rdoc_files:
+- README
+- LICENSE
+files:
+- src/named_parameters.rb
+- README
+- LICENSE
+- spec/named_parameters_spec.rb
+homepage: http://rubygems.org/gems/named_parameters
+licenses:
+- apache 2.0
+post_install_message: 
+rdoc_options:
+- --title
+- Named Parameters
+- --main
+- README
+- --line_numbers
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.17
+signing_key: 
+specification_version: 3
+summary: Makes your methods callable with named parameters
+test_files:
+- spec/named_parameters_spec.rb