transproc 0.2.4 → 0.3.0

data/lib/transproc/recursion.rb

@@ -15,13 +15,13 @@ module Transproc
   #
   # @api public
   module Recursion
-    extend Functions
+    extend Registry
 
-    IF_ENUMERABLE = -> fn { Transproc(:is, Enumerable, fn) }
+    IF_ENUMERABLE = -> fn { Conditional[:is, Enumerable, fn] }
 
-    IF_ARRAY = -> fn { Transproc(:is, Array, fn) }
+    IF_ARRAY = -> fn { Conditional[:is, Array, fn] }
 
-    IF_HASH = -> fn { Transproc(:is, Hash, fn) }
+    IF_HASH = -> fn { Conditional[:is, Hash, fn] }
 
     # Recursively apply the provided transformation function to an enumerable
     #
@@ -43,7 +43,7 @@ module Transproc
     # @return [Enumerable]
     #
     # @api public
-    def recursion(value, fn)
+    def self.recursion(value, fn)
       result = fn[value]
       guarded = IF_ENUMERABLE[-> v { recursion(v, fn) }]
 
@@ -74,7 +74,7 @@ module Transproc
     # @return [Array]
     #
     # @api public
-    def array_recursion(value, fn)
+    def self.array_recursion(value, fn)
       result = fn[value]
       guarded = IF_ARRAY[-> v { array_recursion(v, fn) }]
 
@@ -96,7 +96,7 @@ module Transproc
     # @return [Hash]
     #
     # @api public
-    def hash_recursion(value, fn)
+    def self.hash_recursion(value, fn)
       result = fn[value]
       guarded = IF_HASH[-> v { hash_recursion(v, fn) }]
 
@@ -106,5 +106,9 @@ module Transproc
 
       result
     end
+
+    # @deprecated Register methods globally
+    (methods - Registry.methods - Registry.instance_methods)
+      .each { |name| Transproc.register name, t(name) }
   end
 end

data/lib/transproc/registry.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module Transproc
   # Container to define transproc functions in, and access them via `[]` method
   # from the outside of the module
@@ -6,7 +8,7 @@ module Transproc
   #   module FooMethods
   #     extend Transproc::Registry
   #
-  #     def foo(name, prefix)
+  #     def self.foo(name, prefix)
   #       [prefix, '_', name].join
   #     end
   #   end
@@ -15,10 +17,9 @@ module Transproc
   #   fn['qux'] # => 'qux_baz'
   #
   #   module BarMethods
-  #     # extend Transproc::Registry
-  #     include FooMethods
+  #     extend FooMethods
   #
-  #     def bar(*args)
+  #     def self.bar(*args)
   #       foo(*args).upcase
   #     end
   #   end
@@ -31,10 +32,11 @@ module Transproc
   #
   # @api public
   module Registry
-    # Builds the transproc function either from a Proc, or from the module method
+    # Builds the transformation
     #
     # @param [Proc, Symbol] fn
-    #   Either a proc, or a name of the module's function to be wrapped to transproc
+    #   A proc, a name of the module's own function, or a name of imported
+    #   procedure from another module
     # @param [Object, Array] args
     #   Args to be carried by the transproc
     #
@@ -42,85 +44,81 @@ module Transproc
     #
     # @alias :t
     #
-    # @api public
     def [](fn, *args)
-      fun = fn.is_a?(Proc) ? fn : method(fn).to_proc
-      Transproc::Function.new(fun, args: args)
+      Function.new(fetch(fn), args: args, name: fn)
     end
     alias_method :t, :[]
 
-    # Forwards the named method (transproc) to another module
+    # Imports either a method (converted to a proc) from another module, or
+    # all methods from that module.
     #
-    # Allows using transprocs from other modules without including those
-    # modules as a whole
+    # If the external module is a registry, looks for its imports too.
     #
     # @example
     #   module Foo
-    #     extend Transproc::Registry
-    #
-    #     def foo(value)
+    #     def self.foo(value)
     #       value.upcase
     #     end
     #
-    #     def bar(value)
+    #     def self.bar(value)
     #       value.downcase
     #     end
     #  end
     #
+    #  module Qux
+    #    def self.qux(value)
+    #      value.reverse
+    #    end
+    #  end
+    #
     #  module Bar
     #     extend Transproc::Registry
     #
-    #     uses :foo, from: Foo, as: :baz
-    #     uses :bar, from: Foo
+    #     import :foo, from: Foo, as: :baz
+    #     import :bar, from: Foo
+    #     import Qux
     #  end
     #
     #  Bar[:baz]['Qux'] # => 'QUX'
     #  Bar[:bar]['Qux'] # => 'qux'
