hashstructor 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1c5ba11f6bea507eada8ffef440f9c0ab35335ba
+  data.tar.gz: cfa2de7abfece15ca53d8814efc5a8d5699b9934
+SHA512:
+  metadata.gz: c9d4e04bfe0737b868d16c8cc99250f10a195c8492f5b652a86e731b0c79e0efe62280c0715a80925b7b6e79bf37c68ffe4a03b3c102bbf4e0d92ed1932f5109
+  data.tar.gz: 7b50b74f329a59862be978b0657e1aa4bd4afa6cbbb0673ce01b11f07e354dc29bd9e4820dc4a6c7c70702d436a131f4b268e94fe87d7f869c975e9b754c4514

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.1
+before_install: gem install bundler -v 1.10.5

data/.yardopts

@@ -0,0 +1 @@
+--private --list-undoc --markup markdown - LICENSE.md

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Ed Ropple
+
+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,47 @@
+# Hashstructor
+
+There comes a time in every wee programmer's life (and all programmers are, for the purposes of this readme, wee or previously wee) when one must take a big blob of JSON or YAML and make it into an object. Or worse, a hierarchy of objects. This leads to lots of very manual parsing and gnashing of teeth. Some libraries, like the mildly spiffy [constructor](https://github.com/atomicobject/constructor), allow you to defray some of this pain by letting you pass in hashes to build objects, but this only goes so far: no type coercion, no nested types.
+
+Finally I got tired of this mess when building a game prototype and writing enough stupid read-in code of data files that I decided to Fix This Situation. (You can argue that I got sidetracked; I won't disagree.) After about three hours of late-night work, I'm somewhat proud to unveil **Hashstructor**: your one-stop shop for mangling the heck out of Ruby hashes and building neat-o object trees out of them. (The reverse, breaking these data structures down into hashes, is a TODO.)
+
+Hashstructor is _fully documented_ (100% coverage in `yard`) and comes with a fairly exhaustive set of tests to prove that it actually does what it's supposed to do.
+
+## Installation ##
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hashstructor'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install hashstructor
+
+## Usage ##
+
+Hashstructor is pretty easy to deal with, but it's 2:10AM as I write this and I am very tired, so I shall direct you to the [fancy and/or schmancy](https://github.com/eropple/hashstructor/tree/master/spec) `spec` folder. In `test_classes` you will find examples of nearly every aspect of Hashstructor, and `hashstructor_spec.rb` explains them with a little context.
+
+YARD documentation is hosted at http://eropple.github.io/hashstructor .
+
+Hashstructor is designed for Ruby 2.0 and above, but _may_ run on Ruby 1.9.x; failure to do so is not a bug.
+
+## Development ##
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing ##
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/eropple/hashstructor. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
+
+
+## License ##
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "hashstructor"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/hashstructor.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'hashstructor/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "hashstructor"
+  spec.version       = Hashstructor::VERSION
+  spec.authors       = ["Ed Ropple"]
+  spec.email         = ["ed@edropple.com"]
+
+  spec.summary       = %q{A Ruby DSL and parser for converting hashes into trees of data objects.}
+  spec.homepage      = "https://github.com/eropple/hashstructor"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "yard"
+end

data/lib/hashstructor/class_methods.rb

@@ -0,0 +1,22 @@
+require 'hashstructor/member'
+
+module Hashstructor
+  # Class methods for {Hashstructor} objects.
+  module ClassMethods
+    # @return [Array<Member>] all Hashstructor members for this class (frozen)
+    def hashstructor_members
+      @hashstructor_members.freeze
+    end
+
+    private
+    # Defines a Hashstructor member to be placed on this object. See
+    # {Member}'s documentation for expected values.
+    def member(name, options = {})
+      options[:member_type] ||= :normal
+
+      options[:required] = !!(options[:required])
+
+      @hashstructor_members << Hashstructor::Member.new(self, name, options).freeze
+    end
+  end
+end

data/lib/hashstructor/instance_methods.rb

@@ -0,0 +1,70 @@
+require 'set'
+
+module Hashstructor
+  # Instance methods for {Hashstructor} objects.
+  module InstanceMethods
+    private
+    # Initializes the object. This exists for objects that `prepend`
+    # {Hashstructor}; objects that `include` it must explicitly invoke
+    # {#hashstruct} within their own `initialize` method.
+    #
+    # @param hash [Hash] the hash from which to parse the object data
+    def initialize(hash)
+      hashstruct(hash)
+    end
+
+    # Constructs the object from the given hash, based on the metadata fed
+    # in by {ClassMethods#member} invocations.
+    #
+    # @param hash [Hash] the hash from which to parse the object data
+    def hashstruct(hash)
+      raise HashstructorError, "hashstruct expects a hash." unless hash.is_a?(Hash)
+
+      members = self.class.hashstructor_members
+
+      # This could be done inline, but I'd rather loop twice and get this check
+      # out of the way ahead of time because of the perf hit when dealing with
+      # deeply nested structures.
+      partitioned_members = members.partition { |m| hash[m.name] || hash[m.name.to_s] }
+
+      existing_members = partitioned_members[0]
+      missing_members = partitioned_members[1]
+      raise HashstructorError, "Missing required members: #{missing_members.map { |m| m.name }.join(", ")}" \
+        if missing_members.any? { |m| m.required }
+
+      existing_members.each do |member|
+        raw_value = hash[member.name] || hash[member.name.to_s]
+        out_value = nil
+
+        case member.member_type
+        when :normal
+          raise HashstructorError, "member '#{member.name}' expects a single value, got #{raw_value.class.name}." \
+            if member.options[:no_collections] && raw_value.is_a?(Enumerable)
+
+          out_value = member.parse_single(raw_value)
+
+        when :hash
+          raise HashstructorError, "member '#{member.name}' expects a Hash, got #{raw_value.class.name}." \
+            unless raw_value.is_a?(Hash)
+
+          out_value = {}
+          raw_value.each_pair do |k, v|
+            key = member.options[:string_keys] ? k.to_s : k.to_s.to_sym
+
+            out_value[key] = member.parse_single(v)
+          end
+
+        when :array, :set
+          raise HashstructorError, "member '#{member.name}' expects an Enumerable, got #{raw_value.class.name}"\
+            unless raw_value.is_a?(Enumerable)
+
+          out_value = raw_value.map { |v| member.parse_single(v) }
+
+          out_value = out_value.to_set if member.member_type == :set
+        end
+
+        instance_variable_set("@#{member.name}", out_value)
+      end
+    end
+  end
+end

data/lib/hashstructor/member.rb

@@ -0,0 +1,138 @@
+module Hashstructor
+  # A member within a Hashstructor class that should be populated by the hash
+  # passed into {Hashstructor#initialize}.
+  class Member
+    # The allowed {#member_type}s for a `Member`:
+    #
+    # - `:normal` - a normal value. raises error if hash or array given unless
+    #               the `:no_collections` option is set.
+    # - `:hash` - a hash, with all keys symbolized unless the `:string_keys`
+    #             option is set.
+    # - `:array` - an array
+    # - `:set` - a set
+    #
+    # Note that these types refer to the "collection status" of the member. A
+    # `:normal` member will happily accept any value unless a `:custom_type`
+    # option is passed.
+    VALID_MEMBER_TYPES = [ :normal, :hash, :set, :array ].freeze
+
+    # @return [Symbol] the name of the member, in the parsed hash.
+    attr_reader :name
+
+    # @return [Symbol] the type of the member; see {VALID_MEMBER_TYPES}.
+    attr_reader :member_type
+
+    # A hash of Class => Proc converters for value types. Any value type
+    # in this list, as well as any class that includes or prepends
+    # `Hashstructor`, is valid for {#value_type}. This is _intentionally_
+    # not frozen; if you want to extend it for your own use cases, I'm not
+    # going to get in your way.
+    VALID_VALUE_TYPES = {
+      String => Proc.new do |v|
+        v.to_s
+      end,
+      Symbol => Proc.new do |v|
+        v.to_sym
+      end,
+      Integer => Proc.new do |v|
+        Integer(v.to_s)
+      end,
+      Float => Proc.new do |v|
+        Float(v.to_s)
+      end,
+      TrueClass => Proc.new do |v|
+        !!v
+      end,
+      FalseClass => Proc.new do |v|
+        !!v
+      end,
+    }
+    # Determines the class that Hashstructor should attempt to coerce a
+    # given value into. For example, `Fixnum` will attempt to coerce a
+    # scalar value into a `Fixnum`.
+    #
+    # The valid types for {#value_type} are:
+    #
+    # - `String`
+    # - `Symbol`
+    # - `Integer`
+    # - `Float`
+    # - `TrueClass` or `FalseClass` (for booleans)
+    # - any class that includes or prepends `Hashstructor`
+    #
+    # @return [(nil, Class)] the type of the value stored in this member.
+    attr_reader :value_type
+
+    @required = false
+    # If true, attempting to construct this object without setting this
+    # member will raise an error.
+    attr_reader :required
+
+    # Specifies what type of attr (nil, `:reader`, or `:accessor`) that this
+    # member should define on its class.
+    #
+    # @return [(nil, :reader, :accessor)] the type of attr to create.
+    attr_reader :attr_kind
+
+    # @return [Hash] a (frozen) set of all extra options passed to the member.
+    attr_reader :options
+
+    def initialize(klass, name, options)
+      member_type = options[:member_type] || :normal
+      options.delete(:member_type)
+      value_type = options[:value_type]
+      options.delete(:value_type)
+      required = !!(options[:required])
+      options.delete(:required)
+      attr_kind = options[:attr_kind]
+      options.delete(:attr_kind)
+
+      @options = options.freeze
+
+      raise HashstructorError, "'name' must respond to :to_sym." unless name.respond_to?(:to_sym)
+      @name = name.to_sym
+
+      raise HashstructorError, "'member_type' (#{member_type}) must be one of: [ #{VALID_MEMBER_TYPES.join(", ")} ]" \
+        unless VALID_MEMBER_TYPES.include?(member_type.to_sym)
+
+      @member_type = member_type.to_sym
+
+      raise HashstructorError, "'value_type' must be nil or a Class." \
+        unless value_type == nil || value_type.is_a?(Class)
+      raise HashstructorError, "'value_type' class, #{value_type.name}, must be in " +
+            "VALID_VALUE_TYPES ([ #{VALID_VALUE_TYPES.keys.map { |c| c.name}.join(", ")} ]) " +
+            "or include or prepend Hashstructor." \
+        unless value_type == nil || VALID_VALUE_TYPES[value_type] != nil || value_type.ancestors.include?(Hashstructor)
+
+      @value_type = value_type
+
+      @required = required
+
+      case attr_kind
+      when nil
+        # do nothing
+      when :reader
+        klass.send(:attr_reader, @name)
+      when :accessor
+        klass.send(:attr_accessor, @name)
+      else
+        raise HashstructorError, "Unrecognized attr_kind: #{attr_kind}"
+      end
+      @attr_kind = attr_kind
+    end
+
+    # Parses the passed-in value (always a single item; {InstanceMethods#hashstruct} handles
+    # the breaking down of arrays and hashes) and returns a value according to {#value_type}.
+    def parse_single(value)
+      if value_type.nil?
+        value
+      elsif value_type.ancestors.include?(Hashstructor)
+        raise HashstructorError, "No hash provided for building a Hashstructor object." unless value.is_a?(Hash)
+
+        value_type.new(value)
+      else
+        VALID_VALUE_TYPES[value_type].call(value)
+      end
+    end
+  end
+end

data/lib/hashstructor/version.rb

@@ -0,0 +1,4 @@
+module Hashstructor
+  # The gem version. As one does.
+  VERSION = "1.0.0"
+end

data/lib/hashstructor.rb

@@ -0,0 +1,40 @@
+require "hashstructor/version"
+
+module Hashstructor
+  # You made Hashstructor sad and now you have this error.
+  class HashstructorError < RuntimeError
+  end
+end
+
+require "hashstructor/instance_methods"
+require "hashstructor/class_methods"
+
+# Allows the "hashstruction" of objects by predefining an {Hashstructor#initialize}
+# method off of the {Hashstructor::InstanceMethods#member} declarations within the
+# class spec.
+#
+# The secret sauce for this module is in {Hashstructor::InstanceMethods} and
+# {Hashstructor::ClassMethods}, respectively.
+module Hashstructor
+  prepend Hashstructor::InstanceMethods
+
+  # Fires when this module is `prepend`ed. This is the most cromulent way to
+  # use Hashstructor in Ruby 2.x.
+  def self.prepended(mod)
+    Hashstructor.decorate(mod)
+  end
+
+  # Fires when this module is `include`d. This is provided for Ruby 1.9.x, but
+  # classes that `include` this have to explicitly invoke
+  # {Hashstructor::InstanceMethods#hashstruct}.
+  def self.included(mod)
+    Hashstructor.decorate(mod)
+  end
+
+  # The actual magic of both {Hashstructor#prepended} and {Hashstructor#included};
+  # bolts the class methods onto the prepending/including module.
+  def self.decorate(mod)
+    mod.instance_variable_set("@hashstructor_members", [])
+    mod.extend(Hashstructor::ClassMethods)
+  end
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: hashstructor
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Ed Ropple
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-07-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- ed@edropple.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- ".yardopts"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- hashstructor.gemspec
+- lib/hashstructor.rb
+- lib/hashstructor/class_methods.rb
+- lib/hashstructor/instance_methods.rb
+- lib/hashstructor/member.rb
+- lib/hashstructor/version.rb
+homepage: https://github.com/eropple/hashstructor
+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.4.6
+signing_key: 
+specification_version: 4
+summary: A Ruby DSL and parser for converting hashes into trees of data objects.
+test_files: []
+has_rdoc: