hashformer 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2477c5b2c20be0b81ccdc1927dc3e8ef64adcd2c
-  data.tar.gz: a3b05c569f07c787f55507a358bae3c5e96a3216
+  metadata.gz: cfc27e5ad9d2e3e9869c1f0095821e63553fefdf
+  data.tar.gz: 51b608ef72f5494b086d0e1853f73b0044ed0462
 SHA512:
-  metadata.gz: abb82bae7bb0aa0ef61204f2d8e3b96a695852c277f612bfaabdf88e99ce87ad84f036d530b0a74da611bab6822e438703125b12126887365876b92da9e99ff1
-  data.tar.gz: 70e6040079778f287cd9981eb9b815e2b97895560b0f8bf17fdc60a168362ac0fefdbc85da132a8933caf7a57f7579619b4624758a8fd189571e5415ca4cbeec
+  metadata.gz: f493351b32ba8a4c35db7d6b027300e475846181a6a6187a19a3b2c66205d773a4033729c4328a15b8d67965834268ea9abd6158008dae45eb23239c4b78e1df
+  data.tar.gz: b580f15b4ef7056065904841b8ed57656b1447c9c0ee39d0334d1aa51079e212747e45f1049590ef9143e1eeacedb2b7d02c36579b1c026881be45ce29301df2

data/README.md

@@ -53,7 +53,7 @@ Hashformer.transform(data, xform)
 ```
 
 
-#### Nested values
+#### Nested *input* 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`):
@@ -109,14 +109,45 @@ Hashformer.transform(data, xform)
 ```
 
 
+#### Constant values
+
+If you need to specify a constant value in your output Hash in version 0.2.2 or
+later, use `HF::G.const()`:
+
+```ruby
+data = {
+  irrelevant: 'data',
+}
+xform = {
+  data: HF::G.const(:irrelevant)
+}
+
+Hashformer.transform(data, xform)
+# => {data: :irrelevant}
+```
+
+Most types will work with `HF::G.const()`:
+
+```ruby
+data = {
+}
+xform = {
+  out: HF::G.const({a: 1, b: 2, c: [3, 4, 5]})
+}
+
+Hashformer.transform(data, xform)
+# => {out: {a: 1, b: 2, c: [3, 4, 5]}}
+```
+
+
 #### 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!*
+_**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 = {
@@ -222,6 +253,9 @@ Hashformer.transform(data, xform)
 # => {item_total: 12.0, total: 17.5}
 ```
 
+Finally, you can pass a transformation specification Hash as one or more of the
+parameters to `HF::G.map`.  See the RSpec tests for an example.
+
 
 #### Lambda processing
 
