transproc 0.1.3 → 0.2.0

data/lib/transproc/composer.rb

@@ -1,31 +1,74 @@
 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
+    # @see Transproc
+    #
+    # @api public
     def t(*args, &block)
       Transproc(*args, &block)
     end
   end
 
+  # Helper extension handy for composing many functions in multiple steps
+  #
+  # @example
+  #   include Transproc::Composer
+  #
+  #   fn = compose do |fns|
+  #     fns << t(:map_array, t(:symbolize_keys))
+  #     fns << t(:map_array, t(:nest, :address, [:city, :zipcode]))
+  #   end
+  #
+  #   fn.call [{ 'city' => 'NYC', 'zipcode' => '123' }]
+  #   # => [{ address: { city: 'NYC', zipcode: '123' }]
+  #
+  # @api public
   module Composer
     include Helper
 
+    # @api private
     class Factory
       attr_reader :fns, :default
 
+      # @api private
       def initialize(default = nil)
         @fns = []
         @default = default
       end
 
+      # @api private
       def <<(other)
         fns.concat(Array(other).compact)
         self
       end
 
+      # @api private
       def to_fn
         fns.reduce(:+) || default
       end
     end
 
+    # Gather and compose functions and fall-back to a default one if provided
+    #
+    # @example
+    #   include Transproc::Composer
+    #
+    #   fn = compose(-> v { v }) do |fns|
+    #     fns << t(:to_string) if something
+    #   end
+    #
+    #   fn[1] # => "1"
+    #
+    # @see Composer
+    #
+    # @api public
     def compose(default = nil)
       factory = Factory.new(default)
       yield(factory)

data/lib/transproc/conditional.rb

@@ -0,0 +1,56 @@
+module Transproc
+
+  # Conditional transformation functions
+  #
+  # @example
+  #   require 'transproc/conditional'
+  #
+  #   include Transproc::Helper
+  #
+  #   fn = t(:guard, -> s { s.is_a?(::String) }, -> s { s.to_sym })
+  #
+  #   [fn[2], fn['Jane']]
+  #   # => [2, :Jane]
+  #
+  # @api public
+  module Conditional
+    extend Functions
+
+    # Apply the transformation function to subject if the predicate returns true, or return un-modified
+    #
+    # @example
+    #   [2, 'Jane'].map do |subject|
+    #     Transproc(:guard, -> s { s.is_a?(::String) }, -> s { s.to_sym })[subject]
+    #   end
+    #   # => [2, :Jane]
+    #
+    # @param [Mixed]
+    #
+    # @return [Mixed]
+    #
+    # @api public
+    def guard(value, predicate, fn)
+      predicate[value] ? fn[value] : value
+    end
+
+    # Calls a function when type-check passes
+    #
+    # @example
+    #   fn = Transproc(:is, Array, -> arr { arr.map(&:upcase) })
+    #   fn.call(['a', 'b', 'c']) # => ['A', 'B', 'C']
+    #
+    #   fn = Transproc(:is, Array, -> arr { arr.map(&:upcase) })
+    #   fn.call('foo') # => "foo"
+    #
+    # @param [Object]
+    # @param [Class]
+    # @param [Proc]
+    #
+    # @return [Object]
+    #
+    # @api public
+    def is(value, type, fn)
+      guard(value, -> v { v.is_a?(type) }, fn)
+    end
+  end
+end

data/lib/transproc/function.rb

@@ -1,21 +1,112 @@
 module Transproc
+  # Transformation proc wrapper allowing composition of multiple procs into
+  # a data-transformation pipeline.
+  #
+  # This is used by Transproc to wrap registered methods.
+  #
+  # @api private
   class Function
-    attr_reader :fn, :args
+    # Wrapped proc or another composite function
+    #
+    # @return [Proc,Composed]
+    #
+    # @api private
+    attr_reader :fn
 
-    def initialize(fn, args = [])
+    # Additional arguments that will be passed to the wrapped proc
+    #
+    # @return [Array]
+    #
+    # @api private
+    attr_reader :args
+
+    # @api private
+    def initialize(fn, options = {})
       @fn = fn
-      @args = args
+      @args = options.fetch(:args) { [] }
     end
 
+    # Call the wrapped proc
+    #
+    # @param [Object] value The input value
+    #
+    # @alias []
+    #
+    # @api public
     def call(value)
       fn[value, *args]
     end
     alias_method :[], :call
 
+    # Compose this function with another function or a proc
+    #
+    # @param [Proc,Function]
+    #
+    # @return [Composite]
+    #
+    # @alias :>>
+    #
+    # @api public
     def compose(other)
-      self.class.new(-> *input { other[fn[*input]] }, args)
+      Composite.new(self, right: other)
     end
     alias_method :+, :compose
     alias_method :>>, :compose