+    #  Bar[:qux]['Qux'] # => 'xuQ'
     #
-    # @param [String, Symbol] name
-    # @option [Class] :from The module to take the method from
-    # @option [String, Symbol] :as
+    # @param [Module, #to_sym] name
+    # @option [Module] :from The module to take the method from
+    # @option [#to_sym] :as
     #   The name of imported transproc inside the current module
     #
-    # @return [undefined]
+    # @return [itself] self
+    #
+    # @alias :import
     #
-    # @api public
-    def uses(name, options = {})
-      source   = options.fetch(:from)
-      new_name = options.fetch(:as, name)
-      define_method(new_name) { |*args| source.__send__(name, *args) }
+    def import(source, options = nil)
+      @store = store.import(source, options)
+      self
     end
+    alias_method :uses, :import
 
-    # @api private
-    def self.extended(target)
-      target.extend(ClassMethods)
+    # The store of procedures imported from external modules
+    #
+    # @return [Transproc::Store]
+    #
+    def store
+      @store ||= Store.new
     end
 
-    # @api private
-    module ClassMethods
-      # Makes `[]` and all functions defined in the included modules
-      # accessible in their receiver
-      #
-      # @api private
-      def included(other)
-        other.extend(Transproc::Registry, self)
-      end
-
-      # Makes newly module-defined functions accessible via `[]` method
-      # by adding it to the module's eigenclass
-      #
-      # @api private
-      def method_added(name)
-        module_function(name)
-      end
-
-      # Makes undefined methods inaccessible via `[]` method by
-      # undefining it from the module's eigenclass
-      #
-      # @api private
-      def method_undefined(name)
-        singleton_class.__send__(:undef_method, name)
-      end
+    # Gets the procedure for creating a transproc
+    #
+    # @param [#call, Symbol] fn
+    #   Either the procedure, or the name of the method of the current module,
+    #   or the registered key of imported procedure in a store.
+    #
+    # @return [#call]
+    #
+    def fetch(fn)
+      return fn unless fn.instance_of? Symbol
+      respond_to?(fn) ? method(fn) : store.fetch(fn)
+    rescue
+      raise FunctionNotFoundError.new(fn, self)
     end
   end
 end

data/lib/transproc/rspec.rb

