transproc 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b43b407d9915f16f63dbf1a12f10c9a87228213c
-  data.tar.gz: a46a7614a839a50da267593eeef25acbc8db167b
+  metadata.gz: 2cc7103ff3c33f4d49ebf8bd85f049500f5b0a27
+  data.tar.gz: 08c4676baf065be02235c2a9885d62fadb514311
 SHA512:
-  metadata.gz: 5ce15554b0639b3c79a0a4da686e588f01dd0de7798b89a7129c39b0a51f0f0c31b094533775b3b21f5b6b893917020f2d99aa1b84648c445617c75f3f8e5688
-  data.tar.gz: 104618d775a9ce9781583b2c6f4e0e61ca28107f1f4494124b41456c8442b4663a7d4ad5b353dd6641b0e885f56d5b33ee0d0a32e23ff5a6ad4c9fcf2f029e96
+  metadata.gz: a532a67708497aa9ddc6e53c10bddbcc1b0c9c71ac648b05f59b9d4c24ec61e08d2f713b535134824a67aec9f099be647e5593bbe3033a32dca96c164b1b0b85
+  data.tar.gz: b21cc5f7674752c33e4d55c3067f9f71ba372444d4ee497cc054a14293f89087232b55489e670aa7fafe891ce147a15924c1418009268c4875771d7a657c3431

data/.travis.yml

@@ -13,3 +13,10 @@ rvm:
 matrix:
   allow_failures:
     - rvm: ruby-head
+notifications:
+  webhooks:
+    urls:
+      - https://webhooks.gitter.im/e/177598ba2843dcdc1047
+    on_success: change
+    on_failure: always
+    on_start: false

data/CHANGELOG.md