+
+    # Return a simple AST representation of this function
+    #
+    # @return [Array]
+    #
+    # @api public
+    def to_ast
+      identifier = Proc === fn ? fn : fn.name
+      [identifier, args]
+    end
+
+    # Composition of two functions
+    #
+    # @api private
+    class Composite < Function
+      alias_method :left, :fn
+
+      # @return [Proc]
+      #
+      # @api private
+      attr_reader :right
+
+      # @api private
+      def initialize(fn, options = {})
+        super
+        @right = options.fetch(:right)
+      end
+
+      # Call right side with the result from the left side
+      #
+      # @param [Object] value The input value
+      #
+      # @return [Object]
+      #
+      # @api public
+      def call(value)
+        right[left[value]]
+      end
+      alias_method :[], :call
+
+      # @see Function#compose
+      #
+      # @api public
+      def compose(other)
+        Composite.new(self, right: other)
+      end
+      alias_method :+, :compose
+      alias_method :>>, :compose
+
+      # @see Function#to_ast
+      #
+      # @api public
+      def to_ast
+        left.to_ast << right.to_ast
+      end
+    end
   end
 end

data/lib/transproc/hash.rb

@@ -1,57 +1,234 @@
+require 'transproc/coercions'
+
 module Transproc
-  register(:symbolize_keys) do |hash|
-    Transproc(:symbolize_keys!)[Hash[hash]]
-  end
+  # Transformation functions for Hash objects
+  #
+  # @example
+  #   require 'transproc/hash'
+  #
+  #   include Transproc::Helper
+  #
+  #   fn = t(:symbolize_keys) >> t(:nest, :address, [:street, :zipcode])
+  #
+  #   fn["street" => "Street 1", "zipcode" => "123"]
+  #   # => {:address => {:street => "Street 1", :zipcode => "123"}}
+  #
+  # @api public
+  module HashTransformations
+    extend Functions
 
-  register(:symbolize_keys!) do |hash|
-    hash.keys.each { |key| hash[key.to_sym] = hash.delete(key) }
-    hash
-  end
+    # Map all keys in a hash with the provided transformation function
+    #
+    # @example
+    #   Transproc(:map_keys, -> s { s.upcase })['name' => 'Jane']
+    #   # => {"NAME" => "Jane"}
+    #
+    # @param [Hash]
+    #
+    # @return [Hash]
+    #
+    # @api public
+    def map_keys(hash, fn)
+      map_keys!(Hash[hash], fn)
+    end
 
-  register(:map_hash) do |hash, mapping|
-    Transproc(:map_hash!, mapping)[Hash[hash]]
-  end
+    # Same as `:map_keys` but mutates the hash
+    #
+    # @see HashTransformations.map_keys
+    #
+    # @api public
+    def map_keys!(hash, fn)
+      hash.keys.each { |key| hash[fn[key]] = hash.delete(key) }
+      hash
+    end
 
-  register(:map_hash!) do |hash, mapping|
-    mapping.each { |k, v| hash[v] = hash.delete(k) }
-    hash
-  end
+    # Symbolize all keys in a hash
+    #
+    # @example
+    #   Transproc(:symbolize_keys)['name' => 'Jane']
+    #   # => {:name => "Jane"}
+    #
+    # @param [Hash]
+    #
+    # @return [Hash]
+    #
+    # @api public
+    def symbolize_keys(hash)
+      symbolize_keys!(Hash[hash])
+    end
 
-  register(:map_key) do |hash, key, fn|
-    hash.merge(key => fn[hash[key]])
-  end
+    # Same as `:symbolize_keys` but mutates the hash
+    #
+    # @see HashTransformations.symbolize_keys!
+    #
+    # @api public
+    def symbolize_keys!(hash)
+      map_keys!(hash, Transproc(:to_symbol).fn)
+    end
 
-  register(:map_key!) do |hash, key, fn|
-    hash.update(key => fn[hash[key]])
-  end
+    # Stringify all keys in a hash
+    #
+    # @example
+    #   Transproc(:stringify_keys)[:name => 'Jane']
+    #   # => {"name" => "Jane"}
+    #
+    # @param [Hash]
+    #
+    # @return [Hash]
+    #
+    # @api public
+    def stringify_keys(hash)
+      stringify_keys!(Hash[hash])
+    end
 
-  register(:nest) do |hash, key, keys|
-    Transproc(:nest!, key, keys)[Hash[hash]]
-  end
+    # Same as `:stringify_keys` but mutates the hash
+    #
+    # @see HashTransformations.stringify_keys
+    #
+    # @api public
+    def stringify_keys!(hash)
+      map_keys!(hash, Transproc(:to_string).fn)
+    end
 