@@ -0,0 +1,59 @@
+# encoding: utf-8
+
+# ==============================================================================
+# Examples for testing transproc functions
+# ==============================================================================
+
+shared_context :call_transproc do
+  let!(:initial)  { input.dup rescue input      }
+  let!(:function) { described_class[*arguments] }
+  let!(:result)   { function[input]             }
+end
+
+shared_examples :transforming_data do
+  it '[returns the expected output]' do
+    expect(result).to eql(output), <<-REPORT.gsub(/.+\|/, "")
+      |
+      |fn = #{described_class}#{Array[*arguments]}
+      |
+      |fn[#{input}]
+      |
+      |  expected: #{output}
+      |       got: #{result}
+    REPORT
+  end
+end
+
+shared_examples :transforming_immutable_data do
+  include_context :call_transproc
+
+  it_behaves_like :transforming_data
+
+  it '[keeps input unchanged]' do
+    expect(input).to eql(initial), <<-REPORT.gsub(/.+\|/, "")
+      |
+      |fn = #{described_class}#{Array[*arguments]}
+      |
+      |expected: not to change #{initial}
+      |     got: changed it to #{input}
+    REPORT
+  end
+end
+
+shared_examples :mutating_input_data do
+  include_context :call_transproc
+
+  it_behaves_like :transforming_data
+
+  it '[changes input]' do
+    expect(input).to eql(output), <<-REPORT.gsub(/.+\|/, "")
+      |
+      |fn = #{described_class}#{Array[*arguments]}
+      |
+      |fn[#{input}]
+      |
+      |expected: to change input to #{output}
+      |     got: #{input}
+    REPORT
+  end
+end

data/lib/transproc/store.rb

@@ -0,0 +1,94 @@
+# encoding: utf-8
+
+module Transproc
+  # Immutable collection of named procedures from external modules
+  #
+  # @api private
+  #
+  class Store
+    # @!attribute [r] methods
+    #
+    # @return [Hash] The associated list of imported procedures
+    #
+    attr_reader :methods
+
+    # @!scope class
+    # @!name new(methods = {})
+    # Creates an immutable store with a hash of procedures
+    #
+    # @param [Hash] methods
+    #
+    # @return [Transproc::Store]
+
+    # @private
+    def initialize(methods = {})
+      @methods = methods.dup.freeze
+      freeze
+    end
+
+    # Returns a procedure by its key in the collection
+    #
+    # @param [Symbol] key
+    #
+    # @return [Proc]
+    #
+    def fetch(key)
+      methods.fetch(key.to_sym)
+    end
+
+    # Imports proc(s) to the collection from another module
+    #
+    # @overload add(source)
+    #   @param  (see #import_methods)
+    #   @return (see #import_methods)
+    #
+    # @overload add(source, options)
+    #   @param  (see #import_method)
+    #   @return (see #import_method)
+    #
+    def import(source, options = nil)
+      return import_methods(source) if source.instance_of?(Module)
+      import_method(source, options)
+    end
+
+    protected
+
+    # Creates new immutable collection from the current one,
+    # updated with either the module's singleton method,
+    # or the proc having been imported from another module.
+    #
+    # @param [Symbol] source The name of the method, or imported proc
+    # @param [Hash] options
+    # @option options [Module] :from
+    #   The module whose method or imported proc should be added
+    # @option options [Symbol] :as
+    #   The key for the proc in the current collection
+    #
+    # @return [Transproc::Store]
+    #
+    def import_method(source, options)
+      src  = options.fetch(:from)
+      name = source.to_sym
+      key  = options.fetch(:as) { name }.to_sym
+      fn   = src.is_a?(Registry) ? src.fetch(name) : src.method(name)
+
+      self.class.new(methods.merge(key => fn))
+    end
+
+    # Creates new immutable collection from the current one,
+    # updated with all singleton methods and imported methods
+    # from the other module
+    #
+    # @param [Module] source The module to import procedures from
+    #
+    # @return [Transproc::Store]
+    #
+    def import_methods(source)
+      list =  source.public_methods - Registry.instance_methods - Module.methods
+      list -= [:initialize] # for compatibility with Rubinius
+      list += source.store.methods.keys if source.is_a? Registry
+
+      list.inject(self) { |a, e| a.import_method(e, from: source) }
+    end
+  end # class Store
+end # module Transproc

data/lib/transproc/support/deprecations.rb

@@ -0,0 +1,11 @@
+module Transproc
+  module Deprecations
+    def self.announce(name, msg)
+      warn <<-MSG.gsub(/^\s+/, '')
+        #{name} is deprecated and will be removed in 1.0.0.
+        #{msg}
+        #{caller.detect { |l| !l.include?('lib/transproc')}}
+      MSG
+    end
+  end
+end

data/lib/transproc/version.rb

@@ -1,3 +1,3 @@
 module Transproc
-  VERSION = '0.2.4'.freeze
+  VERSION = '0.3.0'.freeze
 end

data/spec/unit/array_transformations_spec.rb

@@ -1,9 +1,11 @@
 require 'spec_helper'
 
 describe Transproc::ArrayTransformations do
+  let(:hashes) { Transproc::HashTransformations }
+
   describe '.extract_key' do
     it 'extracts values by key from all hashes' do
-      extract_key = t(:extract_key, 'name')
+      extract_key = described_class.t(:extract_key, 'name')
 
       original = [
         { 'name' => 'Alice', 'role' => 'sender' },
@@ -22,7 +24,7 @@ describe Transproc::ArrayTransformations do
 
   describe '.extract_key!' do
     it 'extracts values by key from all hashes' do
-      extract_key = t(:extract_key!, 'name')
+      extract_key = described_class.t(:extract_key!, 'name')
 
       input = [
         { 'name' => 'Alice', 'role' => 'sender' },
@@ -39,7 +41,7 @@ describe Transproc::ArrayTransformations do
 
   describe '.insert_key' do
     it 'wraps values to tuples with given key' do
-      insert_key = t(:insert_key, 'name')
+      insert_key = described_class.t(:insert_key, 'name')
 
       original = ['Alice', 'Bob', nil]
 
@@ -58,7 +60,7 @@ describe Transproc::ArrayTransformations do
 
   describe '.insert_key!' do
     it 'wraps values to tuples with given key' do
-      insert_key = t(:insert_key!, 'name')
+      insert_key = described_class.t(:insert_key!, 'name')
 
       original = ['Alice', 'Bob', nil]
 
@@ -77,7 +79,7 @@ describe Transproc::ArrayTransformations do
 
   describe '.add_keys' do
     it 'returns a new array with missed keys added to tuples' do
-      add_keys = t(:add_keys, [:foo, :bar, :baz])
+      add_keys = described_class.t(:add_keys, [:foo, :bar, :baz])
 
       original = [{ foo: 'bar' }, { bar: 'baz' }]
 
@@ -95,7 +97,7 @@ describe Transproc::ArrayTransformations do
 
   describe '.add_keys!' do
     it 'adds missed keys to tuples' do
-      add_keys = t(:add_keys!, [:foo, :bar, :baz])
+      add_keys = described_class.t(:add_keys!, [:foo, :bar, :baz])
 
       original = [{ foo: 'bar' }, { bar: 'baz' }]
 
@@ -113,7 +115,7 @@ describe Transproc::ArrayTransformations do
 
   describe '.map_array' do
     it 'applies funtions to all values' do
-      map = t(:map_array, t(:symbolize_keys))
+      map = described_class.t(:map_array, hashes[:symbolize_keys])
 
       original = [
         { 'name' => 'Jane', 'title' => 'One' },
@@ -134,7 +136,7 @@ describe Transproc::ArrayTransformations do
 
   describe '.map_array!' do
     it 'updates array with the result of the function applied to each value' do
-      map = t(:map_array!, t(:symbolize_keys))
+      map = described_class.t(:map_array!, hashes[:symbolize_keys])
 
       input = [
         { 'name' => 'Jane', 'title' => 'One' },
@@ -154,7 +156,7 @@ describe Transproc::ArrayTransformations do
 
   describe '.wrap' do
     it 'returns a new array with wrapped hashes' do
-      wrap = t(:wrap, :task, [:title])
+      wrap = described_class.t(:wrap, :task, [:title])
 
       input = [{ name: 'Jane', title: 'One' }]
       output = [{ name: 'Jane', task: { title: 'One' } }]
@@ -164,10 +166,10 @@ describe Transproc::ArrayTransformations do
 
     it 'returns a array new with deeply wrapped hashes' do
       wrap =
-        t(
+        described_class.t(
           :map_array,
-          t(:nest, :user, [:name, :title]) +
-          t(:map_value, :user, t(:nest, :task, [:title]))
+          hashes[:nest, :user, [:name, :title]] +
+          hashes[:map_value, :user, hashes[:nest, :task, [:title]]]
         )
 
       input = [{ name: 'Jane', title: 'One' }]
@@ -177,7 +179,7 @@ describe Transproc::ArrayTransformations do
     end
 
     it 'adds data to the existing tuples' do
-      wrap = t(:wrap, :task, [:title])
+      wrap = described_class.t(:wrap, :task, [:title])
 
       input  = [{ name: 'Jane', task: { priority: 1 }, title: 'One' }]
       output = [{ name: 'Jane', task: { priority: 1, title: 'One' } }]
@@ -187,7 +189,7 @@ describe Transproc::ArrayTransformations do
   end
 
   describe '.group' do
-    subject(:group) { t(:group, :tasks, [:title]) }
+    subject(:group) { described_class.t(:group, :tasks, [:title]) }
 
     it 'returns a new array with grouped hashes' do
       input  = [{ name: 'Jane', title: 'One' }, { name: 'Jane', title: 'Two' }]
@@ -241,7 +243,7 @@ describe Transproc::ArrayTransformations do
   end
 
   describe '.ungroup' do
-    subject(:ungroup) { t(:ungroup, :tasks, [:title]) }
+    subject(:ungroup) { described_class.t(:ungroup, :tasks, [:title]) }
 
     it 'returns a new array with ungrouped hashes' do
       input = [{ name: 'Jane', tasks: [{ title: 'One' }, { title: 'Two' }] }]
@@ -294,8 +296,8 @@ describe Transproc::ArrayTransformations do
   end
 
   describe '.combine' do
-    let(:input) do
-      [
+    it 'merges hashes from arrays using provided join keys' do
+      input = [
         # parent users
         [
           { name: 'Jane', email: 'jane@doe.org' },
@@ -319,22 +321,24 @@ describe Transproc::ArrayTransformations do
           ]
         ]
       ]
-    end
 
-    let(:output) do
-      [
+      output = [
         { name: 'Jane', email: 'jane@doe.org', tasks: [
           { user: 'Jane', title: 'One', tags: [{ task: 'One', tag: 'red' }] },
           { user: 'Jane', title: 'Two', tags: [] }]
         },
-        { name: 'Joe', email: 'joe@doe.org', tasks: [
-          { user: 'Joe', title: 'Three', tags: [{ task: 'Three', tag: 'blue' }] }]
+        {
+          name: 'Joe', email: 'joe@doe.org', tasks: [
+            {
+              user: 'Joe', title: 'Three', tags: [
+                { task: 'Three', tag: 'blue' }
+              ]
+            }
+          ]
         }
       ]
-    end
 
-    it 'merges hashes from arrays using provided join keys' do
-      combine = t(:combine, [
+      combine = described_class.t(:combine, [
         [:tasks, { name: :user }, [[:tags, title: :task]]]
       ])