remap 2.0.3 → 2.1.0

data/lib/remap/rule/map.rb

@@ -2,62 +2,72 @@
 
 module Remap
   class Rule
-    class Map < self
-      using State::Extension
+    using Extensions::Enumerable
+    using State::Extension
 
-      attribute :rule, Types.Interface(:call)
-      attribute :path, Path
+    # Maps an input path to an output path
+    #
+    # @example Map { name: "Ford" } to { person: { name: "Ford" } }
+    #   class Mapper < Remap::Base
+    #     define do
+    #       map :name, to: [:person, :name]
+    #     end
+    #   end
+    #
+    #   Mapper.call({ name: "Ford" }) # => { person: { name: "Ford" } }
+    class Map < Abstract
+      class Path < Struct
+        Output = Remap::Path::Output
+        Input = Remap::Path::Input
 
-      # Maps {input} in 4 steps
-      #
-      # 1. Extract value from {input} using {path}
-      # 2. For each yielded value
-      #   2.1. Map value using {#rule}
-      #   2.2. Map value using {#fn}
+        attribute :output, Output.default { Output.call(EMPTY_ARRAY) }
+        attribute :input, Input.default { Input.call(EMPTY_ARRAY) }
+      end
 
-      # @example Map :a, to :b and add 5
-      #  map = Map.new({
-      #    path: { map: :a, to: :b },
-      #    rule: Void.new,
-      #  })
-      #
-      #  map.adjust do |value|
-      #    value + 5
-      #  end
+      # @return [Hash]
+      attribute? :path, Path.default { Path.call(EMPTY_HASH) }
+
+      # @return [Rule]
+      attribute :rule, Rule.default { Void.call(EMPTY_HASH) }
+
+      # @return [Array<String>]
+      attribute? :backtrace, Types::Backtrace, default: EMPTY_ARRAY
+
+      order :Optional, :Required
+
+      # Represents a required or optional mapping rule
       #
-      #  map.call(a: 10) # => Success({ b: 15 })
+      # @param state [State]
       #
-      # @param input [Any] Value to be mapped
-      # @param state [State] Current state
+      # @return [State]
       #
-      # @return [Monad::Result]
-      def call(state)
-        path.call(state) do |inner_state|
-          rule.call(inner_state).then do |init|
-            fn.reduce(init) do |inner, fn|
-              fn[inner]
-            end
-          end
+      # @abstract
+      def call(state, &error)
+        unless error
+          raise ArgumentError, "Map#call(state, &error) requires error handler block"
+        end
+
+        notice = catch :fatal do
+          return path.input.call(state) do |inner_state|
+            rule.call(inner_state) do |failure|
+              return error[failure]
+            end.then(&callback)
+          end.then(&path.output)
         end
+
+        raise notice.traced(backtrace).exception
       end
 
-      # Post-processor for {#call}
-      #
-      # @example Add 5 to mapped value
-      #  class Mapper < Remap
-      #    define do
-      #      map.adjust do |value|
-      #        value + 5
-      #      end
-      #    end
-      #  end
-      #
-      #  Mapper.call(10) # => 15
+      # A post-processor method
       #
-      # @yieldparam value [Any] Mapped value
-      # @yieldreturn [Monad::Result, Any]
+      # @example Upcase mapped value
+      #   state = Remap::State.call("Hello World")
+      #   map = Remap::Rule::Map.call({})
+      #   upcase = map.adjust(&:upcase)
+      #   error = -> failure { raise failure.exception }
+      #   upcase.call(state, &error).fetch(:value) # => "HELLO WORLD"
       #
-      # @return [void]
+      # @return [Map]
       def adjust(&block)
         add do |state|
           state.execute(&block)
@@ -65,45 +75,156 @@ module Remap
       end
       alias then adjust
 
+      # A pending rule
+      #
+      # @param reason [String]
+      #
+      # @example Pending mapping
+      #   state = Remap::State.call(:value)
+      #   map = Remap::Rule::Map.call({})
+      #   pending = map.pending("this is pending")
+      #   error = -> failure { raise failure.exception }
+      #   pending.call(state, &error).key?(:value) # => false
+      #
+      # @return [Map]
       def pending(reason = "Pending mapping")
         add do |state|
