hash_control 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6c58ba9b45b5b93680cc8d22d8dd859b355bafd3
+  data.tar.gz: c98ed21ba6469980f703b23f2eefeccdd6f2f8f0
+SHA512:
+  metadata.gz: c0bf551ed0f381f37b44fc87d922ca5aec7bd16f7d8839388e58c557528f69110ea962125e991608fd35a0d9abb4ca149426a755c9cee5b13df6c7f9c8188504
+  data.tar.gz: e72d077a10b5161b67637ad9602df132cb753283db5b5bf6d006f172783f538ac8f6c2b56f24c06496cd2f437bd7fd6b175ec21f7e01e98e372cc17d137c69f8

data/.gitignore

@@ -0,0 +1,2 @@
+/Gemfile.lock
+/hash_control-*.gem

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format=documentation
+--tty

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+script: rspec
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - ruby-head

data/Gemfile

@@ -0,0 +1,7 @@
+source "http://rubygems.org"
+
+gem 'activesupport', '~> 4.0'
+
+group :test do
+  gem 'rspec', '~> 3.0'
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2014-2015 Sean Zhu
+
+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/Makefile

@@ -0,0 +1,15 @@
+GEM_NAME := hash_control
+
+all:
+	gem build $(GEM_NAME).gemspec
+
+install: all
+	gem install $(GEM_NAME)
+
+uninstall:
+	gem uninstall $(GEM_NAME)
+
+clean:
+	rm -fv -- $(GEM_NAME)-*.gem
+
+.PHONY: all install clean

data/README.md

