with_validations 0.5.0

data/ChangeLog.md

@@ -0,0 +1,2 @@
+## Version 0.5.0 (April 12, 2012)
+

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Stefan Rohlfing
+
+MIT License
+
+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.md

@@ -0,0 +1,114 @@
+# WithValidations
+
+### Easy validation of option keys and their values.
+
+## Features
+
+* Validate If all option values are valid.
+* Automatically assign default values to missing but required keys.
+* (Optionally) check for unsupported keys in the options hash.
+* Assign the validated values to one or more variables.
+
+
+## Installation
+
+``` bash
+$ gem install with_validations
+```
+
+## Usage
+
+__Note__: A class including this module also need to stick to the following conventions:
+
+* Provide a hash of the type `{ option_key => [default_value, validation_proc], ...}`
+  assigned to a constant named `OPTIONS`.
+* Name the option hash of a method `options`.
+
+### Sample Setup
+
+````ruby
+require 'with_validations'
+
+class TestClass
+  include WithValidations
+
+  # option_key => [default_value, validation_proc]
+  OPTIONS = {:compact      => [false, lambda {|value| is_boolean?(value) }],
+             :with_pinyin  => [true,  lambda {|value| is_boolean?(value) }],
+             :thread_count => [8,     lambda {|value| value.kind_of?(Integer) }]}
+
+  # Instance method
+  def test_method_1(options={}) # options hash has to be named 'options'
+    @thread_count = validate { :thread_count }
+
+    #...
+  end
+
+  # Singleton method
+  def self.test_method_2(options={})
+    @compact, @with_pinyin = validate { [:compact, :with_pinyin] }
+
+    # ...
+  end
+
+  # Optional parameter set to true.
+  def self.test_method_3(options={})
+    @compact, @with_pinyin = validate(true) { [:compact, :with_pinyin] }
+
+    # ...
+  end
+
+  #...
+end
+````
+
+#### Use Cases
+
+```` ruby
+obj = TestClass.new
+obj.test_method_1(:thread_count => 10)
+# @thread_count set to 10
+
+# No options hash passed, used default value
+my_class.test_method_1
+# @thread_count set to 8
+
+# Passing any invalid value
+my_class.test_method_1(:thread_count => 'invalid')
+# ArgumentError: Value 'invalid' is not a valid value for key 'thread_count'
+
+
+TestClass.test_method_2(:compact => true, :with_pinyin => false)
+# @compact set to true, @with_pinyin set to false
+
+TestClass.test_method_2(:compact => true)
+# No options for key :with_pinyin provided: Use the default value
+# @compact is set to true, @with_pinyin is set to true
+
+# By default, any keys from the options hash that are not part of the block are ignored.
+TestClass.test_method_2(:compact => true,
+                        :with_pinyin => false,
+                        :thread_count => 10,           # Key in OPTIONS, but not part of the block.
+                        :not_listed => 'some value')   # Not part of the block
+# @compact set to true, @with_pinyin set to false
+
+# Optional argument set to true: Any key from the options hash that is not part of the keys
+     # passed to the block will throw an exception.
+TestClass.test_method_3(:compact => true,
+                        :with_pinyin => false,
+                        :thread_count => 10,           # Key in OPTIONS, but not part of the block.
+                        :not_listed => 'some value')   # Not part of the block
+# Exception: The following keys are not supported: not_listed
+````
+
+## Documentation
+
+### Main method
+
+* [validate](http://rubydoc.info/github/bytesource/with_validations/master/WithValidations:validate)
+### Optional methods
+
+* [extract_options](http://rubydoc.info/github/bytesource/with_validations/master/WithValidations:extract_options)
+* [is_boolean?](http://rubydoc.info/github/bytesource/with_validations/master/WithValidations:is_boolean%3F)
+
+__Note__: All methods are available as both instance and singleton methods.

data/Rakefile

@@ -0,0 +1,22 @@
+# require 'spec/rake/spectask' # depreciated
+require 'rspec/core/rake_task'
+# require 'rake/gempackagetask' # depreciated
+require 'rubygems/package_task'
+require 'rdoc/task'
+
+# Build gem: rake gem
+# Push gem:  rake push
+
+task :default => [ :spec, :gem ]
+
+RSpec::Core::RakeTask.new { :spec }
+
+gem_spec = eval(File.read('with_validations.gemspec'))
+
+Gem::PackageTask.new( gem_spec ) do |t|
+  t.need_zip = true
+end
+
+task :push => :gem do |t|
+  sh "gem push -v pkg/#{gem_spec.name}-#{gem_spec.version}.gem"
+end

data/lib/with_validations.rb

@@ -0,0 +1,133 @@
+# encoding: utf-8
+require "with_validations/version"
+require 'with_validations/core_ext/hash'
+
+module WithValidations
+
+  # In order to be able to validate options in both
+  # instance and singleton methods,
+  # the following method makes sure that all module methods are available
+  # as both instance and singleton methods.
+  def self.included(klass)
+    klass.extend(self)
+  end
+
+
+  # Validates the options passed in the block.
+  #  Options can either be a single option key or an array of options keys.
+  #  Option keys and their values are validated based on the information given in a
+  #  mandatory constant called `OPTIONS`. Keys from a methods `options` has that are not listed in `OPTIONS` are ignored.
+  # @note A class that includes this module is required to:
+  #
+  #  * provide a constant named `OPTIONS` with a hash of the following type:
+  #   `{ option_key => [default_value, validation_proc], ...}`.
+  #  * name the optional option hash of a method `options`.
+  # @overload validate(strict)
+  #  @param [Boolean] strict Whether or not raise an exception if the options has contains any unsupported keys.
+  #    Default: `false`
+  # @overload validate()
+  # @return [Array, Object] If more than one keys are evaluated, return an array of the key values, otherwise returns a single value.
+  # @example
+  #  require 'with_validations'
+  #
+  #   class TestClass
+  #     include WithValidations
+  #
+  #     # option_key => [default_value, validation_proc]
+  #     OPTIONS = {:compact      => [false, lambda {|value| is_boolean?(value) }],
+  #                :with_pinyin  => [true,  lambda {|value| is_boolean?(value) }],
+  #                :thread_count => [8,     lambda {|value| value.kind_of?(Integer) }]}
+  #
+  #     # Instance method
+  #     def test_method_1(options={})
+  #       @thread_count = validate { :thread_count }
+  #       # ...
+  #     end
+  #
+  #     # Singleton method
+  #     def self.test_method_2(options={})
+  #       @compact, @with_pinyin = validate { [:compact, :with_pinyin] }
+  #       # ...
+  #     end
+  #
+  #     # Optional parameter set to true.
+  #     def self.test_method_3(options={})
+  #       @compact, @with_pinyin = validate(true) { [:compact, :with_pinyin] }
+  #       #...
+  #     end
+  #
+  #     #...
+  #   end
+  def validate(strict = false, &block)
+    raise ArgumentError, "No block given" unless block
+
+    argument = block.call
+    # Raise exception if the block is empty.
+    raise ArgumentError, "Block is empty"  if argument.nil?
+
+    keys = Array(argument) # Wrap single key as array. If passed an array, just return the array.
+
+    constant = eval("OPTIONS", block.binding)
+    options  = eval("options", block.binding) # Alternative: constant = block.binding.eval("OPTIONS")
+
+    # Handling optional argument 'strict'
+    ops = options.dup
+    ops.delete_keys!(*keys)
+    # If 'strict' is set to 'true', any key from the options key that is not part of the keys
+    # passed to the block will throw an exception.
+    raise Exception, "The following keys are not supported: #{ops.keys.join(', ')}"  if ops.size > 0 && strict
+
+    values = keys.map do |key|
+      # Raise exception if 'key' from the block is NOT a key in the OPTIONS constant.
+      raise ArgumentError, "Key '#{key}' passed to the block not found in OPTIONS" unless constant.keys.include?(key)
+
+      if options.has_key?(key) # Supported key in block found in options => extract its value from options.
+        value = options[key]
+        # Check if 'value' is a valid value.
+        validation = constant[key][1]
+        if validation.call(value)    # Validation passed => return value from options
+          value
+        else                         # Validation failed => raise exception
+          raise ArgumentError, "'#{value}' (#{value.class}) is not a valid value for key '#{key}'."
+        end
+      else # Supported key in block not found in options => return its default value.
+        default_value = constant[key][0]
+        default_value
+      end
+    end
+
+    values.size > 1 ? values : values [0]
+  end
+
+  # Returns a new hash from `options` based on the keys in `*keys`.
+  #  in `arr`. Keys in `arr` not found in `options` are ignored.
+  #  *Use case*: When a method's options hash contains options for another method
+  #  that throws an exeption if the options hash contains keys not handled internally (Example: CSV library)
+  #  the options special to that method need to be extracted before passed as an argument.
+  # @return [Hash]
+  # @example
+  #   def sample_method(text, options={})
+  #     @compact, @with_pinyin = validate { [:compact, :with_pinyin] }
+  #
+  #     csv_options = extract_options(CSV::DEFAULT_OPTIONS.keys, options)
+  #     csv = CSV.parse(text, csv_options)
+  #     #...
+  #   end
+  def extract_options(arr, options)
+    options.slice(*arr)
+  end
+
+
+
+  # Some useful validation methods
+  # =============================
+
+  # Helper method that can be used in a validation proc.
+  # @return [true, false] Returns `true` if the argument passed is either `true` or `false`.
+  #   Returns `false` on any other argument.
+  def is_boolean?(value)
+    # Only true for either 'false' or 'true'
+    !!value == value
+  end
+
+end

data/lib/with_validations/core_ext/hash.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+
+class Hash
+
+  # Removes `*keys` from self.
+  # @note (see #slice)
+  # @return [Hash] self with `*keys` removed.
+  def delete_keys!(*keys)
+    keys.each do |key|
+      self.delete(key)
+    end
+  end
+
+
+  # Creates a sub-hash from `self` with the keys from `*keys`.
+  # @note keys in `*keys` not present in `self` are silently ignored.
+  # @return [Hash] a copy of `self`.
+  def slice(*keys)
+    self.select { |k,v| keys.include?(k) }
+  end
+end
+

data/lib/with_validations/version.rb

@@ -0,0 +1,3 @@
+module WithValidations
+  VERSION = "0.5.0"
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: with_validations
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+  prerelease: 
+platform: ruby
+authors:
+- Stefan Rohlfing
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-04-12 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &23227300 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *23227300
+description: ! 'Easy validation of option keys and their values. Installation and
+  usage is very simple. You find all
+
+  the information you need on my homepage listed below.
+
+'
+email: stefan.rohlfing@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/with_validations.rb
+- lib/with_validations/version.rb
+- lib/with_validations/core_ext/hash.rb
+- ChangeLog.md
+- README.md
+- Rakefile
+- LICENSE
+- Gemfile
+homepage: http://github.com/bytesource/with_validations
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: with_validations
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: WithValidation - Easy validation of option keys and values.
+test_files: []