hash_keyword_args 0.1.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'http://rubygems.org'
+
+# Specify your gem's dependencies in hash_keyword_args.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Ronen Barzel
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,222 @@
+= hash_keyword_args
+
+Defines Hash#keyword_args, which provides convenient features when
+using a Hash to provide keyword args to a method:
+
+* Argument checking
+* Accessor methods for values
+* Default values
+* Required vs. optional arguments
+* Argument value validation
+
+Typical simplest usage is as follows:
+
+  def my_method(args={})
+    args = args.keyword_args(:name, :rank)
+
+    puts "name is #{args.name}" if args.name
+    puts "rank is #{name.rank}" if args.rank
+  end
+
+  my_method()                                    # prints nothing
+  my_method(:name => "Kilroy")                   # prints: name is Kilroy
+  my_method(:name => "Kilroy", :rank => "Pawn")  # prints: name is Kilroy / rank is Pawn
+  my_method(:name => "Kilroy", :serial => 666)   # raises ArgumentError
+
+Notice that you declare the keyword arguments you're willing to accept, and
++keyword_args+ returns a new object that has accessors for each argument.
+If an non-matching keyword is detected, +keyword_args+ raises ArgumentError with a descriptive message.
+
+For fancier features (such as required arguments, default values, and
+whatnot) you specify properties for keywords, as discussed below.
+
+Note another common idiom is to define the keyword args after positional args ("rails style"), e.g.:
+
+  def find(id, opts={})
+    opts = opts.keyword_args(:conditions, :order)
+    ...
+  end
+  find(123, :order => :date)
+
+== Details
+
+=== Default Values
+
+Normally if a keyword isn't included in the args, the corresponding accessor will return nil.  But 
+you can provide default values that will be filled in if the keyword isn't provided.  E.g.
+
+  def my_method(args={})
+    args = args.keyword_args(:name, :rank => "Knight")
+
+    puts "name is #{args.name}" if args.name
+    puts "rank is #{name.rank}"
+  end
+
+  my_method()                                    # prints: rank is Knight
+  my_method(:name => "Kilroy")                   # prints: name is Kilroy / rank is Knight
+  my_method(:name => "Kilroy", :rank => "Pawn")  # prints: name is Kilroy / rank is Pawn
+
+Notice that because unadorned hashes must be at the end of ruby calls, any
+keywords with default values or other properties need to come after the ordinary optional
+keywords.  If you care about the order (or like symmetry in your code), you
+can specify the magic symbol :optional instead of a default value.  So this is equivalent to the above:
+
+    args = args.keyword_args(:rank => "Pawn",
+                             :name => :optional)
+
+The above actually show the shortcut form for specifying a default.  There's also a long form, which can be used in combination with other properties or if the default value conflicts with a shortcut:
+
+    args = args.keyword_args(:rank => { :default => "Pawn" },
+                             :name => { },                       
+                             )
+
+
+=== Required Keyword Args
+
+By default, keyword arguments are optional; and if not provided the value is +nil+ or the specified default.  But you can require that an argument be specified:
+
+    def my_method(args={})
+      args = args.keyword_args(:name => :required, :rank => "Pawn")
+
+      puts "name is #{args.name}"
+      puts "rank is #{name.rank}"
+    end
+
+    my_method()                         # raises ArgumentError with a descriptive message
+    my_method(:name => "Kilroy")        # prints: name is Kilroy / rank is Pawn
+
+Again, the above is the shortcut form.  The equivalent long form would be:
+
+      args = args.keyword_args(:name => { :required => true },
+                               :rank => { :default => "Pawn"},
+                               )
+
+=== Value Validation
+
++keyword_args+ can check that the provided values have a given type or are
+chosen from among a specified array of values.
+
+    def my_roll(args={})
+      args = args.keyword_args(:lucky => Integer,
+                               :dice => [:d6, :d10, :d20])
+
+      ...
+    end
+
+    my_roll(:lucky => 17, :dice => :d20)    # OK
+    my_roll(:lucky => "yes", :dice => :d20) # raises ArgumentError with a descriptive message for :lucky
+    my_roll(:lucky => 17, :dice => :d4)     # raises ArgumentError with a descriptive message for :dice
+    my_roll(:dice => :d4)                   # raises ArgumentError; :dice is OK but :lucky (nil) isn't an Integer
+
+Note that since the default value, +nil+ isn't a valid Integer and wasn't listed in the collection, the above declaration has implicitly caused those keywords to be required.  But it's possible to specify default values and/or allow nil using the long form:
+
+      args = args.keyword_args(:lucky => {:valid => Integer, :allow_nil => true})
+      args = args.keyword_args(:lucky => {:valid => Integer, :default => 7})
+      args = args.keyword_args(:lucky => {:valid => Integer, :default => 7, :allow_nil => true})
+
+In the third form above, the default value is 7, but if args explicitly included :lucky => nil it would override the default.
+
+=== Enumerable Values
+
+You can specify that you expect a keyword to take an array of values (or other +Enumerable+), via
+
+    def my_report(args={})
+      args = args.keyword_args(:winners => :enumerable)
+
+      args.winners.each do |winner|
+        puts "#{winner} is a winner"
+      end
+    end
+
+    my_report(:winners => ["Bonnie", "Clyde"])  # prints: Bonnie is a winner / Clyde is a winner
+    my_report(:winners => "Nero")               # prints: Nero is a winner
+    my_report()                                 # prints nothing
+
+Notice that a non-enumerable value gets automatically wrapped in an array for you, and the default value is an empty array.  If you want to do type checking on the values, you can use the long form:
+
+    args = args.keyword_args(:winners => { :enumerable => true, :valid => String})
+
+which will perform validity checking on element of the array.  You can combine :enumerable with a default as well:
+
+    args = args.keyword_args(:winners => { :enumerable => true, :default => ["Huey", "Dewey"] }
+
+=== Can I have my keywords & values in a Hash?
+
+The returned object is actually a +Hash+ with the accessors defined in its singleton class, so you use hash operations on it if needed, and you can pass it in turn to another method.  For example:
+
+  def my_wrapper(args={})
+    args = args.keyword_args(:name, :rank, :serial_number)
+    @serial_number = args.delete(:serial_number)
+    my_method(args)
+  end
+
+=== Suppress Argument Checking
+
+If you want to suppress argument checking you can specify the magic keyword :OTHERS, e.g.:
+
+  def execute(operator, opts={})
+    opts = opts.keyword_args(:immediately, :OTHERS)
+    immediately = opts.delete(:immediately)  # take :immediately out of the list...
+    opts.each do |opt, value|                # ...and loop over all the others
+      ...
+    end
+  end
+
+  execute(operator, :yabba => 1, :dabba => 2, :doo => 3)  # not an argument error
+
+No accessor methods are defined for undeclared keywords, but the values will be available in the hash.  The properties to :OTHERS are ignored, but if you want to make it look nice in at the end of list it's suggested that you use +:OTHERS => :optional:
+      
+  args = args.keyword_args(:name => String,
+                           :OTHERS => :optional)
+
+== Summary
+
+=== Complete list of long form properties that can be specified
+
+    :key => { :required => boolean }
+    :key => { :default => "your default value" }
+    :key => { :valid => Class-or-enumeration, :allow_nil => boolean }
+    :key => { :enumerable => boolean }  # implies :default => []
+
+=== Complete list of shortcuts
+
+    :key => :optional     # short for :key => {}
+    :key => :required     # short for :key => {:required => true}
+    :key => :enumerable   # short for :key => {:enumerable => true} which in turn implies :default => []
+    :key => [1, 2, 3]     # short for :key => {:valid => [1, 2, 3]} validates inclusion in the list
+    :key => Class         # short for :key => {:valid => Class}     validates is_a Class
+    :key => "whatever"    # anything else is short for :key => {:default => "whatever"}
+
+
+== Installation
+
+Install via:
+
+   % gem install hash_keyword_args
+
+or in your Gemfile:
+
+   gem "hash_keyword_args
+
+== Versions
+
+Has been tested on MRI 1.8.7 and MRI 1.9.3
+
+== History
+
+Past: I've been using this for years and carrying it around from project to project.  Finally got around to bundling it into a gem and putting it on rubygems, since that's now so darn easy to do!  Maybe somebody other than me will find this gem useful too.
+
+Future: I hope that this gem will be obviated in future versions of ruby.
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it.  Make sure that the coverage report
+  (generated automatically when you run rspec with ruby >= 1.9) is at 100%
+* Send me a pull request.
+
+== Copyright
+
+Released under the MIT License.  See LICENSE for details.
+

data/Rakefile

@@ -0,0 +1,7 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.rspec_opts = '-Ispec'
+end

data/hash_keyword_args.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/hash_keyword_args/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["ronen barzel"]
+  gem.email         = ["ronen@barzel.org"]
+  gem.description   = %q{Makes it easier and more robust to use a hash for keyword args to a method. In particular, performs argument checking and default values.}
+  gem.summary       = %q{Helper for using a hash for keyword args to a method. Performs argument checking, provides accessor methods for values, supports default values, required arguments, and argument value validation.}
+  gem.homepage      = ""
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.name          = "hash_keyword_args"
+  gem.require_paths = ["lib"]
+  gem.version       = HashKeywordArgs::VERSION
+
+  gem.add_dependency 'enumerable_hashify'
+
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'simplecov'
+  gem.add_development_dependency 'simplecov-gem-adapter'
+end

data/lib/hash_keyword_args.rb

@@ -0,0 +1,4 @@
+require "hash_keyword_args/version"
+require "hash_keyword_args/hash"
+
+Hash.send :include, HashKeywordArgs::Hash

data/lib/hash_keyword_args/hash.rb

@@ -0,0 +1,115 @@
+require 'enumerable_hashify'
+
+module HashKeywordArgs
+  module Hash
+    # given an argument hash and a description of acceptable keyword args and
+    # their default values, checks validity of the arguments and raises any
+    # errors, otherwise returns a new hash containing all arg values with
+    # defaults filled in as needed.
+    #
+    # args = hash.keyword_args(:a, :b, :c,        # these are all optional args
+    #                          :d => :optional,   # same as listing it the arg up front
+    #                          :e => :required,   # raises an error if arg not provided
+    #                          :f => "hello"      # default value
+    #                          :g => [:x,:y,:z]   # valid values
+    #                          :h => Integer      # valid type
+    #                          :i => :enumerable  # expect/coerce an enumerable, check all items, default is []
+    #                          :j => { :valid => Integer, :allow_nil => true}   # Integer or nil
+    #                          :j => { :valid => [:x,:y,:z], :default => :x, :required => true }   # combo
+    #                          )
+    #
+    # by default this will raise an error if the hash contains any keys not
+    # listed.  however, if :OTHERS is specified as a keyword arg, that test
+    # will be disabled and any other key/value pairs will be passed through.
+    #
+    # Returns a Struct whose values are the 
+    #
+    def keyword_args(*args)
+      argshash = args[-1].is_a?(Hash) ? args.pop : {}
+      argshash = args.hashify(:optional).merge(argshash)
+      others_OK = argshash.delete(:OTHERS)
+      ret = {}
+
+      # defaults, required, and checked
+      required = []
+      check = {}
+      argshash.each do |key, val|
+        # construct fleshed-out attribute hash for all args
+        attrs = case val
+                when Hash
+                  val[:default] ||= [] if val[:enumerable]
+                  val
+                when :required
+                  { :required => true }
+                when :optional
+                  {}
+                when :enumerable
+                  { :enumerable => true, :default => [] }
+                when Array
+                  { :valid => val }
+                when Class, Module
+                  { :valid => val }
+                else
+                  { :default => val }
+                end
+
+        # extract required flag, validity checks, and default vlues from attribute hash
+        required << key if attrs[:required]
+        check[key] = case valid = attrs[:valid]
+                     when Enumerable
+                       [:one_of, valid]
+                     when Class, Module
+                       [:is_a, valid]
+                     else
+                       [:ok]
+                     end
+        check[key][2] = [:allow_nil, :enumerable].select{|mod| attrs[mod]}
+        ret[key] = attrs[:default] if attrs.include?(:default)
+      end
+
+      # check validity of keys
+      unless others_OK or (others = self.keys - argshash.keys).empty?
+        raise ArgumentError, "Invalid keyword arg#{others.length>1 && "s" or ""} #{others.collect{|a| a.inspect}.join(', ')}", caller
+      end
+
+      # process values, checking validity
+      self.each do |key, val|
+        code, valid, mods = check[key]
+        mods ||= []
+        val = [ val ] unless mods.include?(:enumerable) and val.is_a?(Enumerable)
+        ok = val.all? { |v|
+          if mods.include?(:allow_nil) and v.nil?
+            true
+          else
+            case code
+            when nil     then true      # for OTHERS args, there's no code
+            when :ok     then true
+            when :one_of then valid.include?(v)
+            when :is_a   then v.is_a?(valid)
+            end
+          end
+        }
+        val = val.first unless mods.include?(:enumerable)
+        raise ArgumentError, "Invalid value for keyword arg #{key.inspect} => #{val.inspect}", caller unless ok
+        ret[key] = val
+        required.delete(key)
+      end
+
+      unless required.empty?
+        raise ArgumentError, "Missing required keyword arg#{required.length>1 && "s" or ""} #{required.collect{|a| a.inspect}.join(', ')}", caller
+      end
+
+      (class << ret ; self ; end).class_eval do
+        argshash.keys.each do |key|
+          define_method(key) do
+            self[key]
+          end
+        end
+      end
+
+      ret
+    end
+
+
+  end
+end

data/lib/hash_keyword_args/version.rb

@@ -0,0 +1,3 @@
+module HashKeywordArgs
+  VERSION = "0.1.0"
+end

data/spec/keyword_args_spec.rb

@@ -0,0 +1,104 @@
+require 'spec_helper'
+
+describe "keyword_args" do
+
+  it "unadorned args should be optional" do
+    expect { @args = {:a => 17}.keyword_args(:a, :b) }.should_not raise_error
+    @args.a.should == 17
+    @args.b.should be_nil
+  end
+
+  it ":optional args should be optional" do
+    expect { @args = {:a => 17}.keyword_args(:a => :optional, :b => :optional) }.should_not raise_error
+    @args.a.should == 17
+    @args.b.should be_nil
+  end
+
+  it ":required args should be required" do
+    expect { @args = {:a => 17}.keyword_args(:a => :required, :b => :required) }.should raise_error(ArgumentError)
+    expect { @args = {:a => 17, :b => 32}.keyword_args(:a => :required, :b => :required) }.should_not raise_error(ArgumentError)
+    @args.a.should == 17
+    @args.b.should == 32
+  end
+
+  it "should handle default value" do
+    @args = {:a => "alpha"}.keyword_args(:a => "adam", :b => "baker")
+    @args.a.should == "alpha"
+    @args.b.should == "baker"
+  end
+
+  it "should complain about invalid args" do
+    expect { @args = {:a => "whatever"}.keyword_args(:b) }.should raise_error(ArgumentError)
+  end
+
+  it "should not complain about invalid args if :OTHERS is given" do
+    expect { @args = {:a => "whatever"}.keyword_args(:b) }.should raise_error(ArgumentError)
+    expect { @args = {:a => "whatever"}.keyword_args(:b, :OTHERS) }.should_not raise_error
+    @args[:a].should == "whatever"
+  end
+
+  it "should not define method for OTHERS arg" do
+    @args = {:a => "whatever"}.keyword_args(:b, :OTHERS)
+    expect { @args.a }.should raise_error(NoMethodError)
+    @args[:a].should == "whatever"
+  end
+
+  it "should validate against list of values" do
+    expect { @args = {:a => :BAD}.keyword_args(:a => [:OK, :GOOD]) }.should raise_error(ArgumentError)
+    expect { @args = {:a => :OK}.keyword_args(:a => [:OK, :GOOD]) }.should_not raise_error
+    @args.a.should == :OK
+  end
+
+  it "should validate against class" do
+    expect { @args = {:a => "hello"}.keyword_args(:a => Integer) }.should raise_error(ArgumentError)
+    expect { @args = {:a => 17}.keyword_args(:a => Integer) }.should_not raise_error
+    @args.a.should == 17
+  end
+
+  it "should allow validity set via hash" do
+    expect { @args = {:a => "hello"}.keyword_args(:a => {:valid => Integer}) }.should raise_error(ArgumentError)
+    expect { @args = {:a => 17}.keyword_args(:a => {:valid => Integer}) }.should_not raise_error
+    @args.a.should == 17
+  end
+
+  it "should allow nil if :allow_nil is set" do
+    expect { @args = {:a => nil}.keyword_args(:a => {:valid => Integer}) }.should raise_error(ArgumentError)
+    expect { @args = {:a => nil}.keyword_args(:a => {:valid => Integer, :allow_nil => true}) }.should_not raise_error
+    @args.a.should be_nil
+  end
+
+  it "should accept enumerable if :enumerable" do
+    @args = {:a => 1..10}.keyword_args(:a => :enumerable)
+    @args.a.should == (1..10)
+  end
+
+  it "should coerce enumerable if :enumerable" do
+    @args = {:a => 3}.keyword_args(:a => :enumerable)
+    @args.a.should == [3]
+  end
+
+  it "should default enumerable if :enumerable" do
+    @args = {}.keyword_args(:a => :enumerable)
+    @args.a.should == []
+  end
+
+  it "should default enumerable if specified long form" do
+    @args = {}.keyword_args(:a => { :enumerable => true })
+    @args.a.should == []
+  end
+
+  it "should validate if :enumerable and :valid" do
+    expect {@args = {:a => 3}.keyword_args(:a => { :enumerable => true, :valid => String })}.should raise_error(ArgumentError)
+    expect {@args = {:a => ["OK", 3]}.keyword_args(:a => { :enumerable => true, :valid => String })}.should raise_error(ArgumentError)
+    expect {@args = {:a => ["OK", "YY"]}.keyword_args(:a => { :enumerable => true, :valid => String })}.should_not raise_error
+    @args.a.should == ["OK", "YY"]
+  end
+
+  it "should not include undefaulted arguments in hash" do
+    @args = {:a =>3}.keyword_args(:a, :b)
+    @args.include?(:a).should be_true
+    @args.include?(:b).should_not be_true
+  end
+
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,17 @@
+if RUBY_VERSION > "1.9"
+  require 'simplecov'
+  require 'simplecov-gem-adapter'
+  SimpleCov.start 'gem'
+end
+
+require 'rspec'
+require 'enumerable_hashify'
+require 'hash_keyword_args'
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: hash_keyword_args
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- ronen barzel
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-12-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: enumerable_hashify
+  requirement: &70192151724620 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70192151724620
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70192151724120 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70192151724120
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70192151723620 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70192151723620
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: &70192151722980 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70192151722980
+- !ruby/object:Gem::Dependency
+  name: simplecov-gem-adapter
+  requirement: &70192151722020 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70192151722020
+description: Makes it easier and more robust to use a hash for keyword args to a method.
+  In particular, performs argument checking and default values.
+email:
+- ronen@barzel.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.rdoc
+- Rakefile
+- hash_keyword_args.gemspec
+- lib/hash_keyword_args.rb
+- lib/hash_keyword_args/hash.rb
+- lib/hash_keyword_args/version.rb
+- spec/keyword_args_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Helper for using a hash for keyword args to a method. Performs argument checking,
+  provides accessor methods for values, supports default values, required arguments,
+  and argument value validation.
+test_files:
+- spec/keyword_args_spec.rb
+- spec/spec_helper.rb