@@ -1,4 +1,26 @@
-## v0.1.3 to-be-released
+## v0.2.0 2015-04-14
+
+### Added
+
+* `:map_values` hash transformation (AMHOL)
+* `:map_value` hash transformation (AMHOL)
+* `:map_value` hash transformation (AMHOL)
+* `:guard` function (AMHOL)
+* `:is` type-check function (solnic)
+* `Function#to_ast` for easy inspection (solnic)
+* Ability to define module with custom functions that will be auto-registered (solnic + splattael)
+
+### Changed
+
+* [BREAKING] `map_hash` renamed to `rename_keys`
+* [BREAKING] `map_key` renamed to `map_value`
+* [BREAKING] `map_array` no longer accepts multiple functions (AMHOL)
+* All functions are now defined as module functions (solnic + splattael)
+* Functions no longer create anonymous procs (solnic)
+
+[Compare v0.1.3...v0.2.0](https://github.com/solnic/transproc/compare/v0.1.3...v0.2.0)
+
+## v0.1.3 2015-04-07
 
 ### Added
 

data/Gemfile

@@ -3,10 +3,13 @@ source 'https://rubygems.org'
 gemspec
 
 group :test do
+  gem 'mutant'
+  gem 'mutant-rspec'
   gem 'codeclimate-test-reporter', require: nil
 end
 
 group :tools do
   gem 'byebug', platform: :mri
   gem 'benchmark-ips'
+  gem 'guard-rspec'
 end

data/README.md

@@ -5,7 +5,7 @@
 [coveralls]: https://coveralls.io/r/solnic/transproc
 [inchpages]: http://inch-ci.org/github/solnic/transproc
 
-# Transproc
+# Transproc [![Join the chat at https://gitter.im/solnic/transproc](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/solnic/transproc?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
 [![Gem Version](https://badge.fury.io/rb/transproc.svg)][gem]
 [![Build Status](https://travis-ci.org/solnic/transproc.svg?branch=master)][travis]
@@ -39,21 +39,39 @@ Or install it yourself as:
 require 'transproc/all'
 
 # compose transformation functions
-transformation = Transproc(:symbolize_keys) >> Transproc(:map_hash, user_name: :name))
+include Transproc::Helper
 
-# call the function
-transformation['user_name' => 'Jane']
-# => {:name=>"Jane"}
-
-# or using a helper (no, it's not a good idea to include it here :))
-include Transproc::Composer
+transformation = t(:map_array, t(:symbolize_keys) >> t(:rename_keys, user_name: :user))
+transformation >>= t(:wrap, :address, [:city, :street, :zipcode])
 
-transformation = compose do |fns|
-  fns << t(:symbolize_keys) << t(:map_hash, user_name: :name)
+# call the function
+transformation.call(
+  [
+    { 'user_name' => 'Jane',
+      'city' => 'NYC',
+      'street' => 'Street 1',
+      'zipcode' => '123' }
+  ]
+)
+# => [{:user=>"Jane", :address=>{:city=>"NYC", :street=>"Street 1", :zipcode=>"123"}}]
+
+# Define your own transformations easily
+Transproc(:to_json, -> v { JSON.dump(v) })
+
+Transproc(:to_json).call([{ name: 'Jane' }])
+# => "[{\"name\":\"Jane\"}]"
+
+# ...or create a module with custom transformations
+module MyTransformations
+  extend Transproc::Functions
+
+  def load_json(v)
+    JSON.load(v)
+  end
 end
 
-transformation['user_name' => 'Jane']
-# => {:name=>"Jane"}
+(Transproc(:load_json) >> Transproc(:symbolize_keys)).call('[{"name":"Jane"}]')
+# => [{ :name => "Jane" }]
 ```
 
 ## Credits

data/lib/transproc.rb

@@ -3,23 +3,78 @@ require 'transproc/function'
 require 'transproc/composer'
 
 module Transproc
-  def self.register(*args, &block)
+  module_function
+
+  # Register a new function
+  #
+  # @example
+  #   Transproc.register(:to_json, -> v { v.to_json })
+  #
+  #   Transproc(:map_array, Transproc(:to_json))
+  #
+  #
+  # @return [Function]
+  #
+  # @api public
+  def register(*args, &block)
     name, fn = *args
     functions[name] = fn || block
   end
 
-  def self.functions
+  # Get registered function with provided name
+  #
+  # @param [Symbol] name The name of the registered function
+  #
+  # @api private
+  def [](name)
+    functions.fetch(name)
+  end
+
+  # Function registry
+  #
+  # @api private
+  def functions
     @_functions ||= {}
   end
 
-  def self.[](name)
-    functions.fetch(name)
+  # Function container extension
+  #
+  # @example
+  #   module MyTransformations
+  #     extend Transproc::Functions
+  #
+  #     def boom!(value)
+  #       "#{value} BOOM!"
+  #     end
+  #   end
+  #
+  #   Transproc(:boom!)['w00t!'] # => "w00t! BOOM!"
+  #
+  # @api public
+  module Functions
+    def method_added(meth)
+      module_function meth
+      Transproc.register(meth, method(meth))
+    end
   end
 end
 
+# 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)
   case fn
-  when Proc then Transproc::Function.new(fn, args)
-  when Symbol then Transproc::Function.new(Transproc[fn], args)
+  when Proc then Transproc::Function.new(fn, args: args)
+  when Symbol then Transproc::Function.new(Transproc[fn], args: args)
   end
 end

data/lib/transproc/all.rb

@@ -1,6 +1,7 @@
 require 'transproc'
 
 require 'transproc/coercions'
+require 'transproc/conditional'
 require 'transproc/array'
 require 'transproc/hash'
 require 'transproc/recursion'

data/lib/transproc/array.rb

@@ -1,27 +1,102 @@
+require 'transproc/hash'
+
 module Transproc
-  register(:map_array) do |array, *fns|
-    Transproc(:map_array!, *fns)[Array[*array]]
-  end
+  # Transformation functions for Array objects
+  #
+  # @example
+  #   require 'transproc/array'
+  #
+  #   include Transproc::Helper
+  #
+  #   fn = t(:map_array, t(:symbolize_keys)) >> t(:wrap, :address, [:city, :zipcode])
+  #
+  #   fn.call(
+  #     [
+  #       { 'city' => 'Boston', 'zipcode' => '123' },
+  #       { 'city' => 'NYC', 'zipcode' => '312' }
+  #     ]
+  #   )
+  #   # => [{ city: 'Boston', zipcode: '123' }, { city: 'NYC', zipcode: '312' }]
+  #
+  # @api public
+  module ArrayTransformations
+    extend Functions
 
-  register(:map_array!) do |array, *fns|
-    fn = fns.size == 1 ? fns[0] : fns.reduce(:+)
-    array.map! { |value| fn[value] }
-  end
+    # Map array values using transformation function
+    #
+    # @example
+    #
+    #   fn = Transproc(:map_array, -> v { v.upcase })
+    #
+    #   fn.call ['foo', 'bar'] # => ["FOO", "BAR"]
+    #
+    # @param [Array] array The input array
+    # @param [Proc] fn The transformation function
+    #
+    # @return [Array]
+    #
+    # @api public
+    def map_array(array, fn)
+      map_array!(Array[*array], fn)
+    end
 
-  register(:wrap) do |array, key, keys|
-    Transproc(:map_array, Transproc(:nest, key, keys))[array]
-  end
+    # Same as `map_array` but mutates the array
+    #
+    # @see ArrayTransformations.map_array
+    #
+    # @api public
+    def map_array!(array, fn)
+      array.map! { |value| fn[value] }
+    end
 
-  register(:group) do |array, key, keys|
-    grouped = Hash.new { |hash, key| hash[key] = [] }
-    array.each do |hash|
-      hash = hash.dup
-      child = {}
-      keys.each { |k| child[k] = hash.delete(k) }
-      grouped[hash] << child
+    # Wrap array values using HashTransformations.nest function
+    #
+    # @example
+    #   fn = Transproc(:wrap, :address, [:city, :zipcode])
+    #
+    #   fn.call [{ city: 'NYC', zipcode: '123' }]
+    #   # => [{ address: { city: 'NYC', zipcode: '123' } }]
+    #
+    # @param [Array] array The input array
+    # @param [Object] key The nesting root key
+    # @param [Object] keys The nesting value keys
+    #
+    # @return [Array]
+    #
+    # @api public
+    def wrap(array, key, keys)
+      map_array(array, Transproc(:nest, key, keys))
     end
-    grouped.map do |root, children|
-      root.merge(key => children)
+
+    # Group array values using provided root key and value keys
+    #
+    # @example
+    #   fn = Transproc(:group, :tags, [:tag_name])
+    #
+    #   fn.call [
+    #     { task: 'Group it', tag: 'task' },
+    #     { task: 'Group it', tag: 'important' }
+    #   ]
+    #   # => [{ task: 'Group it', tags: [{ tag: 'task' }, { tag: 'important' }]]
+    #
+    # @param [Array] array The input array
+    # @param [Object] key The nesting root key
+    # @param [Object] keys The nesting value keys
+    #
+    # @return [Array]
+    #
+    # @api public
+    def group(array, key, keys)
+      grouped = Hash.new { |h, k| h[k] = [] }
+      array.each do |hash|
+        hash = hash.dup
+        child = {}
+        keys.each { |k| child[k] = hash.delete(k) }
+        grouped[hash] << child
+      end
+      grouped.map do |root, children|
+        root.merge(key => children)
+      end
     end
   end
 end

data/lib/transproc/coercions.rb

@@ -4,42 +4,154 @@ require 'bigdecimal'
 require 'bigdecimal/util'
 
 module Transproc
-  TRUE_VALUES = [true, 1, '1', 'on', 't', 'true', 'y', 'yes'].freeze
-  FALSE_VALUES = [false, 0, '0', 'off', 'f', 'false', 'n', 'no'].freeze
+  # Coercion functions for common types
+  #
+  # @api public
+  module Coercions
+    extend Functions
 
-  BOOLEAN_MAP = Hash[
-    TRUE_VALUES.product([true]) + FALSE_VALUES.product([false])
-  ].freeze
+    TRUE_VALUES = [true, 1, '1', 'on', 't', 'true', 'y', 'yes'].freeze
+    FALSE_VALUES = [false, 0, '0', 'off', 'f', 'false', 'n', 'no'].freeze
 
-  register(:to_string) do |value|
-    value.to_s
-  end
+    BOOLEAN_MAP = Hash[
+      TRUE_VALUES.product([true]) + FALSE_VALUES.product([false])
+    ].freeze
 
-  register(:to_integer) do |value|
-    value.to_i
-  end
+    # Coerce value into a string
+    #
+    # @example
+    #   Transproc(:to_string)[1]
+    #   # => "1"
+    #
+    # @param [Object] value The input value
+    #
+    # @return [String]
+    #
+    # @api public
+    def to_string(value)
+      value.to_s
+    end
 
-  register(:to_float) do |value|
-    value.to_f
-  end
+    # Coerce value into a symbol
+    #
+    # @example
+    #   Transproc(:to_symbol)['foo']
+    #   # => :foo
+    #
+    # @param [Object] value The input value
+    #
+    # @return [Symbol]
+    #
+    # @api public
+    def to_symbol(value)
+      value.to_sym
+    end
 
-  register(:to_decimal) do |value|
-    value.to_d
-  end
+    # Coerce value into a integer
+    #
+    # @example
+    #   Transproc(:to_integer)['1']
+    #   # => 1
+    #
+    # @param [Object] value The input value
+    #
+    # @return [Integer]
+    #
+    # @api public
+    def to_integer(value)
+      value.to_i
+    end
 
-  register(:to_boolean) do |value|
-    BOOLEAN_MAP.fetch(value)
-  end
+    # Coerce value into a float
+    #
+    # @example
+    #   Transproc(:to_float)['1.2']
+    #   # => 1.2
+    #
+    # @param [Object] value The input value
+    #
+    # @return [Float]
+    #
+    # @api public
+    def to_float(value)
+      value.to_f
+    end
 
-  register(:to_date) do |value|
-    Date.parse(value)
-  end
+    # Coerce value into a decimal
+    #
+    # @example
+    #   Transproc(:to_decimal)[1.2]
+    #   # => #<BigDecimal:7fca32acea50,'0.12E1',18(36)>
+    #
+    # @param [Object] value The input value
+    #
+    # @return [Decimal]
+    #
+    # @api public
+    def to_decimal(value)
+      value.to_d
+    end
 
-  register(:to_time) do |value|
-    Time.parse(value)
-  end
+    # Coerce value into a boolean
+    #
+    # @example
+    #   Transproc(:to_boolean)['true']
+    #   # => true
+    #   Transproc(:to_boolean)['f']
+    #   # => false
+    #
+    # @param [Object] value The input value
+    #
+    # @return [TrueClass,FalseClass]
+    #
+    # @api public
+    def to_boolean(value)
+      BOOLEAN_MAP.fetch(value)
+    end
+
+    # Coerce value into a date
+    #
+    # @example
+    #   Transproc(:to_date)['2015-04-14']
+    #   # => #<Date: 2015-04-14 ((2457127j,0s,0n),+0s,2299161j)>
+    #
+    # @param [Object] value The input value
+    #
+    # @return [Date]
+    #
+    # @api public
+    def to_date(value)
+      Date.parse(value)
+    end
+
+    # Coerce value into a time
+    #
+    # @example
+    #   Transproc(:to_time)['2015-04-14 12:01:45']
+    #   # => 2015-04-14 12:01:45 +0200
+    #
+    # @param [Object] value The input value
+    #
+    # @return [Time]
+    #
+    # @api public
+    def to_time(value)
+      Time.parse(value)
+    end
 
-  register(:to_datetime) do |value|
-    DateTime.parse(value)
+    # Coerce value into a datetime
+    #
+    # @example
+    #   Transproc(:to_datetime)['2015-04-14 12:01:45']
+    #   # => #<DateTime: 2015-04-14T12:01:45+00:00 ((2457127j,43305s,0n),+0s,2299161j)>
+    #
+    # @param [Object] value The input value
+    #
+    # @return [DateTime]
+    #
+    # @api public
+    def to_datetime(value)
+      DateTime.parse(value)
+    end
   end
 end