-  register(:nest!) do |hash, root, keys|
-    nest_keys = hash.keys & keys
+    # Map all values in a hash using transformation function
+    #
+    # @example
+    #   Transproc(:map_values, -> v { v.upcase })[:name => 'Jane']
+    #   # => {"name" => "JANE"}
+    #
+    # @param [Hash]
+    #
+    # @return [Hash]
+    #
+    # @api public
+    def map_values(hash, fn)
+      map_values!(Hash[hash], fn)
+    end
 
-    if nest_keys.size > 0
-      child = Hash[nest_keys.zip(nest_keys.map { |key| hash.delete(key) })]
-      hash.update(root => child)
-    else
-      hash.update(root => {})
+    # Same as `:map_values` but mutates the hash
+    #
+    # @see HashTransformations.map_values
+    #
+    # @param [Hash]
+    #
+    # @return [Hash]
+    #
+    # @api public
+    def map_values!(hash, fn)
+      hash.each { |key, value| hash[key] = fn[value] }
+      hash
     end
-  end
 
-  register(:unwrap) do |hash, root, keys|
-    copy = Hash[hash].merge(root => Hash[hash[root]])
-    Transproc(:unwrap!, root, keys)[copy]
-  end
+    # Rename all keys in a hash using provided mapping hash
+    #
+    # @example
+    #   Transproc(:rename_keys, user_name: :name)[user_name: 'Jane']
+    #   # => {:name => "Jane"}
+    #
+    # @param [Hash] hash The input hash
+    # @param [Hash] mapping The key-rename mapping
+    #
+    # @return [Hash]
+    #
+    # @api public
+    def rename_keys(hash, mapping)
+      rename_keys!(Hash[hash], mapping)
+    end
+
+    # Same as `:rename_keys` but mutates the hash
+    #
+    # @see HashTransformations.rename_keys
+    #
+    # @api public
+    def rename_keys!(hash, mapping)
+      mapping.each { |k, v| hash[v] = hash.delete(k) }
+      hash
+    end
+
+    # Map a key in a hash with the provided transformation function
+    #
+    # @example
+    #   Transproc(:map_value, -> s { s.upcase })['name' => 'jane']
+    #   # => {"name" => "JANE"}
+    #
+    # @param [Hash]
+    #
+    # @return [Hash]
+    #
+    # @api public
+    def map_value(hash, key, fn)
+      hash.merge(key => fn[hash[key]])
+    end
+
+    # Same as `:map_value` but mutates the hash
+    #
+    # @see HashTransformations.map_value!
+    #
+    # @api public
+    def map_value!(hash, key, fn)
+      hash.update(key => fn[hash[key]])
+    end
 
-  register(:unwrap!) do |hash, root, keys|
-    if nested_hash = hash[root]
-      keys ||= nested_hash.keys
-      hash.update(Hash[keys.zip(keys.map { |key| nested_hash.delete(key) })])
-      hash.delete(root) if nested_hash.empty?
+    # Nest values from specified keys under a new key
+    #
+    # @example
+    #   Transproc(:nest, :address, [:street, :zipcode])[street: 'Street', zipcode: '123']
+    #   # => {address: {street: "Street", zipcode: "123"}}
+    #
+    # @param [Hash]
+    #
+    # @return [Hash]
+    #
+    # @api public
+    def nest(hash, key, keys)
+      nest!(Hash[hash], key, keys)
     end
 
-    hash
+    # Same as `:nest` but mutates the hash
+    #
+    # @see HashTransformations.nest
+    #
+    # @api public
+    def nest!(hash, root, keys)
+      nest_keys = hash.keys & keys
+
+      if nest_keys.size > 0
+        child = Hash[nest_keys.zip(nest_keys.map { |key| hash.delete(key) })]
+        hash.update(root => child)
+      else
+        hash.update(root => {})
+      end
+    end
+
+    # Collapse a nested hash from a specified key
+    #
+    # @example
+    #   Transproc(:unwrap, :address, [:street, :zipcode])[address: { street: 'Street', zipcode: '123' }]
+    #   # => {street: "Street", zipcode: "123"}
+    #
+    # @param [Hash]
+    #
+    # @return [Hash]
+    #
+    # @api public
+    def unwrap(hash, root, keys)
+      copy = Hash[hash].merge(root => Hash[hash[root]])
+      unwrap!(copy, root, keys)
+    end
+
+    # Same as `:unwrap` but mutates the hash
+    #
+    # @see HashTransformations.unwrap
+    #
+    # @api public
+    def unwrap!(hash, root, keys = nil)
+      if nested_hash = hash[root]
+        keys ||= nested_hash.keys
+        hash.update(Hash[keys.zip(keys.map { |key| nested_hash.delete(key) })])
+        hash.delete(root) if nested_hash.empty?
+      end
+
+      hash
+    end
   end
 end