remap 2.0.2 → 2.1.5

data/lib/remap/rule/set.rb

@@ -2,41 +2,31 @@
 
 module Remap
   class Rule
-    class Set < self
-      using State::Extension
+    using State::Extension
 
-      attribute :value, Types.Interface(:call)
-      attribute :path, Path
+    # Set path to a static value
+    #
+    # @example Set path [:a, :b] to value "C"
+    #   value = Remap::Static::Fixed.new(value: "a value")
+    #   set = Remap::Rule::Set.new(value: value, path: [:a, :b])
+    #   state = Remap::State.call("ANY VALUE")
+    #   set.call(state).fetch(:value) # => { a: { b: "a value" } }
+    #
+    # @example Set path [:a, :b] to option :c
+    #   value = Remap::Static::Option.new(name: :c)
+    #   set = Remap::Rule::Set.new(value: value, path: [:a, :b])
+    #   state = Remap::State.call("ANY VALUE", options: { c: "C" })
+    #   set.call(state).fetch(:value) # => { a: { b: "C" } }
+    class Set < Concrete
+      # @return [Static]
+      attribute :value, Static, alias: :rule
 
-      # Returns {value} mapped to {path} regardless of input
-      #
-      # @param state [State]
-      #
-      # @example Given an option
-      #   class Mapper < Remap::Base
-      #     option :name
-      #
-      #     define do
-      #       set [:person, :name], to: option(:name)
-      #     end
-      #   end
-      #
-      #   Mapper.call(input, name: "John") # => { person: { name: "John" } }
-      #
-      # @example Given a value
-      #   class Mapper < Remap::Base
-      #     define do
-      #       set [:api_key], to: value("ABC-123")
-      #     end
-      #   end
-      #
-      #   Mapper.call(input) # => { api_key: "ABC-123" }
-      #
-      # @return [State]
-      def call(state)
-        path.call(state) do
-          value.call(state)
-        end
+      # @return [Path::Output]
+      attribute :path, Path::Output
+
+      # @see Rule#call
+      def call(...)
+        rule.call(...).then(&path)
       end
     end
   end

data/lib/remap/rule/support/collection/empty.rb

@@ -3,19 +3,19 @@
 module Remap
   class Rule
     class Collection
-      class Empty < Unit
-        using State::Extension
+      using State::Extension
 
-        attribute? :rules, Value(EMPTY_ARRAY).default { EMPTY_ARRAY }
+      # Represents an empty rule block
+      class Empty < Unit
+        attribute? :rules, Value(EMPTY_ARRAY), default: EMPTY_ARRAY
 
         # Represents an empty define block, without any rules
         #
-        # @param input [Any]
-        # @param state [State]
+        # @param state [State<T>]
         #
-        # @return [Monad::Failure]
+        # @return [State<T>]
         def call(state)
-          state.problem("No rules, empty block")
+          state.notice!("No rules, empty block")
         end
       end
     end

data/lib/remap/rule/support/collection/filled.rb

@@ -3,23 +3,36 @@
 module Remap
   class Rule
     class Collection
-      class Filled < Unit
-        using State::Extension
+      using State::Extension
 
+      # Represents a non-empty rule block
+      #
+      # @example A collection containing a single rule
+      #   state = Remap::State.call("A")
+      #   void = Remap::Rule::Void.call({})
+      #   rule = Remap::Rule::Collection.call([void])
+      #   error = -> failure { raise failure.exception }
+      #   rule.call(state, &error).fetch(:value) # => "A"
+      class Filled < Unit
+        # @return [Array<Rule>]
         attribute :rules, [Types.Interface(:call)], min_size: 1
 
         # Represents a non-empty define block with one or more rules
-        # Calls every {#rules} with {input} and merges the output
+        # Calls every {#rules} with state and merges the output
         #
         # @param state [State]
         #
         # @return [State]
-        def call(state)
-          rules.map do |rule|
-            Thread.new(rule, state) { _1.call(_2) }
-          end.map(&:value).reduce do |acc, inner_state|
-            acc.merged(inner_state)
+        def call(state, &error)
+          unless error
+            raise ArgumentError, "Collection::Filled#call(state, &error) requires a block"
           end
