optionable 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 05abcff0632b217f377d6b25eca962591f2e6b0f
+  data.tar.gz: c64a040f884e222841a93e796194e3648b17aeab
+SHA512:
+  metadata.gz: c9a204f1685ea3090b229f4d54e5c926d99b9810d75cb3d76a3ae28c59da5768363d34942e2a62bddbfbf601f1976aed9ad40de91249b3bd8338815256161a14
+  data.tar.gz: f5655b60fb44aaf901a63d2abcf41bd3be2aaca506fb72d0a67dbbbb250eb50df49d0107218ebdbd92b6dbbb684cca70cb8e0eb1c7f4e6fd53d9f72564b97a97

data/LICENSE.md

@@ -0,0 +1,20 @@
+Copyright (c) 2013 Durran Jordan
+
+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,83 @@
+BSON [![Build Status](https://secure.travis-ci.org/durran/optionable.png?branch=master&.png)](http://travis-ci.org/durran/optionable) [![Code Climate](https://codeclimate.com/github/durran/optionable.png)](https://codeclimate.com/github/durran/optionable) [![Coverage Status](https://coveralls.io/repos/durran/optionable/badge.png?branch=master)](https://coveralls.io/r/durran/optionable?branch=master)
+====
+
+Robust validation of options passed to Ruby methods.
+
+Compatibility
+-------------
+
+BSON is tested against MRI (1.9.2+), JRuby (1.7.0+), Rubinius (2.0.0+).
+
+Installation
+------------
+
+With bundler, add the `optionable` gem to your `Gemfile`.
+
+```ruby
+gem "optionable",
+```
+
+Require the `optionable` gem in your application.
+
+```ruby
+require "optionable"
+```
+
+Usage
+-----
+
+Include the optional module in your object, and use the DSL for define what values
+are valid for the specified options. Currently you can match on exact values or
+values of a specific type. Then to validate your options, simply call `validate_strict`
+and pass it the hash of options.
+
+```ruby
+class Parser
+  include Optionable
+
+  option(:streaming).allow(true, false)
+  option(:timeout).allow(Optionable.any(Integer))
+
+  def initialize(options = {})
+    validate_strict(options)
+  end
+end
+```
+
+If the options are invalid, an `Optionable::Invalid` error will be raised.
+
+
+API Documentation
+-----------------
+
+The [API Documentation](http://rdoc.info/github/durran/optionable/master/frames) is
+located at rdoc.info.
+
+Versioning
+----------
+
+This project adheres to the [Semantic Versioning Specification](http://semver.org/).
+
+License
+-------
+
+Copyright (c) 2013 Durran Jordan
+
+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/Rakefile

@@ -0,0 +1,30 @@
+require "bundler"
+Bundler.setup
+
+require "rake"
+require "rspec/core/rake_task"
+
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+require "optionable/version"
+
+task :gem => :build
+task :build do
+  system "gem build optionable.gemspec"
+end
+
+task :install => :build do
+  system "sudo gem install optionable-#{Optionable::VERSION}.gem"
+end
+
+task :release => :build do
+  system "git tag -a v#{Optionable::VERSION} -m 'Tagging #{Optionable::VERSION}'"
+  system "git push --tags"
+  system "gem push optionable-#{Optionable::VERSION}.gem"
+  system "rm optionable-#{Optionable::VERSION}.gem"
+end
+
+RSpec::Core::RakeTask.new("spec") do |spec|
+  spec.pattern = "spec/**/*_spec.rb"
+end
+
+task :default => :spec

data/lib/optionable.rb

@@ -0,0 +1,68 @@
+# encoding: utf-8
+require "optionable/any"
+require "optionable/dsl"
+require "optionable/invalid"
+require "optionable/validator"
+require "optionable/version"
+
+# This module is to be included in objects that require some nifty options
+# validation.
+#
+# @since 0.0.0
+module Optionable
+
+  # Validate the provided options against the defined acceptable values.
+  #
+  # @example Validate the options.
+  #   optionable.validate_strict(read: "test")
+  #
+  # @param [ Hash ] options The options to validate.
+  #
+  # @raise [ Optionable::Invalid ] If the options are wack.
+  #
+  # @since 0.0.0
+  def validate_strict(options)
+    (options || {}).each_pair do |key, value|
+      validator = optionable_validators[key]
+      validator.validate!(value) if validator
+    end
+  end
+
+  private
+
+  # Get the optionable validators from the class.
+  #
+  # @api private
+  #
+  # @since 0.0.0
+  def optionable_validators
+    self.class.optionable_validators
+  end
+
+  class << self
+
+    # Provides a convenience method for creating a new option acceptance for
+    # values of a certain type.
+    #
+    # @example Create the any type.
+    #   Optionable.any(Integer)
+    #
+    # @param [ Class ] type The type of supported value.
+    #
+    # @since 0.0.0
+    def any(type)
+      Any.new(type)
+    end
+
+    private
+
+    # Extend the DSL methods when the module is included.
+    #
+    # @api private
+    #
+    # @since 0.0.0
+    def included(klass)
+      klass.extend(DSL)
+    end
+  end
+end

data/lib/optionable/any.rb

@@ -0,0 +1,49 @@
+# encoding: utf-8
+module Optionable
+
+  # Represents an option that can be of any value of a certain type.
+  #
+  # @since 0.0.0
+  class Any
+
+    # @!attribute type
+    #   @return [ Class ] The class type.
+    attr_reader :type
+
+    # Check equality of the value for this type.
+    #
+    # @example Check if the value equals this type.
+    #   any == 10
+    #
+    # @param [ Object ] other The object to check against.
+    #
+    # @since 0.0.0
+    def ==(other)
+      other.is_a?(type)
+    end
+
+    # Initialize the new any value object.
+    #
+    # @example Initialize the any value object.
+    #   Optionable::Any.new(Integer)
+    #
+    # @param [ Class ] type The class type.
+    #
+    # @since 0.0.0
+    def initialize(type)
+      @type = type
+    end
+
+    # Return the pretty inspected type.
+    #
+    # @example Get the any as an inspection.
+    #   any.inspect
+    #
+    # @return [ String ] any + the class type.
+    #
+    # @since 0.0.0
+    def inspect
+      "any #{type}"
+    end
+  end
+end

data/lib/optionable/dsl.rb

@@ -0,0 +1,35 @@
+# encoding: utf-8
+module Optionable
+
+  # Provides the entry point to the optionable DSL.
+  #
+  # @since 0.0.0
+  module DSL
+
+    # Defines an option to be validated.
+    #
+    # @example Define the option.
+    #   option(:read).allow(:primary, :secondary)
+    #
+    # @param [ Symbol ] key The name of the option.
+    #
+    # @return [ Optionable::Validator ] The associated validator for the option.
+    #
+    # @since 0.0.0
+    def option(key)
+      optionable_validators[key] ||= Validator.new(key)
+    end
+
+    # Get all the validators for all options.
+    #
+    # @example Get all the validators.
+    #   dsl.optionable_validators
+    #
+    # @return [ Hash<Symbol, Optionable::Validator> ] The validators.
+    #
+    # @since 0.0.0
+    def optionable_validators
+      @optionable_validators ||= {}
+    end
+  end
+end

data/lib/optionable/invalid.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+module Optionable
+
+  # This exception is raised whenever invalid options are found during
+  # validation.
+  #
+  # @since 0.0.0
+  class Invalid < RuntimeError
+
+    # @!attribute key
+    #   @return [ Symbol ] The name of the option.
+    # @!attribute value
+    #   @return [ Object ] The value provided for the option.
+    # @!attribute allowed
+    #   @return [ Array<Object> ] The allowed values for the option.
+    attr_reader :key, :value, :allowed
+
+    # Initialize the Invalid option exception.
+    #
+    # @example Initialize the exception.
+    #   Optionable::Invalid.new(:test, 10, [ 11, 12 ])
+    #
+    # @param [ Symbol ] key The name of the option.
+    # @param [ Object ] value The value provided for the option.
+    # @param [ Array<Object> ] allowed The allowed values for the option.
+    #
+    # @since 0.0.0
+    def initialize(key, value, allowed)
+      @key = key
+      @value = value
+      @allowed = allowed
+      super(generate_message)
+    end
+
+    private
+
+    # Generate the message that will be used in the exception.
+    #
+    # @api private
+    #
+    # @since 0.0.0
+    def generate_message
+      "#{value.inspect} is not acceptable for option #{key.inspect}. " +
+      "Valid values are: #{allowed.map(&:inspect).join(", ")}."
+    end
+  end
+end

data/lib/optionable/validator.rb

@@ -0,0 +1,75 @@
+# encoding: utf-8
+module Optionable
+
+  # This is responsible for the actual validation of the options.
+  #
+  # @since 0.0.0
+  class Validator
+
+    # @!attribute key
+    #   @return [ Symbol ] The name of the option.
+    attr_reader :key
+
+    # Tells the validator what values are acceptable for the option.
+    #
+    # @example Specify allowed values.
+    #   validator.allow(:test, :testing)
+    #
+    # @param [ Array<Object> ] values The allowed values.
+    #
+    # @return [ Array<Object> ] The full list of allowed values.
+    #
+    # @since 0.0.0
+    def allow(*values)
+      allowed_values.concat(values)
+    end
+
+    # Initialize the new validator.
+    #
+    # @example Initialize the validator.
+    #   Optionable::Validator.new(:test)
+    #
+    # @param [ Symbol ] key The name of the option.
+    #
+    # @since 0.0.0
+    def initialize(key)
+      @key = key
+    end
+
+    # Validate the provided value against the acceptable values.
+    #
+    # @example Validate the provided value.
+    #   validator.validate!("test")
+    #
+    # @param [ Object ] value The value for the option.
+    #
+    # @raise [ Optionable::Invalid ] If the value is invalid.
+    #
+    # @since 0.0.0
+    def validate!(value)
+      raise Invalid.new(key, value, allowed_values) unless match?(value)
+    end
+
+    private
+
+    # Get the allowed values for the option.
+    #
+    # @api private
+    #
+    # @since 0.0.0
+    def allowed_values
+      @allowed_values ||= []
+    end
+
+    # Does the value match an allowed value?
+    #
+    # @api private
+    #
+    # @since 0.0.0
+    def match?(value)
+      allowed_values.any? do |allowed|
+        value == allowed
+      end
+    end
+  end
+end

data/lib/optionable/version.rb

@@ -0,0 +1,4 @@
+# encoding: utf-8
+module Optionable
+  VERSION = "0.1.0"
+end

data/spec/optionable/any_spec.rb

@@ -0,0 +1,47 @@
+require "spec_helper"
+
+describe Optionable::Any do
+
+  describe "#==" do
+
+    let(:any) do
+      described_class.new(Integer)
+    end
+
+    context "when the value is of the correct type" do
+
+      it "returns true" do
+        expect(any).to eq(10)
+      end
+    end
+
+    context "when the value is an incorrect type" do
+
+      it "returns false" do
+        expect(any).to_not eq(10.5)
+      end
+    end
+  end
+
+  describe "#initialize" do
+
+    let(:any) do
+      described_class.new(Integer)
+    end
+
+    it "sets the type" do
+      expect(any.type).to eq(Integer)
+    end
+  end
+
+  describe "#inspect" do
+
+    let(:any) do
+      described_class.new(Integer)
+    end
+
+    it "returns any + the name of the class" do
+      expect(any.inspect).to eq("any Integer")
+    end
+  end
+end

data/spec/optionable/invalid_spec.rb

@@ -0,0 +1,46 @@
+require "spec_helper"
+
+describe Optionable::Invalid do
+
+  describe "#message" do
+
+    context "when a single value is provided" do
+
+      let(:invalid) do
+        described_class.new(:test, 10, [ 15 ])
+      end
+
+      it "returns the single value error message" do
+        expect(invalid.message).to eq(
+          "10 is not acceptable for option :test. Valid values are: 15."
+        )
+      end
+    end
+
+    context "when multiple values are provided" do
+
+      let(:invalid) do
+        described_class.new(:test, 10, [ 15, "something" ])
+      end
+
+      it "returns the single value error message" do
+        expect(invalid.message).to eq(
+          "10 is not acceptable for option :test. Valid values are: 15, \"something\"."
+        )
+      end
+    end
+
+    context "when multiple values are provided with type" do
+
+      let(:invalid) do
+        described_class.new(:test, "test", [ Optionable.any(Integer) ])
+      end
+
+      it "returns the single value error message" do
+        expect(invalid.message).to eq(
+          "\"test\" is not acceptable for option :test. Valid values are: any Integer."
+        )
+      end
+    end
+  end
+end

data/spec/optionable/validator_spec.rb

@@ -0,0 +1,89 @@
+require "spec_helper"
+
+describe Optionable::Validator do
+
+  describe "#allow" do
+
+    let(:validator) do
+      described_class.new(:test)
+    end
+
+    let(:allowed) do
+      validator.send(:allowed_values)
+    end
+
+    context "when no values exist" do
+
+      before do
+        validator.allow(:test)
+      end
+
+      it "sets the valid options" do
+        expect(allowed).to eq([ :test ])
+      end
+    end
+
+    context "when sending multiple values" do
+
+      before do
+        validator.allow(:test, :testing)
+      end
+
+      it "sets the valid options" do
+        expect(allowed).to eq([ :test, :testing ])
+      end
+    end
+
+    context "when existing values are present" do
+
+      before do
+        validator.allow(:test)
+        validator.allow(:testing)
+      end
+
+      it "sets the valid options" do
+        expect(allowed).to eq([ :test, :testing ])
+      end
+    end
+  end
+
+  describe "#initialize" do
+
+    let(:validator) do
+      described_class.new(:test)
+    end
+
+    it "sets the key of the option" do
+      expect(validator.key).to eq(:test)
+    end
+  end
+
+  describe "#validate!" do
+
+    let(:validator) do
+      described_class.new(:test)
+    end
+
+    context "when the value is acceptable" do
+
+      before do
+        validator.allow(:testing)
+      end
+
+      it "raises no error" do
+        expect {
+          validator.validate!(:testing)
+        }.to_not raise_error
+      end
+    end
+
+    context "when the value is invalid" do
+
+      it "raises an error" do
+        expect {
+          validator.validate!(:testing)
+        }.to raise_error(Optionable::Invalid)
+      end
+    end
+  end
+end

data/spec/optionable_spec.rb

@@ -0,0 +1,118 @@
+require "spec_helper"
+
+describe Optionable do
+
+  before(:all) do
+    class Model
+      include Optionable
+
+      option(:read).allow(:primary, :secondary)
+      option(:write).allow(Optionable.any(Integer))
+      option(:update).allow(int: Optionable.any(Integer))
+      option(:update).allow(str: "exact")
+      option(:update).allow(flt: 10.5)
+
+      def initialize(options = {})
+        validate_strict(options)
+      end
+    end
+  end
+
+  after(:all) do
+    Object.send(:remove_const, :Model)
+  end
+
+  describe "#validate_strict" do
+
+    context "when options are empty" do
+
+      it "does not raise an error" do
+        expect {
+          Model.new
+        }.to_not raise_error
+      end
+    end
+
+    context "when options are nil" do
+
+      it "does not raise an error" do
+        expect {
+          Model.new(nil)
+        }.to_not raise_error
+      end
+    end
+
+    context "when the options are valid" do
+
+      context "when options are allowed specific values" do
+
+        it "does not raise an error for any value" do
+          expect {
+            Model.new(read: :primary)
+            Model.new(read: :secondary)
+          }.to_not raise_error
+        end
+      end
+
+      context "when options allow types" do
+
+        it "does not raise an error for correct type" do
+          expect {
+            Model.new(write: 10)
+          }.to_not raise_error
+        end
+      end
+
+      context "when options are mixed" do
+
+        it "does not raise an error for correct type" do
+          expect {
+            Model.new(update: { int: 10 })
+          }.to_not raise_error
+        end
+
+        it "does not raise an error for correct value" do
+          expect {
+            Model.new(update: { str: "exact" })
+          }.to_not raise_error
+        end
+      end
+    end
+
+    context "when the options are not valid" do
+
+      context "when options are allowed specific values" do
+
+        it "raises an error for any bad value" do
+          expect {
+            Model.new(read: :tertiary)
+          }.to raise_error(Optionable::Invalid)
+        end
+      end
+
+      context "when options allow types" do
+
+        it "raises an error for incorrect type" do
+          expect {
+            Model.new(write: 14.5)
+          }.to raise_error(Optionable::Invalid)
+        end
+      end
+
+      context "when options are mixed" do
+
+        it "raises an error for incorrect type" do
+          expect {
+            Model.new(update: { int: 14.5 })
+          }.to raise_error(Optionable::Invalid)
+        end
+
+        it "raises an error for incorrect value" do
+          expect {
+            Model.new(update: { str: "blah" })
+          }.to raise_error(Optionable::Invalid)
+        end
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,14 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "..", "lib"))
+
+if ENV["CI"]
+  require "simplecov"
+  require "coveralls"
+  SimpleCov.formatter = Coveralls::SimpleCov::Formatter
+  SimpleCov.start do
+    add_filter "spec"
+  end
+end
+
+require "optionable"
+require "rspec"

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: optionable
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Durran Jordan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-07-09 00:00:00.000000000 Z
+dependencies: []
+description: Robust options validation for methods.
+email:
+- durran@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/optionable/any.rb
+- lib/optionable/dsl.rb
+- lib/optionable/invalid.rb
+- lib/optionable/validator.rb
+- lib/optionable/version.rb
+- lib/optionable.rb
+- README.md
+- LICENSE.md
+- Rakefile
+- spec/optionable/any_spec.rb
+- spec/optionable/invalid_spec.rb
+- spec/optionable/validator_spec.rb
+- spec/optionable_spec.rb
+- spec/spec_helper.rb
+homepage: 
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: 1.3.6
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: Robust options validation for methods.
+test_files:
+- spec/optionable/any_spec.rb
+- spec/optionable/invalid_spec.rb
+- spec/optionable/validator_spec.rb
+- spec/optionable_spec.rb
+- spec/spec_helper.rb