remap 2.0.3 → 2.1.0

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