+
+          rules.map do |rule|
+            rule.call(state) do |failure|
+              return error[failure]
+            end
+          end.reduce(&:combine)
         end
       end
     end

data/lib/remap/rule/support/collection.rb

@@ -2,9 +2,17 @@
 
 module Remap
   class Rule
-    class Collection < Dry::Interface
-      def to_proc
-        method(:call).to_proc
+    # Represents a block defined by a rule
+    class Collection < Abstract
+      attribute :rules, Array
+
+      # @param state [State]
+      #
+      # @return [State]
+      #
+      # @abstract
+      def call(state)
+        raise NotImplementedError, "#{self.class}#call not implemented"
       end
     end
   end

data/lib/remap/rule/support/enum.rb

@@ -2,17 +2,32 @@
 
 module Remap
   class Rule
-    class Enum
-      include Dry::Core::Constants
+    class Enum < Proxy
       include Dry::Monads[:maybe]
 
-      extend Dry::Initializer
-
+      # @return [Hash]
       option :mappings, default: -> { Hash.new { default } }
+
+      # @return [Maybe]
       option :default, default: -> { None() }
 
       alias execute instance_eval
 
+      # Builds an enumeration using the block as context
+      #
+      # @example
+      #   enum = Remap::Rule::Enum.call do
+      #     from "B", to: "C"
+      #     value "A"
+      #     otherwise "D"
+      #   end
+      #
+      #   enum.get("A") # => "A"
+      #   enum.get("B") # => "C"
+      #   enum.get("C") # => "C"
+      #   enum.get("MISSING") # => "D"
+      #
+      # @return [Any]
       def self.call(&block)
         unless block
           raise ArgumentError, "no block given"
@@ -21,40 +36,48 @@ module Remap
         new.tap { _1.execute(&block) }
       end
 
-      def [](key)
-        mappings[key]
-      end
-
+      # Translates key into a value using predefined mappings
+      #
+      # @param key [#hash]
+      #
+      # @yield [String]
+      #   If the key is not found & no default value is set
+      #
+      # @return [Any]
       def get(key, &error)
         unless error
           return get(key) { raise Error, _1 }
         end
 
-        mappings[key].bind { return _1 }.or do
+        self[key].bind { return _1 }.or do
           error["Enum key [#{key}] not found among [#{mappings.keys.inspect}]"]
         end
       end
       alias call get
 
-      # Map all keys in {keys} to {to}
-      #
-      # @return [VOID]
+      # @return [Maybe]
+      def [](key)
+        mappings[key]
+      end
+
+      # @return [void]
       def from(*keys, to:)
+        value = Some(to)
+
         keys.each do |key|
-          mappings[key] = Some(to)
+          mappings[key] = value
+          mappings[to] = value
         end
       end
 
-      # Maps {var} to {var}
-      #
-      # @return [VOID]
-      def value(id)
-        from(id, to: id)
+      # @return [void]
+      def value(*ids)
+        ids.each do |id|
+          from(id, to: id)
+        end
       end
 
-      # Fallback value when {#call} fails
-      #
-      # @return [Void]
+      # @return [void]
       def otherwise(value)
         mappings.default = Some(value)
       end

data/lib/remap/rule/void.rb

@@ -2,27 +2,26 @@
 
 module Remap
   class Rule
-    class Void < self
-      using State::Extension
+    using State::Extension
 
-      # Returns its input
+    # Represents a mapping without block
+    #
+    # @example Maps "A" to "A"
+    #   class Mapper < Remap::Base
+    #     define do
+    #       map
+    #     end
+    #   end
+    #
+    #  Mapper.call("A") # => "A"
+    class Void < Concrete
+      # @param state [State<T>]
       #
-      # @param state [State]
-      #
-      # @example An empty rule
-      #   class Mapper < Remap::Base
-      #     define do
-      #       map do
-      #         # Empty ...
-      #       end
-      #     end
-      #   end
-      #
-      #   Mapper.call(input) # => input
-      #
-      # @return [State]
+      # @return [State<T>]
       def call(state)