@@ -261,6 +295,59 @@ Hashformer.transform(data, xform)
 ```
 
 
+#### Nested *output* values
+
+As of Hashformer 0.2.2, you can also nest transformations within
+transformations to generate a Hash for an output value:
+
+```ruby
+data = {
+  a: 1,
+  b: 2,
+  c: 3
+}
+xform = {
+  a: {
+    all: ->(orig){ orig },
+  },
+  b: {
+    x: :a,
+    y: :b,
+    z: :c,
+  }
+}
+
+Hashformer.transform(data, xform)
+# => {a: { all: { a: 1, b: 2, c: 3 } }, b: { x: 1, y: 2, z: 3 }}
+```
+
+Nested transformations will still refer to the original input Hash, rather than
+any input key of the same name.  That way any value from the input can be used
+at any point in the output:
+
+```ruby
+data = {
+  a: 1,
+  b: {
+    a: 2,
+    b: 3,
+    c: 4
+  },
+  c: 5
+}
+xform = {
+  b: {
+    n: :a,             # Refers to the top-level :a
+    o: HF[:b][:a],     # Refers to the :a within :b
+    p: ->(h){ h[:c] }, # Refers to the top-level :c
+  }
+}
+
+Hashformer.transform(data, xform)
+# => {b: { n: 1, o: 2, p: 5 }}
+```
+
+
 #### Practical example with validation
 
 Suppose your application receives addresses in one format, but you need to pass

data/lib/hashformer/generate.rb

@@ -121,13 +121,32 @@ module Hashformer
       alias inspect to_s
     end
 
-    # TODO: Add a constant generator (that can be chained?)
+    # Internal representation of a constant output value.  Do not instantiate
+    # directly; call Hashformer::Generate.const (or HF::G.const) instead.
+    class Constant
+      attr_reader :value
+
+      def initialize(value)
+        @value = value
+      end
+    end
+
+
+    # Generates a transformation that always returns a constant value.
+    #
+    # Examples:
+    #   HF::G.const(5)
+    def self.const(value)
+      Constant.new(value)
+    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.
     #
+    # You can also pass a Hashformer transformation Hash as one or more keys.
+    #
     # 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]

data/lib/hashformer/version.rb

@@ -1,3 +1,3 @@
 module Hashformer
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

data/lib/hashformer.rb

@@ -9,20 +9,21 @@ require 'hashformer/version'
 require 'hashformer/generate'
 
 
-# This module contains the Hashformer methods for transforming Ruby Hash objects
-# from one form to another.
+# This module contains the Hashformer methods for transforming Ruby Hash
+# objects from one form to another.
 #
 # See README.md for examples.
 module Hashformer
   # Transforms +data+ according to the specification in +xform+.  The
   # transformation specification in +xform+ is a Hash specifying an input key
-  # name (e.g. a String or Symbol) or transforming lambda for each output key
-  # name.  If +validate+ is true, then ClassyHash::validate will be used to
-  # validate the input and output data formats against the :@__in_schema and
-  # :@__out_schema keys within +xform+, if specified.
+  # name (e.g. a String or Symbol), generator, or transforming lambda for each
+  # output key name.  If +validate+ is true, then ClassyHash::validate will be
+  # used to validate the input and output data formats against the
+  # :@__in_schema and :@__out_schema keys within +xform+, if specified.
   #
-  # Nested transformations can be specified by calling Hashformer::transform
-  # again inside of a lambda.
+  # Nested transformations can be specified by using a Hash as the
+  # transformation value, or by calling Hashformer.transform again inside of a
+  # lambda.
   #
   # If a value in +xform+ is a Proc, the Proc will be called with the input
   # Hash, and the return value of the Proc used as the output value.
@@ -46,7 +47,7 @@ module Hashformer
       next if key == :__in_schema || key == :__out_schema
 
       key = key.call(value, data) if key.respond_to?(:call)
-      out[key] = self.get_value(data, value)
+      out[key] = self.get_value(data, value, xform)
     end
 
     validate(out, xform[:__out_schema], 'output') if validate
@@ -55,18 +56,21 @@ module Hashformer
   end
 
   # Returns a value for the given +key+, method chain, or callable on the given
-  # +input_hash+.
-  def self.get_value(input_hash, key)
+  # +input_hash+.  If +xform+ is not nil, then Hashe keys will be processed
+  # with Hashformer.transform.
+  def self.get_value(input_hash, key, xform = nil)
     if Hashformer::Generate::Chain::Receiver === key
       # Had to special case chains to allow chaining .call
       key.__chain.call(input_hash)
+    elsif Hashformer::Generate::Constant === key
+      key.value
     elsif key.respond_to?(:call)
       key.call(input_hash)
+    elsif key.is_a?(Hash)
+      transform(input_hash, key)
     else
       input_hash[key]
     end
-
-    # TODO: add support for nested output hashes
   end
 
   private

data/spec/lib/hashformer/generate_spec.rb

@@ -8,6 +8,28 @@ require 'spec_helper'
 require 'hashformer'
 
 RSpec.describe Hashformer::Generate do
+  describe '.const' do
+    let(:data) {
+      {}
+    }
+
+    it 'returns the original integer when given an integer' do
+      expect(Hashformer.transform({}, { a: HF::G.const(5) })).to eq({a: 5})
+    end
+
+    it 'returns the original array when given an array' do
+      expect(Hashformer.transform({a: 1}, { a: HF::G.const([1, 2, :three]) })).to eq({a: [1, 2, :three]})
+    end
+
+    it 'returns a symbol when given a symbol' do
+      expect(Hashformer.transform({q: nil}, { a: HF::G.const(:q) })).to eq({a: :q})
+    end
+
+    it 'can be used with .map' do
+      expect(Hashformer.transform({}, { a: HF::G.map(HF::G.const(-1)) })).to eq({a: [-1]})
+    end
+  end
+
   describe '.map' do
     let(:data) {
       {
@@ -116,6 +138,26 @@ RSpec.describe Hashformer::Generate do
       end
     end
 
+    it 'works with transformations as keys' do
+      data = {
+        a: 1,
+        b: 2,
+        c: 3
+      }
+      xform = {
+        a: HF::G.map(:a, { a: HF::G.const(-1), b: :c }, :b)
+      }
+      expected = {
+        a: [
+          1,
+          { a: -1, b: 3 },
+          2
+        ]
+      }
+
+      expect(Hashformer.transform(data, xform)).to eq(expected)
+    end
+
     it 'works when chained' do
       xform = {
         name: HF::G.map(HF::G.map(:first, :last), HF::G.map(:last, :first))

data/spec/lib/hashformer_spec.rb

@@ -209,7 +209,7 @@ RSpec.describe Hashformer do
         end
       end
 
-      context 'Nested values' do
+      context 'Nested input values' do
         it 'produces the expected output for a present path' do
           data = {
             name: 'Hashformer',
@@ -253,6 +253,29 @@ RSpec.describe Hashformer do
         end
       end
 
+      context 'Constant values' do
+        it 'produces the expected output for a symbol' do
+          data = {
+            irrelevant: 'data',
+          }
+          xform = {
+            data: HF::G.const(:irrelevant)
+          }
+
+          expect(Hashformer.transform(data, xform)).to eq({data: :irrelevant})
+        end
+
+        it 'produces the expected output for a hash' do
+          data = {
+          }
+          xform = {
+            out: HF::G.const({a: 1, b: 2, c: [3, 4, 5]})
+          }
+
+          expect(Hashformer.transform(data, xform)).to eq({out: {a: 1, b: 2, c: [3, 4, 5]}})
+        end
+      end
+
       context 'Method chaining' do
         it 'produces the expected output for simple method chaining' do
           data = {
@@ -361,6 +384,54 @@ RSpec.describe Hashformer do
         end
       end
 
+      context 'Nested output values' do
+        it 'produces the expected output for a flat input' do
+          data = {
+            a: 1,
+            b: 2,
+            c: 3
+          }
+          xform = {
+            a: {
+              all: ->(orig){ orig },
+            },
+            b: {
+              x: :a,
+              y: :b,
+              z: :c,
+            }
+          }
+          expected = {
+            a: { all: { a: 1, b: 2, c: 3 } },
+            b: { x: 1, y: 2, z: 3 }
+          }
+
+          expect(Hashformer.transform(data, xform)).to eq(expected)
+        end
+
+        it 'produces the expected output for a nested input' do
+          data = {
+            a: 1,
+            b: {
+              a: 2,
+              b: 3,
+              c: 4
+            },
+            c: 5
+          }
+          xform = {
+            b: {
+              n: :a,             # Refers to the top-level :a
+              o: HF[:b][:a],     # Refers to the :a within :b
+              p: ->(h){ h[:c] }, # Refers to the top-level :c
+            }
+          }
+          expected = {b: { n: 1, o: 2, p: 5 }}
+
+          expect(Hashformer.transform(data, xform)).to eq(expected)
+        end
+      end
+
       context 'Practical example with validation' do
         it 'produces the expected output for a practical example' do
           # Classy Hash schema - https://github.com/deseretbook/classy_hash
@@ -406,6 +477,101 @@ RSpec.describe Hashformer do
           expect(Hashformer.transform(data, xform)).to eq(expected)
         end
       end
+
+      context 'Nested transformations' do
+        it 'produces the expected output for a practical example' do
+          in_schema = {
+            name: {
+              first: String,
+              last: String,
+            },
+
+            email: String,
+            phone: String,
+
+            address: {
+              line1: String,
+              line2: String,
+              city: String,
+              state: String,
+              zip: String,
+            }
+          }
+
+          out_schema = {
+            first: String,
+            last: String,
+            email: String,
+
+            address: {
+              phone: String,
+              lines: {
+                line1: String,
+                line2: String,
+              },
+              city: String,
+              state: String,
+              postcode: String,
+            }
+          }
+
+          xform = {
+            # Using multiple different transform types to make sure they all
+            # work here.  Normally one would use HF[] for all of these.
+            first: HF[:name][:first],
+            last: HF::G.path[:name][:last],
+            email: HF::G.map(:email){|e| e},
+
+            address: {
+              phone: :phone,
+              lines: {
+                line1: ->(u){ u[:address][:line1] },
+                line2: HF[:address][:line2],
+              },
+              city: HF[:address][:city],
+              state: HF::G.path[:address][:state],
+              postcode: HF[:address][:zip],
+            }
+          }
+
+          data = {
+            name: {
+              first: 'Hash',
+              last: 'Transformed',
+            },
+
+            email: 'Hashformer@example',
+            phone: '555-555-5555',
+
+            address: {
+              line1: '123 This Street',
+              line2: 'That One There',
+              city: 'Here',
+              state: 'ZZ',
+              zip: '00000',
+            }
+          }
+
+          expected = {
+            first: 'Hash',
+            last: 'Transformed',
+            email: 'Hashformer@example',
+
+            address: {
+              phone: '555-555-5555',
+              lines: {
+                line1: '123 This Street',
+                line2: 'That One There',
+              },
+              city: 'Here',
+              state: 'ZZ',
+              postcode: '00000',
+            }
+          }
+
+          expect(Hashformer.transform(data, xform)).to eq(expected)
+        end
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hashformer
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Deseret Book
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-29 00:00:00.000000000 Z
+date: 2014-08-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler