transproc 0.4.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5fb2ca80c956f246b5277462bb1dcbf5c3dbd09d
-  data.tar.gz: 7ae7b71a375e026ca281fbb6906850e418ba2b21
+  metadata.gz: ca6a7b97e58a3d28f1c9ebeb9303a52926c94d39
+  data.tar.gz: f1255fcec0934e3f096a6b47252d1ab6937df70e
 SHA512:
-  metadata.gz: d5fcb3e8a8229938d4f2cf16dab007eea0d3b7fbcb09c901c3a7aec87d5ceaa99ebd8e7254400409b4d540fb6426d5ba9d0b6182d36450d27a480430473c68c7
-  data.tar.gz: 708adcb9250af48b08950fdd85e82b6168d468c02b089544b97db283854be4852c37c347c4606779cee336bbf10ed6cc18bc4d595fea44db2fe5be7fd3dbb4b1
+  metadata.gz: f9a87bded9276d2be3f4847bd59528a29e26c54333518ead773f304b8c342a9dc63b8f18bc681483e10cd70c7717194cbc56d74b921d7228fd28b991339ec949
+  data.tar.gz: 6ef8c827fd903e226c3c1660091aac9fa231108ab7b7cecda5c438d142b633b81428000fa43802b51258d4033d774ac4f5ba90e0c97dbf77bbe42d66b30955da

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## v1.0.0 2017-01-29
+
+## Added
+
+* Add support of custom `Transproc::Registry` to `Transproc::Transformer` (Kukunin)
+* Add `Transproc::Transformer.t` DSL method to access transformations (Kukunin)
+* Add `Transproc::Transformer.define` method for anonymous transprocs defining (Kukunin)
+
+## Deleted
+
+* Remove all mutating transformations (Kukunin)
+* Remove deprecated `Transproc` global container with `Transproc::Helper`(Kukunin)
+* Remove support of `Transproc::Transformer` without registry (Kukunin)
+
+[Compare v0.4.2...v1.0.0](https://github.com/solnic/transproc/compare/v0.4.2...v1.0.0)
+
 ## v0.4.2 2017-01-12
 
 ## Added

data/README.md

@@ -14,7 +14,13 @@
 [![Test Coverage](https://codeclimate.com/github/solnic/transproc/badges/coverage.svg)][codeclimate]
 [![Inline docs](http://inch-ci.org/github/solnic/transproc.svg?branch=master)][inchpages]
 
-Transproc is a small library that allows you to compose methods into a functional pipeline using left-to-right function composition. It works like `|>` in Elixir or `>>` in F#.
+Transproc is a small library that allows you to compose procs into a functional pipeline using left-to-right function composition.
+
+The approach came from Functional Programming, where simple functions are composed into more complex functions in order to transform some data. It works like `|>` in Elixir
+or `>>` in F#.
+
+`transproc` provides a mechanism to define and compose transformations,
+along with a number of built-in transformations.
 
 It's currently used as the data mapping backend in [Ruby Object Mapper](http://rom-rb.org).
 
@@ -34,7 +40,128 @@ Or install it yourself as:
 
     $ gem install transproc
 
-## Usage
+## Basics
+
+Simple transformations are defined as easy as:
+
+```ruby
+increament = Transproc::Function.new(-> (data) { data + 1 })
+increament[1] # => 2
+```
+
+It's easy to compose transformations:
+
+```ruby
+to_string = Transproc::Function.new(:to_s.to_proc)
+(increament >> to_string)[1] => '2'
+```
+
+It's easy to pass additional arguments to transformations:
+
+```ruby
+append = Transproc::Function.new(-> (value, suffix) { value + suffix })
+append_bar = append.with('_bar')
+append_bar['foo'] # => foo_bar
+```
+
+Or even accept another transformation as an argument:
+
+```ruby
+map_array = Transproc::Function.new(-> (array, fn) { array.map(&fn) })
+map_array.with(to_string).call([1, 2, 3]) # => ['1', '2', '3']
+```
+
+To improve this low-level definition, you can use class methods
+with `Transproc::Registry`:
+
+```ruby
+M = Module.new do
+  extend Transproc::Registry
+
+  def self.to_string(value)
+    value.to_s
+  end
+
+  def self.map_array(array, fn)
+    array.map(&fn)
+  end
+end
+M[:map_array, M[:to_string]].([1, 2, 3]) # => ['1', '2', '3']
+```
+
+### Built-in transformations
+
+`transproc` comes with a lot of built-in functions. They come in the form of
+modules with class methods, which you can import into a registry:
+
+* [Coercions](http://www.rubydoc.info/gems/transproc/Transproc/Coercions)
+* [Array transformations](http://www.rubydoc.info/gems/transproc/Transproc/ArrayTransformations)
+* [Hash transformations](http://www.rubydoc.info/gems/transproc/Transproc/HashTransformations)
+* [Class transformations](http://www.rubydoc.info/gems/transproc/Transproc/ClassTransformations)
+* [Proc transformations](http://www.rubydoc.info/gems/transproc/Transproc/ProcTransformations)
+* [Conditional](http://www.rubydoc.info/gems/transproc/Transproc/Conditional)
+* [Recursion](http://www.rubydoc.info/gems/transproc/Transproc/Recursion)
+
+You can import everything with:
+
+```ruby
+module T
+  extend Transproc::Registry
+
+  import Transproc::Coercions
+  import Transproc::ArrayTransformations
+  import Transproc::HashTransformations
+  import Transproc::ClassTransformations
+  import Transproc::ProcTransformations
+  import Transproc::Conditional
+  import Transproc::Recursion
+end
+T[:to_string].call(:abc) # => 'abc'
+```
+
+Or import selectively with:
+
+```ruby
+module T
+  extend Transproc::Registry
+
+  import :to_string, from: Transproc::Coercions, as: :stringify
+end
+T[:stringify].call(:abc) # => 'abc'
+T[:to_string].call(:abc)
+# => Transproc::FunctionNotFoundError: No registered function T[:to_string]
+```
+
+### Transformer
+
+Transformer is a class-level DSL for composing transformation pipelines,
+for example:
+
+```ruby
+T = Class.new(Transproc::Transformer) do
+  map_array do
+    symbolize_keys
+    rename_keys user_name: :name
+    nest :address, [:city, :street, :zipcode]
+  end
+end
+
+T.new.call(
+  [
+    { 'user_name' => 'Jane',
+      'city' => 'NYC',
+      'street' => 'Street 1',
+      'zipcode' => '123'
+    }
+  ]
+)
+# => [{:name=>"Jane", :address=>{:city=>"NYC", :street=>"Street 1", :zipcode=>"123"}}]
+```
+
+It converts every method call to its corresponding transformation, and joins
+these transformations into a transformation pipeline (a transproc).
+
+## Transproc Example Usage
 
 ``` ruby
 require 'json'
@@ -99,6 +226,9 @@ module Functions
   end
 end
 
+# ...or add it to registered functions via .register method
+Functions.register(:load_json) { |v| JSON.load(v) }
+
 transformation = t(:load_json) >> t(:map_array, t(:symbolize_keys))
 
 transformation.call('[{"name":"Jane"}]')

data/lib/transproc.rb

@@ -10,78 +10,7 @@ require 'transproc/support/deprecations'
 
 module Transproc
   Undefined = Object.new.freeze
-  Transformer.container(self)
-  # Function registry
-  #
-  # @api private
-  def self.functions
-    @_functions ||= {}
-  end
-
-  # Register a new function
-  #
-  # @example
-  #   Transproc.register(:to_json, -> v { v.to_json })
-  #
-  #   Transproc(:map_array, Transproc(:to_json))
-  #
-  #
-  # @return [Function]
-  #
-  # @api public
-  def self.register(*args, &block)
-    name, fn = *args
-    if functions.include? name
-      raise FunctionAlreadyRegisteredError, "Function #{name} is already defined"
-    end
-    functions[name] = fn || block
-  end
-
-  # Get registered function with provided name
-  #
-  # @param [Symbol] name The name of the registered function
-  #
-  # @api private
-  def self.[](name, *args)
-    fn = functions.fetch(name) { raise(FunctionNotFoundError, name) }
-
-    if args.any?
-      fn.with(*args)
-    else
-      fn
-    end
-  end
 end
 
 require 'transproc/array'
 require 'transproc/hash'
-
-# Access registered functions
-#
-# @example
-#   Transproc(:map_array, Transproc(:to_string))
-#
-#   Transproc(:to_string) >> Transproc(-> v { v.upcase })
-#
-# @param [Symbol,Proc] fn The name of the registered function or an anonymous proc
-# @param [Array] args Optional addition args that a given function may need
-#
-# @return [Function]
-#
-# @api public
-def Transproc(fn, *args)
-  Transproc::Deprecations.announce(
-    'Transproc()',
-    'Define your own function registry using Transproc::Registry extension'
-  )
-
-  case fn
-  when Proc then Transproc::Function.new(fn, args: args)
-  when Symbol
-    func = Transproc[fn, *args]
-    case func
-    when Transproc::Function, Transproc::Composite then func
-    else Transproc::Function.new(func, args: args)
-    end
-  end
-end

data/lib/transproc/array.rb

@@ -38,16 +38,7 @@ module Transproc
     #
     # @api public
     def self.map_array(array, fn)
-      map_array!(array.dup, fn)
-    end
-
-    # Same as `map_array` but mutates the array
-    #
-    # @see ArrayTransformations.map_array
-    #
-    # @api public
-    def self.map_array!(array, fn)
-      array.map! { |value| fn[value] }
+      Array(array).map { |value| fn[value] }
     end
 
     # Wrap array values using HashTransformations.nest function
@@ -127,51 +118,53 @@ module Transproc
       array.flat_map { |item| HashTransformations.split(item, key, keys) }
     end
 
-    # Combines two arrays by merging child items from right array using join keys
-    #
-    # @example
-    #   fn = t(:combine, [[:tasks, name: :user]])
-    #
-    #   fn.call([[{ name: 'Jane' }], [{ user: 'Jane', title: 'One' }]])
-    #   # => [{:name=>"Jane", :tasks=>[{:user=>"Jane", :title=>"One"}]}]
-    #
-    # @param [Array<Array>] array The input array
-    # @param [Array<Hash>] mappings The mapping definitions array
-    #
-    # @return [Array<Hash>]
-    #
-    # @api public
-    def self.combine(array, mappings)
-      root, groups = array
+    CACHE = Hash.new { |h, k| h[k] = {} }
 
-      cache = Hash.new { |h, k| h[k] = {} }
+    def self.combine(array, mappings, cache = CACHE.dup)
+      root, groups = array
 
-      root.map { |parent|
+      root.map do |parent|
         child_hash = {}
 
-        groups.each_with_index do |candidates, index|
-          key, keys, group_mappings = mappings[index]
+        for candidates in groups
+          index = groups.index(candidates)
+          data = mappings[index]
+
+          key = data[0]
+          keys = data[1]
 
           children =
-            if group_mappings
-              combine(candidates, group_mappings)
-            else
+            if data.size == 2
               candidates
+            else
+              combine(candidates, data[2])
+            end
+
+          child_keys = keys.size > 1 ? keys.values : keys.values[0]
+          pk_names = keys.size > 1 ? keys.keys : keys.keys[0]
+
+          pkey_value =
+            if pk_names.is_a?(Array)
+              parent.values_at(*pk_names)
+            else
+              parent[pk_names]
             end
 
-          child_keys = keys.values
-          pkey_value = parent.values_at(*keys.keys) # ugh
+          cache[key][child_keys] ||= children.group_by do |child|
+            if child_keys.is_a?(Array)
+              child.values_at(*child_keys)
+            else
+              child[child_keys]
+            end
+          end
 
-          cache[key][child_keys] ||= children.group_by { |child|
-            child.values_at(*child_keys)
-          }
           child_arr = cache[key][child_keys][pkey_value] || []
 
-          child_hash.update(key => child_arr)
+          child_hash[key] = child_arr
         end
 
         parent.merge(child_hash)
-      }
+      end
     end
 
     # Converts the array of hashes to array of values, extracted by given key
@@ -192,16 +185,7 @@ module Transproc
     #
     # @api public
     def self.extract_key(array, key)
-      extract_key!(Array[*array], key)
-    end
-
-    # Same as `extract_key` but mutates the array
-    #
-    # @see ArrayTransformations.extract_key
-    #
-    # @api public
-    def self.extract_key!(array, key)
-      map_array!(array, -> v { v[key] })
+      map_array(array, ->(v) { v[key] })
     end
 
     # Wraps every value of the array to tuple with given key
@@ -220,16 +204,7 @@ module Transproc
     #
     # @api public
     def self.insert_key(array, key)
-      insert_key!(Array[*array], key)
-    end
-
-    # Same as `insert_key` but mutates the array
-    #
-    # @see ArrayTransformations.insert_key
-    #
-    # @api public
-    def self.insert_key!(array, key)
-      map_array!(array, -> v { { key => v } })
+      map_array(array, ->(v) { { key => v } })
     end
 
     # Adds missing keys with nil value to all tuples in array
@@ -241,21 +216,8 @@ module Transproc
     # @api public
     #
     def self.add_keys(array, keys)
-      add_keys!(Array[*array], keys)
-    end
-
-    # Same as `add_keys` but mutates the array
-    #
-    # @see ArrayTransformations.add_keys
-    #
-    # @api public
-    def self.add_keys!(array, keys)
       base = keys.inject({}) { |a, e| a.merge(e => nil) }
-      map_array!(array, -> v { base.merge(v) })
+      map_array(array, ->(v) { base.merge(v) })
     end
-
-    # @deprecated Register methods globally
-    (methods - Registry.methods - Registry.instance_methods)
-      .each { |name| Transproc.register name, t(name) }
   end
 end

data/lib/transproc/class.rb

@@ -48,9 +48,5 @@ module Transproc
       end
       object
     end
-
-    # @deprecated Register methods globally
-    (methods - Registry.methods - Registry.instance_methods)
-      .each { |name| Transproc.register name, t(name) }
   end
 end

data/lib/transproc/coercions.rb

@@ -188,9 +188,5 @@ module Transproc
       array.select! { |item| item.is_a?(Hash) }
       array.any? ? array : [{}]
     end
-
-    # @deprecated Register methods globally
-    (methods - Registry.methods - Registry.instance_methods)
-      .each { |name| Transproc.register name, t(name) }
   end
 end

data/lib/transproc/composer.rb

@@ -1,32 +1,6 @@
 require 'transproc/support/deprecations'
 
 module Transproc
-  # Transproc helper that adds `t` method as a shortcut for `Transproc` method
-  #
-  # @example
-  #   include Transproc::Helper
-  #
-  #   t(:to_string)
-  #
-  # @api public
-  module Helper
-    # @api private
-    def self.included(*)
-      Transproc::Deprecations.announce(
-        'Transproc::Helper',
-        'Define your own function registry using Transproc::Registry extension'
-      )
-      super
-    end
-
-    # @see Transproc
-    #
-    # @api public
-    def t(*args, &block)
-      Transproc(*args, &block)
-    end
-  end
-
   # Helper extension handy for composing many functions in multiple steps
   #
   # @example