-        state.bind { _2.set(_1) }
+        state.bind do |value, inner_state|
+          inner_state.set(value)
+        end
       end
     end
   end

data/lib/remap/rule/wrap.rb

@@ -1,29 +1,37 @@
 # frozen_string_literal: true
 
-require "active_support/core_ext/array/wrap"
-
 module Remap
   class Rule
-    class Wrap < self
-      using State::Extension
+    using State::Extension
 
+    # Wraps rule in a type
+    #
+    # @example Maps { name: "Ford" } to { cars: ["Ford"] }
+    #   class Mapper < Remap::Base
+    #     define do
+    #       to :cars do
+    #         wrap(:array) do
+    #           map :name
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    #   Mapper.call({ name: "Ford" }) # => { cars: ["Ford"] }
+    class Wrap < Concrete
+      # @return [:array]
       attribute :type, Value(:array)
-      attribute :rule, Types::Any
+
+      # @return [Rule]
+      attribute :rule, Types::Rule
 
       # Wraps the output from {#rule} in a {#type}
       #
-      # @param state [State]
-      #
-      # @example mapps { car: "Volvo" } to { cars: ["Volvo"] }
-      #   to :cars do
-      #     wrap(:array) do
-      #       map :car
-      #     end
-      #   end
-      #
-      # @return [State]
-      def call(state)
-        rule.call(state).fmap { Array.wrap(_1) }
+      # @see Rule#call
+      def call(...)
+        rule.call(...).fmap do |value|
+          Array.wrap(value)
+        end
       end
     end
   end

data/lib/remap/rule.rb

@@ -1,8 +1,15 @@
 # frozen_string_literal: true
 
 module Remap
-  class Rule < Dry::Concrete
+  class Rule < Dry::Interface
     defines :requirement
     requirement Types::Any
+
+    # @param state [State]
+    #
+    # @abstract
+    def call(state)
+      raise NotImplementedError, "#{self.class}#call not implemented"
+    end
   end
 end

data/lib/remap/selector/all.rb

@@ -2,18 +2,40 @@
 
 module Remap
   class Selector
-    class All < Concrete
-      using State::Extension
+    using State::Extension
 
+    # Selects all elements from a state
+    #
+    # @example Select all keys from array hash
+    #   state = Remap::State.call([{a: "A1"}, {a: "A2"}])
+    #   all = Remap::Selector::All.new
+    #   result = all.call(state) do |other_state|
+    #     value = other_state.fetch(:value).class
+    #     other_state.merge(value: value)
+    #   end
+    #   result.fetch(:value) # => [Hash, Hash]
+    class All < Concrete
       requirement Types::Enumerable
 
-      def call(state, &block)
-        state.bind(quantifier: "*") do |enumerable, inner_state, &error|
-          requirement[enumerable] do
-            return error["Expected an enumeration"]
+      # Iterates over state and passes each value to block
+      #
+      # @param outer_state [State<Enumerable<T>>]
+      #
+      # @yieldparam [State<T>]
+      # @yieldreturn [State<U>]
+      #
+      # @return [State<U>]
+      def call(outer_state, &block)
+        unless block_given?
+          raise ArgumentError, "All selector requires an iteration block"
+        end
+
+        outer_state.bind(quantifier: "*") do |enum, state|
+          requirement[enum] do
+            state.fatal!("Expected enumeration but got %p (%s)", enum, enum.class)
           end
 
-          inner_state.map(&block)
+          state.map(&block)
         end
       end
     end

data/lib/remap/selector/index.rb

@@ -2,36 +2,44 @@
 
 module Remap
   class Selector
+    using State::Extension
+
+    # Selects value at given index
+    #
+    # @example Select the value at index 1 from a array
+    #   state = Remap::State.call([:one, :two, :tree])
+    #   result = Remap::Selector::Index.new(1).call(state)
+    #   result.fetch(:value) # => :two
     class Index < Unit