-          state.problem(reason)
+          state.notice!(reason)
         end
       end
 
+      # An enumeration processor
+      #
+      # @example A mapped enum
+      #   enum = Remap::Rule::Map.call({}).enum do
+      #     value "A", "B"
+      #     otherwise "C"
+      #   end
+      #
+      #   error = -> failure { raise failure.exception }
+      #
+      #   a = Remap::State.call("A")
+      #   enum.call(a, &error).fetch(:value) # => "A"
+      #
+      #   b = Remap::State.call("B")
+      #   enum.call(b, &error).fetch(:value) # => "B"
+      #
+      #   c = Remap::State.call("C")
+      #   enum.call(c, &error).fetch(:value) # => "C"
+      #
+      #   d = Remap::State.call("D")
+      #   enum.call(d, &error).fetch(:value) # => "C"
+      #
+      # @return [Map]
       def enum(&block)
-        add do |state|
-          state.fmap do |id, &error|
-            Enum.call(&block).get(id, &error)
+        add do |outer_state|
+          outer_state.fmap do |id, state|
+            Enum.call(&block).get(id) do
+              state.ignore!("Enum value %p (%s) not defined", id, id.class)
+            end
           end
         end
       end
 
+      # Keeps map, only if block is true
+      #
+      # @example Keep if value contains "A"
+      #   map = Remap::Rule::Map.call({}).if do
+      #     value.include?("A")
+      #   end
+      #
+      #   error = -> failure { raise failure.exception }
+      #
+      #   a = Remap::State.call("A")
+      #   map.call(a, &error).fetch(:value) # => "A"
+      #
+      #   b = Remap::State.call("BA")
+      #   map.call(b, &error).fetch(:value) # => "BA"
+      #
+      #   c = Remap::State.call("C")
+      #   map.call(c, &error).key?(:value) # => false
+      #
+      # @return [Map]
       def if(&block)
-        add do |state|
-          state.execute(&block).fmap do |bool, &error|
-            bool ? state.value : error["#if returned false"]
+        add do |outer_state|
+          outer_state.execute(&block).fmap do |bool, state|
+            bool ? outer_state.value : state.notice!("#if returned false")
           end
         end
       end
 
+      # Keeps map, only if block is false
+      #
+
+      # @example Keep unless value contains "A"
+      #   map = Remap::Rule::Map.call({}).if_not do
+      #     value.include?("A")
+      #   end
+      #
+      #   error = -> failure { raise failure.exception }
+      #
+      #   a = Remap::State.call("A")
+      #   map.call(a, &error).key?(:value) # => false
+      #
+      #   b = Remap::State.call("BA")
+      #   map.call(b, &error).key?(:value) # => false
+      #
+      #   c = Remap::State.call("C")
+      #   map.call(c, &error).fetch(:value) # => "C"
+      #
+      # @return [Map]
       def if_not(&block)
-        add do |state|
-          state.execute(&block).fmap do |bool, &error|
-            bool ? error["#if_not returned true"] : state.value
+        add do |outer_state|
+          outer_state.execute(&block).fmap do |bool, state|
+            bool ? state.notice!("#if_not returned false") : outer_state.value
           end
         end
       end
 
       private
 
+      # @return [self]
       def add(&block)
         tap { fn << block }
       end
 
+      # @return [Array<Proc>]
       def fn
         @fn ||= []
       end
+
+      # @return [Proc]
+      def callback
+        -> state do
+          fn.reduce(state) do |inner, fn|
+            fn[inner]
+          end
+        end
+      end
+
+      # Catches :fatal and raises {Notice::Error}
+      #
+      # @param state [State]
+      # @param id (:fatal) [:fatal, :notice, :ignore]
+      #
+      # raise [Notice::Error]
+      def fatal(state, id: :fatal, &block)
+        raise catch(id, &block).traced(backtrace).exception
+      end
+
+      # Catches :notice exceptions and repackages them as a state
+      #
+      # @param state [State]
+      #
+      # @return [State]
+      def notice(state, &block)
+        state.set(notice: catch(:notice, &block).traced(backtrace)).except(:value)
+      end
+
+      # @abstract
+      def ignore(...)
+        raise NotImplementedError, "#{self.class}#ignore"
+      end
     end
   end
 end

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