README.md in hashformer-0.2.1 vs README.md in hashformer-0.2.2

- old
+ new

@@ -51,11 +51,11 @@ Hashformer.transform(data, xform) # => {zero: 'Nothing', one: 'Only One'} ``` -#### 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`): ```ruby @@ -107,18 +107,49 @@ Hashformer.transform(data, xform) # => {h: {a: 1, b: 2}} ``` +#### 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 = { s: 'Hashformer', v: [1, 2, 3, 4, 5] @@ -220,11 +251,14 @@ 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 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. @@ -256,9 +290,62 @@ ->(value, h){h[:key]} => :value } Hashformer.transform(data, xform) # => {x: 0} +``` + + +#### 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