-      using State::Extension
-
+      # @return [Integer]
       attribute :index, Integer
 
       requirement Types::Array
 
-      # Fetches {#input[value]} and passes it to {block}
+      # Selects the {#index}th element from state and passes it to block
       #
-      # @param [State] state
+      # @param outer_state [State<Array<T>>]
       #
-      # @yieldparam [State]
-      # @yieldreturn [State<T>]
-
-      # @return [State<T>]
-      def call(state, &block)
-        unless block
-          raise ArgumentError, "no block given"
-        end
+      # @yieldparam [State<T>]
+      # @yieldreturn [State<U>]
+      #
+      # @return [State<U>]
+      def call(outer_state, &block)
+        return call(outer_state, &:itself) unless block
 
-        state.bind(index: index) do |array, inner_state, &error|
+        outer_state.bind(index: index) do |array, state|
           requirement[array] do
-            return error["Expected an array"]
+            state.fatal!("Expected array but got %p (%s)", array, array.class)
           end
 
           element = array.fetch(index) do
-            return error["No element on index at index #{index}"]
+            state.ignore!("Index %s in array %p (%s) not found",
+                          index,
+                          array,
+                          array.class)
           end
 
-          block[inner_state.set(element, index: index)]
+          state.set(element, index: index).then(&block)
         end
       end
     end

data/lib/remap/selector/key.rb

@@ -2,35 +2,50 @@
 
 module Remap
   class Selector
+    using State::Extension
+
+    # Selects value at key from state
+    #
+    # @example Select the value at key :name from a hash
+    #   state = Remap::State.call({ name: "John" })
+    #   selector = Remap::Selector::Key.new(:name)
+    #
+    #   selector.call(state) do |state|
+    #     state.fetch(:value)
+    #   end
     class Key < Unit
-      using State::Extension
+      # @return [#hash
+      attribute :key, Types::Key
 
-      attribute :key, Types::Hash.not
-      requirement Types::Hash.constrained(min_size: 1)
+      requirement Types::Hash
 
-      # Fetches {#input[value]} and passes it to {block}
+      # Selects {#key} from state and passes it to block
       #
-      # @param [State] state
+      # @param outer_state [State<Hash<K, V>>]
       #
-      # @yieldparam [State]
-      # @yieldreturn [State<T>]
-
-      # @return [State<T>]
-      def call(state, &block)
-        unless block
-          return call(state, &:itself)
+      # @yieldparam [State<V>]
+      # @yieldreturn [State<U>]
+      #
+      # @return [State<U>]
+      def call(outer_state, &block)
+        unless block_given?
+          raise ArgumentError, "The key selector requires an iteration block"
         end
 
-        state.bind(key: key) do |hash, inner_state, &error|
+        outer_state.bind(key: key) do |hash, state|
           requirement[hash] do
-            return error["Expected a hash"]
+            state.fatal!("Expected hash but got %p (%s)", hash, hash.class)
           end
 
           value = hash.fetch(key) do
-            return error["Key [#{key}] not found"]
+            state.ignore!("Key %p (%s) not found in hash %p (%s)",
+                          key,
+                          key.class,
+                          hash,
+                          hash.class)
           end
 
-          block[inner_state.set(value, key: key)]
+          state.set(value, key: key).then(&block)
         end
       end
     end

data/lib/remap/selector.rb

@@ -1,12 +1,29 @@
 # frozen_string_literal: true
 
 module Remap
+  # Defines how a path element, or selector
+  # Specifies how a value is extracted from a state
   class Selector < Dry::Interface
     defines :requirement, type: Types::Any.constrained(type: Dry::Types::Type)
     requirement Types::Any
 
+    # Selects value from state, package it as a state and passes it to block
+    #
+    # @param state [State]
+    #
+    # @yieldparam [State]
+    # @yieldreturn [State]
+    #
+    # @return [State]
+    #
+    # @abstract
+    def call(state)
+      raise NotImplementedError, "#{self.class}#call not implemented"
+    end
+
     private
 
+    # @return [Dry::Types::Type]
     def requirement
       self.class.requirement
     end