@@ -0,0 +1,91 @@
+# HashControl
+
+[![Build Status](https://travis-ci.org/szhu/hashcontrol.svg?branch=master)](https://travis-ci.org/szhu/hashcontrol)
+[![Code Climate](https://codeclimate.com/github/szhu/hashcontrol/badges/gpa.svg)](https://codeclimate.com/github/szhu/hashcontrol)
+
+```shell
+gem install hash_control
+```
+
+This Ruby library provides some conveniences for using and manipulating hash-like data.
+
+## Features
+
+`HashControl::Model` is a class with
+
+ - validation checking
+ - getting and setting properties with both `[]` and accessor methods
+ - setter methods can be omitted to prevent mutation
+ - [AwesomePrint](https://github.com/michaeldv/awesome_print) support
+
+Want just a single-use validator? Use `HashControl::Validator`.
+ 
+## Examples
+
+### Model
+
+ ```ruby
+require 'hash_control'
+class Comment
+  include ::HashControl::Model
+  require_key :author, :body, :date
+  permit_key :image
+end
+
+require 'hash_control'
+class Something
+  include ::HashControl::Model
+  require_key :id
+  permit_all_keys
+end
+
+Comment.new(author: 'me', body: 'interesting stuff', date: Time.now)
+
+Comment.new(body: "this ain't gonna fly")
+# ArgumentError: extra params [:extra]
+#   in {:body=>"this ain't gonna fly", :author=>"me", :date=>2014-01-01 00:00:00 -0000, :extra=>"hullo"}
+
+Something.new(body: "this, however, will")
+# ArgumentError: required params [:id] missing
+#   in {:body=>"this, however, will"}
+
+Something.new(id: 1, body: "oops my bad")
+```
+
+### Validator
+
+```ruby
+require 'hash_control'
+get_request = {
+  get: '/api/article/23/comment/34/show'
+}
+post_request = {
+  post: '/api/article/23/comment/34/update',
+  body: {
+    date: Time.new,
+    body: 'hullo',
+    meta: 'fsdkfsifhdsfsdhkj'
+  }
+}
+validator = ::HashControl::Validator.new(post_request)
+validator.require(:post).permit(:body).only
+# `permit` marks keys as allowed but doesn't do any verification
+# `only` ensures no other keys are present
+
+class CustomValidator < ::HashControl::Validator
+  def validate_request
+    require_one_of(:get, :post)
+  end
+
+  def validate_get_request
+    validate_request.only
+  end
+
+  def validate_post_request
+    validate_request.permit(:body).only
+  end
+end
+
+CustomValidator.new(get_request).validate_get_request
+CustomValidator.new(post_request).validate_post_request
+```

data/hash_control.gemspec

@@ -0,0 +1,21 @@
+require './lib/hash_control/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = File.basename(ARGV[1], '.gemspec')
+  gem.summary       = 'Conveniently validating and manipulating hash-like data.'
+  gem.description   = <<-END
+      Provides some conveniences for validating and manipulating hash-like data.
+    END
+
+  gem.version       = ::HashControl::VERSION
+  gem.date          = '2014-08-22'
+
+  gem.homepage      = 'https://github.com/szhu/hashcontrol'
+  gem.authors       = ['Sean Zhu']
+  gem.email         = 'interestinglythere@gmail.com'
+  gem.license       = 'MIT'
+
+  gem.add_dependency 'activesupport', '~> 4.0'
+  gem.files         = `git ls-files`.split($RS)
+  gem.require_paths = ['lib']
+end

data/lib/hash_control/model.rb

@@ -0,0 +1,126 @@
+require 'active_support/core_ext/hash/indifferent_access'
+require 'active_support/hash_with_indifferent_access'
+require_relative 'validator'
+
+module HashControl
+  # An hash-like type that requires certain keys to be defined
+  module Model
+    def initialize(hash = {})
+      @hash = ::ActiveSupport::HashWithIndifferentAccess.new(hash)
+      initialize_model if self.class.method_defined? :initialize_model
+      hash_validator = validate_default
+      validate(hash_validator) if self.class.method_defined? :validate
+    end
+
+    def symbolized_hash
+      @hash.symbolize_keys
+    end
+
+    def slice(*keys)
+      @symbolized_hash.select { |key, _| keys.include? key.to_sym }
+    end
+
+    def [](name)
+      @hash[name]
+    end
+
+    private
+
+    def validate_default
+      hash_validator = Validator.new(@hash)
+      hash_validator.require(*self.class.required_keys)
+      unless self.class.permitted_keys == :all
+        hash_validator.permit(*self.class.permitted_keys).only
+      end
+      hash_validator
+    end
+
+    module ClassMethods
+      def initialize_class
+        instance_variable_set(:@required_keys, Set.new)
+        instance_variable_set(:@permitted_keys, Set.new)
+      end
+      attr_reader :required_keys, :permitted_keys
+
+      def permit_all_keys
+        @permitted_keys = :all
+      end
+
+      def require_key(*keys)
+        keys.each { |key| key_accessor(key) }
+        required_keys.merge keys
+      end
+
+      def permit_key(*keys)
+        keys.each { |key| key_accessor(key) }
+        permitted_keys.merge keys
+      end
+
+      def key_accessor(name)
+        name = name.to_sym
+        return if self.respond_to?(name)
+        class_eval do
+          define_method(name) { @hash[name] }
+        end
+      end
+    end
+
+    def self.included(base)
+      base.extend ClassMethods
+      base.initialize_class
+    end
+  end
+
+  # Allow setting
+  module WritableModel
+    include Model
+
+    module ClassMethods
+      def key_accessor(name)
+        name = name.to_sym
+        return if self.respond_to?(name)
+        class_eval do
+          define_method(name) { @hash[name] }
+          define_method("#{name}=") { |x| @hash[name] = x }
+        end
+      end
+    end
+
+    def []=(name, x)
+      @hash[name] = x
+    end
+
+    def self.included(base)
+      Model.included(base)
+      base.extend ClassMethods
+    end
+  end
+
+  # Add extra I/O
+  # Placed in a separate block for sake of clarity
+  module Model
+    # JSON support
+    module ClassMethods
+      def json_create(hash_as_json)
+        require 'json'
+        hash = JSON.parse hash_as_json
+        new hash
+      end
+    end
+
+    def to_json
+      require 'json'
+      @hash.to_json
+    end
+
+    def as_json(_opts = {})
+      symbolized_hash
+    end
+
+    # AwesomePrint support
+    def ai(options)
+      require 'awesome_print'
+      AwesomePrint::Inspector.new(options).awesome(symbolized_hash)
+    end
+  end
+end

data/lib/hash_control/validator.rb

@@ -0,0 +1,115 @@
+require 'active_support/hash_with_indifferent_access'
+require 'active_support/inflector'
+require 'set'
+
+module HashControl
+  class Validator
+    def initialize(hash, opts = {})
+      if hash.is_a? ::ActiveSupport::HashWithIndifferentAccess
+        @hash = hash
+      else
+        @hash = ::ActiveSupport::HashWithIndifferentAccess.new(hash)
+      end
+      @error_class = opts[:raising] || ArgumentError
+      @term = opts[:term] || 'param'
+      @string_keys = opts[:string_keys] || false
+      @permitted_keys = Set.new
+    end
+
+    # Specifies keys that must exist
+    def require(*keys)
+      permitted_keys.merge keys
+      required_keys = keys.to_set
+      unless (missing_keys = required_keys - hash_keys).empty?
+        error "required #{terms} #{missing_keys.to_a} missing" + postscript
+      end
+      self
+    end
+
+    def require_n_of(n, *keys)
+      permitted_keys.merge keys
+      required_keys = keys.to_set
+      if (missing_keys = required_keys - hash_keys).length > n
+        error "#{n} or more #{terms} in #{missing_keys.to_a} must be given" + postscript
+      end
+      self
+    end
+
+    def require_one_of(*keys)
+      require_n_of(1, *keys)
+    end
+
+    # Specifies keys that can exist with no further restrictions
+    # Does no checking on its own
+    def permit(*keys)
+      permitted_keys.merge keys
+      self
+    end
+
+    # Checks that only the the previously mentioned keys exist
+    # In Rails, `permit' will do this as well, but having this as a separate
+    # option allows for specifying permit not at the beginning of the chain
+    def only
+      unless (extra_keys = hash_keys - permitted_keys).empty?
+        error "extra #{terms} #{extra_keys.to_a}" + postscript
+      end
+      self
+    end
+
+    # Similar to Rails' `permit' method.
+    def permit_only(*keys)
+      permit(*keys).only
+    end
+
+    def int(*keys)
+      permitted_keys.merge keys
+      keys.each do |key|
+        next if hash[key].is_a? Integer
+        error "#{term} #{key.inspect} must be integer but was #{hash[key].inspect}" + postscript
+      end
+      self
+    end
+
+    def int_or_nil(*keys)
+      permitted_keys.merge keys
+      keys.each do |key|
+        next if hash[key].nil? || hash[key].is_a?(Integer)
+        error "#{term} #{key.inspect} must be integer but was #{hash[key].inspect}" + postscript
+      end
+      self
+    end
+
+    def not_nil(*keys)
+      permitted_keys.merge keys
+      keys.each do |key|
+        next unless hash[key].nil?
+        error "#{term} #{key.inspect} is nil" + postscript
+      end
+      self
+    end
+
+    private
+
+    def hash
+      @string_keys ? @hash : @hash.symbolize_keys
+    end
+
+    def hash_keys
+      (@string_keys ? @hash.keys : @hash.keys.map(&:to_sym)).to_set
+    end
+
+    attr_reader :permitted_keys, :term
+
+    def error(message)
+      raise @error_class, message
+    end
+
+    def postscript
+      "\n\tin #{hash.inspect}"
+    end
+
+    def terms
+      @terms ||= term.pluralize
+    end
+  end
+end

data/lib/hash_control/version.rb

@@ -0,0 +1,3 @@
+module HashControl
+  VERSION = "0.1.2"
+end

data/lib/hash_control.rb

@@ -0,0 +1,3 @@
+require_relative 'hash_control/model'
+require_relative 'hash_control/validator'
+require_relative 'hash_control/version'

data/spec/lib/hash_control/model_spec.rb

@@ -0,0 +1,96 @@
+require 'hash_control/model'
+
+describe HashControl::Model do
+  before :all do
+    class Comment
+      include ::HashControl::Model
+      require_key :author, :body, :date
+      permit_key :image
+    end
+
+    class Something
+      include ::HashControl::Model
+      require_key :id
+      permit_all_keys
+    end
+  end
+
+  describe "making an instance should error if it" do
+    it "does not permit all keys and has extra params" do
+      expect {
+        Comment.new(body: "this ain't gonna fly", author: 'me', date: Time.now, extra: 'hullo')
+      }.to raise_error(ArgumentError)
+      # ArgumentError: extra params [:extra]
+      #   in {:body=>"this ain't gonna fly", :author=>"me", :date=>2014-01-01 00:00:00 -0000, :extra=>"hullo"}
+    end
+
+    it "is missing required params" do
+      expect {
+        Something.new(body: "this won't either")
+      }.to raise_error(ArgumentError)
+      # ArgumentError: required params [:id] missing
+      #   in {:body=>"this won't either"}
+    end
+  end
+
+  describe "a valid model" do
+    describe "that permits only certain keys" do
+      before :all do
+        @comment = Comment.new(author: 'me', body: 'interesting stuff', date: Time.now)
+      end
+
+      describe "can use methods to access" do
+        it "explicitly required and permitted keys" do
+          expect(@comment.author).to eq('me')
+          expect(@comment.body).to eq('interesting stuff')
+          expect(@comment.date.class).to eq(Time)
+          expect(@comment.image).to eq(nil)
+        end
+        it "not other keys" do
+          expect{@comment.nonexistent}.to raise_error(NoMethodError)
+        end
+      end
+
+      describe "can use [] (using both string and symbol) to access" do
+        it "all keys regardless of whether they exist" do
+          expect(@comment['author']).to eq('me')
+          expect(@comment[:author]).to eq('me')
+          expect(@comment['image']).to eq(nil)
+          expect(@comment[:image]).to eq(nil)
+          expect(@comment['nonexistent']).to eq(nil)
+          expect(@comment[:nonexistent]).to eq(nil)
+        end
+      end
+
+    end
+
+    describe "that permits all keys" do
+      before :all do
+        @something = Something.new(id: 1, body: "heh")
+      end
+
+      describe "can use methods to access" do
+        it "explicitly required and permitted keys" do
+          expect(@something.id).to eq(1)
+        end
+        it "not implicitly-permitted keys" do
+          expect{@something.body}.to raise_error(NoMethodError)
+          expect{@something.nonexistent}.to raise_error(NoMethodError)
+        end
+        it "not other keys" do
+          expect{@something.body}.to raise_error(NoMethodError)
+          expect{@something.nonexistent}.to raise_error(NoMethodError)
+        end
+      end
+
+      describe "can use [] (using both string and symbol) to access" do
+        it "all keys regardless of whether they exist" do
+          expect(@something['body']).to eq('heh')
+          expect(@something[:body]).to eq('heh')
+          expect(@something['nonexistent']).to eq(nil)
+          expect(@something[:nonexistent]).to eq(nil)
+        end
+      end
+    end
+  end
+end

data/spec/lib/hash_control/validator_spec.rb

@@ -0,0 +1,83 @@
+require 'hash_control/validator'
+
+describe HashControl::Validator do
+  def validate(hash)
+    ::HashControl::Validator.new(hash)
+  end
+
+  before :all do
+    @empty = {
+    }
+    @get_request = {
+      get: '/api/article/23/comment/34/show'
+    }
+    @post_request = {
+      post: '/api/article/23/comment/34/update',
+      body: {
+        date: Time.new,
+        body: 'hullo',
+        meta: 'fsdkfsifhdsfsdhkj'
+      }
+    }
+    @not_allowed_but_currently_ok = {
+      get: 'something',
+      post: 'something_else'
+    }
+  end
+
+  describe "when used as its own class," do
+    # `require` ensures certain keys are present
+    it "require should work properly" do
+      expect{ validate(@post_request).require(:post) }.not_to raise_error
+      expect{ validate(@post_request).require(:body) }.not_to raise_error
+      expect{ validate(@post_request).require(:post, :body) }.not_to raise_error
+      expect{ validate(@post_request).require(:nonexistent) }.to raise_error(ArgumentError)
+    end
+
+    # `require_n_of` ensures at least n of certain keys are present
+    it "require_n_of should work properly" do
+      expect{ validate(@post_request).require_n_of(2, :post, :body) }.not_to raise_error
+    end
+
+    # `permit` marks keys as allowed but doesn't do any verification
+    it "permit should work properly" do
+      expect{ validate(@post_request).permit(:body) }.not_to raise_error
+      expect{ validate(@post_request).permit(:nonexistent) }.not_to raise_error
+    end
+
+    # `only` ensures no other keys are present
+    it "only should work properly" do
+      expect{ validate(@post_request).only }.to raise_error(ArgumentError)
+      expect{ validate(@post_request).require(:post).only }.to raise_error(ArgumentError)
+      expect{ validate(@post_request).require(:post).permit(:body).only }.not_to raise_error
+    end
+  end
+
+  describe "when subclassed," do
+    before :all do
+      class CustomValidator < ::HashControl::Validator
+        def validate_request
+          require_one_of(:get, :post)
+        end
+
+        def validate_get_request
+          validate_request.only
+        end
+
+        def validate_post_request
+          validate_request.permit(:body).only
+        end
+      end
+    end
+
+    it "should work properly for allowed hashes" do
+      expect{ CustomValidator.new(@get_request).validate_get_request }.not_to raise_error
+      expect{ CustomValidator.new(@post_request).validate_post_request }.not_to raise_error
+      expect{ CustomValidator.new(@not_allowed_but_currently_ok).validate_post_request }.not_to raise_error
+    end
+
+    it "should work properly for invalid hashes" do
+      expect{ CustomValidator.new(@empty).validate_get_request }.to raise_error(ArgumentError)
+    end
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: hash_control
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Sean Zhu
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-08-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: |2
+        Provides some conveniences for validating and manipulating hash-like data.
+email: interestinglythere@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE
+- Makefile
+- README.md
+- hash_control.gemspec
+- lib/hash_control.rb
+- lib/hash_control/model.rb
+- lib/hash_control/validator.rb
+- lib/hash_control/version.rb
+- spec/lib/hash_control/model_spec.rb
+- spec/lib/hash_control/validator_spec.rb
+homepage: https://github.com/szhu/hashcontrol
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Conveniently validating and manipulating hash-like data.
+test_files: []