hashformer 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b7f71daa79a2af9d68aaa378dca0748ab4e19157
+  data.tar.gz: 7f17e9b9260f1ad6cbb362a7eebf435995fb2449
+SHA512:
+  metadata.gz: 265374fe6b61f42539c24e3007ce6da1b36da296c92e6c5889325a58da6f4ac4a24f1361586cf42df6afc871be96bd0f740692b65b0d76b4c830e05b038343a0
+  data.tar.gz: daa336e0a096baebb1bab6535adb24723ac56a9c8f64ddc4513975a3920fcf4b671a91d7dabf5ebfa3ef37cfe73a877c0cd4b90e57513b366f582768b1974fca

data/.gitignore

@@ -0,0 +1,34 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,19 @@
+source 'https://rubygems.org'
+
+group :test do
+  # RSpec for tests
+  gem 'rspec'
+
+  # SimpleCov for test coverage
+  gem 'simplecov', '~> 0.7.1', require: false
+
+  # Code Climate test coverage
+  gem "codeclimate-test-reporter", require: nil
+end
+
+group :development do
+  gem 'debugger', platforms: [:ruby_19]
+  gem 'byebug', platforms: [:ruby_20, :ruby_21]
+end
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Deseret Book and Contributors
+
+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,344 @@
+Hashformer [![Code Climate](https://codeclimate.com/github/deseretbook/hashformer.png)](https://codeclimate.com/github/deseretbook/hashformer) [![Test Coverage](https://codeclimate.com/github/deseretbook/hashformer/coverage.png)](https://codeclimate.com/github/deseretbook/hashformer) [![Codeship Status for deseretbook/hashformer](https://www.codeship.io/projects/dd988da0-dee7-0131-9e92-7e1ff0bec112/status?branch=master)](https://www.codeship.io/projects/24888)
+=========
+
+### Transform any Ruby Hash with a declarative DSL
+
+Hashformer is the ultimate Ruby Hash transformation tool, made from 100% pure
+Hashformium (may contain trace amounts of caffeine).  It provides a simple,
+Ruby Hash-based DSL for transforming data from one format to another.  It's
+vaguely like XSLT, but way less complicated and way more Ruby.
+
+You specify Hash to Hash transformations using a Hash with a list of output
+keys, input keys, and transformations, and Hashformer will convert your data
+into the format you specify.  It can also help verify your transformations by
+validating input and output data using [Classy Hash](https://github.com/deseretbook/classy_hash).
+
+
+### Examples
+
+#### Basic renaming
+
+If you just need to move/copy/rename keys, you specify the source key as the
+value for the destination key in your transformation:
+
+```ruby
+data = {
+  'first_name' => 'Hash',
+  'last_name' => 'Former'
+}
+xform = {
+  first: 'first_name',
+  last: 'last_name'
+}
+
+Hashformer.transform(data, xform)
+# => {first: 'Hash', last: 'Former'}
+```
+
+Just about any source key type will work:
+
+```ruby
+data = {
+  0 => 'Nothing',
+  1 => 'Only One'
+}
+xform = {
+  zero: 0,
+  one: 1
+}
+
+Hashformer.transform(data, xform)
+# => {zero: 'Nothing', one: 'Only One'}
+```
+
+
+#### Nested values
+
+If you need to grab values from a Hash or Array within a Hash, you can use
+`Hashformer::Generate.path` (or, the convenient shortcut, `HF::G.path`):
+
+```ruby
+data = {
+  name: 'Hashformer',
+  addresses: [
+    {
+      line1: 'Hash',
+      line2: 'Former'
+    }
+  ]
+}
+xform = {
+  name: :name,
+  line1: HF::G.path[:addresses][0][:line1],
+  line2: HF::G.path[:addresses][0][:line2]
+}
+
+Hashformer.transform(data, xform)
+# => {name: 'Hashformer', line1: 'Hash', line2: 'Former'}
+```
+
+If you try to access beyond a path that doesn't exist, nil will be returned
+instead:
+
+```ruby
+data = {
+  a: { b: 'c' }
+}
+xform = {
+  a: HF::G.path[:a][0][:c]
+}
+
+Hashformer.transform(data, xform)
+# => {a: nil}
+```
+
+If no path is specified, the entire Hash will be returned:
+
+```ruby
+data = {
+  a: 1,
+  b: 2
+}
+xform = {
+  h: HF::G.path
+}
+
+Hashformer.transform(data, xform)
+# => {h: {a: 1, b: 2}}
+```
+
+
+#### Method chaining
+
+This is the most useful and powerful aspect of Hashformer.  You can use
+`HF::G.chain`, or the shortcut `HF[]`, to chain method calls and Array or Hash
+lookups:
+
+**Note:** *Method chaining may not work as expected if entered in `irb`, because
+`irb` might try to call `#to_s` or `#inspect` on the method chain!*
+
+```ruby
+data = {
+  s: 'Hashformer',
+  v: [1, 2, 3, 4, 5]
+}
+xform = {
+  s: HF[:s].reverse.capitalize,
+  # It's important to call clone before calling methods that modify the array
+  v: HF[:v].clone.concat([6]).map{|x| x * x}.reduce(0, &:+)
+}
+
+Hashformer.transform(data, xform)
+# => {s: 'Remrofhsah', v: 91}
+```
+
+Unlike `HF::g.path`, `HF[]`/`HF::G.chain` will raise an exception if you try to
+access beyond a path that doesn't exist:
+
+```ruby
+data = {
+  a: [1, 2, 3]
+}
+xform = {
+  a: HF[:b][0]
+}
+
+Hashformer.transform(data, xform)
+# Raises "undefined method `[]' for nil:NilClass"
+```
+
+`HF[]` or `HF::G.chain` without any methods or references will return the input
+Hash:
+
+```ruby
+data = {
+  a: 1
+}
+xform = {
+  a: HF[].count,
+  b: HF::G.chain
+}
+
+Hashformer.transform(data, xform)
+# => {a: 1, b: {a: 1}}
+```
+
+Although it's not recommended, you can also chain operators as long as `HF[]`
+is the first element evaluated by Ruby:
+
+```ruby
+xform = {
+  x: -(HF[:x] * 2) + 5
+}
+
+Hashformer.transform({x: 3}, xform)
+# => {x: -1}
+
+Hashformer.transform({x: -12}, xform)
+# => {x: 29}
+```
+
+
+#### Mapping one or more values
+
+If you want Hashformer to gather one or more values for you and either place
+them in an Array or pass them to a lambda, you can use `HF::G.map`.  Pass the
+names of the keys to map as parameters, followed by the optional Proc or
+lambda:
+
+```ruby
+data = {
+  a: 'Hashformer'
+}
+xform = {
+  a: HF::G.map(:a, &:upcase),
+  b: HF::G.map(:a)
+}
+
+Hashformer.transform(data, xform)
+# => {a: 'HASHFORMER', b: ['Hashformer']}
+```
+
+You can also mix and match paths and method chains in the `HF::G.map`
+parameters:
+
+```ruby
+data = {
+  items: [
+    {name: 'Item 1', price: 1.50},
+    {name: 'Item 2', price: 2.50},
+    {name: 'Item 3', price: 3.50},
+    {name: 'Item 4', price: 4.50},
+  ],
+  shipping: 5.50
+}
+xform = {
+  item_total: HF[:items].map{|i| i[:price]}.reduce(0.0, &:+),
+  total: HF::G.map(HF[:items].map{|i| i[:price]}.reduce(0.0, &:+), HF::G.path[:shipping], &:+)
+}
+
+Hashformer.transform(data, xform)
+# => {item_total: 12.0, total: 17.5}
+```
+
+
+#### Lambda processing
+
+If you need to apply a completely custom transformation to your data, you can
+use a raw lambda.  The lambda will be called with the entire input Hash.
+
+```ruby
+data = {
+  x: 3.0,
+  y: 4.0
+}
+xform = {
+  radius: ->(h){ Math.sqrt(h[:x] * h[:x] + h[:y] * h[:y]) }
+}
+
+Hashformer.transform(data, xform)
+# => {radius: 5.0}
+```
+
+
+#### Dynamic key names
+
+There might not be much use for it, but you can use a lambda as a key as well.
+It will be called with its associated unprocessed value and the input Hash:
+
+```ruby
+data = {
+  key: :x,
+  value: 0
+}
+xform = {
+  ->(value, h){h[:key]} => :value
+}
+
+Hashformer.transform(data, xform)
+# => {x: 0}
+```
+
+
+#### Practical example with validation
+
+Suppose your application receives addresses in one format, but you need to pass
+them along in another format.  You might need to rename some keys, convert some
+keys to different types, merge keys, etc.  We'll define the input and output
+data formats using [Classy Hash schemas](https://github.com/deseretbook/classy_hash#simple-example).
+
+```ruby
+# Classy Hash schema - https://github.com/deseretbook/classy_hash
+in_schema = {
+  # Totally violates http://www.kalzumeus.com/2010/06/17/falsehoods-programmers-believe-about-names/
+  first: String,
+  last: String,
+  city: String,
+  phone: String,
+}
+
+out_schema = {
+  name: String,
+  location: String,
+  phone: Integer, # Just for example; probably shouldn't make phone numbers integers
+}
+```
+
+You can write a Hashformer transformation to turn any Hash with the `in_schema`
+format into a Hash with the `out_schema` format, and verify the results:
+
+```ruby
+# Hashformer transformation - https://github.com/deseretbook/hashformer
+xform = {
+  # Validate input and output data according to the Classy Hash schemas
+  __in_schema: in_schema,
+  __out_schema: out_schema,
+
+  # Combine first and last name into a single String
+  name: HF::G.map(:first, :last) {|f, l| "#{f} #{l}".strip},
+
+  # Copy the :city field directly into :location
+  location: :city,
+
+  # Remove non-digits from :phone
+  phone: HF[:phone].gsub(/[^\d]/, '').to_i
+}
+
+data = {
+  first: 'Hash',
+  last: 'Transformed',
+  city: 'Here',
+  phone: '555-555-5555',
+}
+
+Hashformer.transform(data, xform)
+# => {name: 'Hash Transformed', location: 'Here', phone: 5555555555}
+```
+
+
+### Testing
+
+Hashformer includes a thorough [RSpec](http://rspec.info) test suite:
+
+```bash
+# Execute within a clone of the Git repository:
+bundle install --without=development
+rspec
+```
+
+
+### Alternatives
+
+Hashformer just might be the coolest Ruby Hash data transformer out there.  But
+if you disagree, here are some other options:
+
+- [hash_transformer](https://github.com/trampoline/hash_transformer) provides
+  an *imperative* DSL for Hash modification.
+- [ActiveModel::Serializers](https://github.com/rails-api/active_model_serializers)
+- [XSLT](https://en.wikipedia.org/wiki/Xslt)
+
+
+### License
+
+Hashformer is released under the MIT license (see the `LICENSE` file for the
+license text and copyright notice).

data/hashformer.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'hashformer/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "hashformer"
+  spec.version       = Hashformer::VERSION
+  spec.authors       = ['Deseret Book', 'Mike Bourgeous']
+  spec.email         = ["mike@mikebourgeous.com"]
+  spec.summary       = 'Transform any Hash with a declarative data transformation DSL for Ruby'
+  spec.description   = <<-DESC
+    Hashformer provides a simple, Ruby Hash-based way of transforming data from
+    one format to another.  It's vaguely like XSLT, but way less complicated
+    and way more Ruby.
+    DESC
+  spec.homepage      = "https://github.com/deseretbook/hashformer"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = '>= 1.9.3'
+
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_runtime_dependency "classy_hash", "~> 0.1", ">= 0.1.1"
+end

data/lib/hashformer/generate.rb

@@ -0,0 +1,177 @@
+# Hashformer transformation generators
+# Created July 2014 by Mike Bourgeous, DeseretBook.com
+# Copyright (C)2014 Deseret Book
+# See LICENSE and README.md for details.
+
+require 'classy_hash'
+
+module Hashformer
+  # This module contains simple methods for generating complex transformations
+  # for Hashformer.
+  module Generate
+    # Internal representation of a mapping transformation.  Do not instantiate
+    # directly; call Hashformer::Generate.map (or HF::G.map) instead.
+    class Map
+      def initialize(*keys_or_callables, &block)
+        @keys = keys_or_callables
+        @block = block
+      end
+
+      # Called to process the map on the given +input_hash+
+      def call(input_hash)
+        values = @keys.map{|k| Hashformer.get_value(input_hash, k)}
+        values = @block.call(*values) if @block
+        values
+      end
+    end
+
+    # Internal representation of a path to a nested key/value.  Do not
+    # instantiate directly; call Hashformer::Generate.path (or HF::G.path)
+    # instead.
+    class Path
+      def initialize
+        @pathlist = []
+      end
+
+      # Called to dereference the path on the given +input_hash+.
+      def call(input_hash)
+        begin
+          value = input_hash
+          @pathlist.each do |path_item|
+            value = value && value[path_item]
+          end
+          value
+        rescue => e
+          raise "Error dereferencing path #{self}: #{e}"
+        end
+      end
+
+      # Adds a path item to the end of the saved path.
+      def [](path_item)
+        @pathlist << path_item
+        self
+      end
+
+      def to_s
+        @pathlist.map{|p| "[#{p.inspect}]"}.join
+      end
+    end
+
+    # Internal representation of a method call and array lookup chainer.  Do
+    # not use this directly; instead use HF::G.chain().
+    class Chain
+      # Receiver for chaining calls that has no methods of its own except
+      # initialize.  This allows methods like :call to be chained.
+      #
+      # IMPORTANT: No methods other than .__chain can be called on this object,
+      # because they will be chained!  Instead, use === to detect the object's
+      # type, for example.
+      class Receiver < BasicObject
+        # An oddly named accessor is used instead of #initialize to avoid
+        # conflicts with any methods that might be chained.
+        attr_accessor :__chain
+
+        # Adds a method call or array dereference to the list of calls to apply.
+        def method_missing(name, *args, &block)
+          @__chain << {name: name, args: args, block: block}
+          self
+        end
+
+        undef !=
+        undef ==
+        undef !
+        undef instance_exec
+        undef instance_eval
+        undef equal?
+        undef singleton_method_added
+        undef singleton_method_removed
+        undef singleton_method_undefined
+      end
+
+      # Returns the call chaining receiver.
+      attr_reader :receiver
+
+      def initialize
+        @calls = []
+        @receiver = Receiver.new
+        @receiver.__chain = self
+      end
+
+      # Applies the methods stored by #method_missing
+      def call(input_hash)
+        value = input_hash
+        @calls.each do |c|
+          value = value.send(c[:name], *c[:args], &c[:block])
+        end
+        value
+      end
+
+      # Adds the given call info (used by Receiver).
+      def <<(info)
+        @calls << info
+        self
+      end
+    end
+
+    # Generates a transformation that passes one or more values from the input
+    # Hash (denoted by key names or paths (see Hashformer::Generate.path) to
+    # the block.  If the block is not given, then the values are placed in an
+    # array in the order in which their keys were given as parameters.
+    #
+    # Examples:
+    #   HF::G.map(:first, :last) do |f, l| "#{f} #{l}".strip end
+    #   HF::G.map(:a1, :a2) # Turns {a1: 1, a2: 2} into [1, 2]
+    #   HF::G.map(HF::G.path[:address][:line1], HF::G.path[:address][:line2])
+    def self.map(*keys_or_paths, &block)
+      Map.new(*keys_or_paths, &block)
+    end
+
+    # Generates a path reference (via Path#[]) that grabs a nested value for
+    # use directly or in other transformations.  If no path is specified, the
+    # transformation will use the input hash.
+    #
+    # When the path is dereferenced, if any of the parent elements referred to
+    # by the path are nil, then nil will be returned.  If any path elements do
+    # not respond to [], or otherwise raise an exception, then an exception
+    # will be raised by the transformation.
+    #
+    # The major difference between .path and .chain is that .path will return
+    # nil if a nonexistent key is referenced (even multiple times), while
+    # .chain will raise an exception.
+    #
+    # Examples:
+    #   HF::G.path[:user][:address][:line1]
+    #   HF::G.path[:lines][5]
+    def self.path
+      Path.new
+    end
+
+    # Generates a method call chain to apply to the input hash given to a
+    # transformation.  This allows path references (as with HF::G.path) and
+    # method calls to be stored and applied later.
+    #
+    # Example:
+    #   data = { in1: { in2: [1, 2, 3, [4, 5, 6, 7]] } }
+    #   xform = { out1: HF::G.chain[:in1][:in2][3].reduce(&:+) }
+    #   Hashformer.transform(data, xform) # Returns { out1: 22 }
+    def self.chain
+      Chain.new.receiver
+    end
+  end
+
+  # Shortcut to Hashformer::Generate
+  G = Generate
+
+  # Convenience method for calling HF::G.chain() to generate a path reference
+  # and/or method call chain.  If the initial +path_item+ is not given, then
+  # the method chain will start with the input hash.  Chaining methods that
+  # have side effects or modify the underlying data is not recommended.
+  #
+  # Example:
+  #   data = { in1: { in2: ['a', 'b', 'c', 'd'] } }
+  #   xform = { out1: HF[:in1][:in2][3], out2: HF[].count }
+  #   Hashformer.transform(data, xform) # Returns { out1: 'd', out2: 1 }
+  def self.[](path_item = :__hashformer_not_given)
+    path_item == :__hashformer_not_given ? HF::G.chain : HF::G.chain[path_item]
+  end
+end

data/lib/hashformer/version.rb

@@ -0,0 +1,3 @@
+module Hashformer
+  VERSION = "0.2.0"
+end