remap 2.0.2 → 2.1.5

data/lib/remap/compiler.rb

@@ -1,17 +1,30 @@
 # frozen_string_literal: true
 
 module Remap
-  class Compiler
-    include Dry::Core::Constants
-    extend Dry::Initializer
-    extend Forwardable
-
-    param :rules, default: -> { EMPTY_ARRAY.dup }
+  # Constructs a {Rule} from the block passed to {Remap::Base.define}
+  class Compiler < Proxy
+    # @return [Array<Rule>]
+    param :rules, type: Types.Array(Rule)
 
     # @return [Rule]
-    delegate call: self
+    delegate :call, to: Compiler
 
-    # Constructs a rule tree given {block}
+    # Constructs a rule tree given block
+    #
+    # @example Compiles two rules, [get] and [map]
+    #   rule = Remap::Compiler.call do
+    #     get :name
+    #     get :age
+    #   end
+    #
+    #   state = Remap::State.call({
+    #     name: "John",
+    #     age: 50
+    #   })
+    #
+    #   error = -> failure { raise failure.exception }
+    #
+    #   rule.call(state, &error).fetch(:value) # => { name: "John", age: 50 }
     #
     # @return [Rule]
     def self.call(&block)
@@ -19,83 +32,324 @@ module Remap
         return Rule::Void.new
       end
 
-      new.tap { _1.instance_eval(&block) }.rule
+      new([]).tap do |compiler|
+        compiler.instance_exec(&block)
+      end.rule
     end
 
-    # Maps {path} to {to} with {block} inbetween
+    # Maps input path [input] to output path [to]
     #
     # @param path ([]) [Array<Segment>, Segment]
     # @param to ([]) [Array<Symbol>, Symbol]
     #
-    # @return [Rule::Map]
-    def map(*path, to: EMPTY_ARRAY, &block)
-      add Rule::Map.new(
+    # @example From path [:name] to [:nickname]
+    #   rule = Remap::Compiler.call do
+    #     map :name, to: :nickname
+    #   end
+    #
+    #   state = Remap::State.call({
+    #     name: "John"
+    #   })
+    #
+    #   output = rule.call(state) do |failure|
+    #     raise failure.exception
+    #   end
+    #
+    #   output.fetch(:value) # => { nickname: "John" }
+    #
+    # @return [Rule::Map::Required]
+    def map(*path, to: EMPTY_ARRAY, backtrace: Kernel.caller, &block)
+      add Rule::Map::Required.call(
+        path: {
+          output: [to].flatten,
+          input: path.flatten
+        },
+        backtrace: backtrace,
+        rule: call(&block))
+    end
+
+    # Optional version of {#map}
+    #
+    # @example Map an optional field
+    #   rule = Remap::Compiler.call do
+    #     to :person do
+    #       map? :age, to: :age
+    #       map :name, to: :name
+    #     end
+    #   end
+    #
+    #   state = Remap::State.call({
+    #     name: "John"
+    #   })
+    #
+    #   output = rule.call(state) do |failure|
+    #     raise failure.exception
+    #   end
+    #
+    #   output.fetch(:value) # => { person: { name: "John" } }
+    #
+    # @see #map
+    #
+    # @return [Rule::Map::Optional]
+    def map?(*path, to: EMPTY_ARRAY, backtrace: Kernel.caller, &block)
+      add Rule::Map::Optional.call(
         path: {
-          map: path.flatten,
-          to: [to].flatten
+          output: [to].flatten,
+          input: path.flatten
         },
-        rule: call(&block)
-      )
+        backtrace: backtrace,
+        rule: call(&block))
     end
 
-    # Maps using {mapper}
+    # Select a path and uses the same path as output
+    #
+    # @param path ([]) [Array<Segment>, Segment]
+    #
+    # @example Map from [:name] to [:name]
+    #   rule = Remap::Compiler.call do
+    #     get :name
+    #   end
+    #
+    #   state = Remap::State.call({
+    #     name: "John"
+    #   })
+    #
+    #   output = rule.call(state) do |failure|
+    #     raise failure.exception
+    #   end
+    #
+    #   output.fetch(:value) # => { name: "John" }
+    #
+    # @return [Rule::Map::Required]
+    def get(*path, backtrace: Kernel.caller, &block)
+      map(path, to: path, backtrace: backtrace, &block)
+    end
+
+    # Optional version of {#get}
+    #
+    # @example Map from [:name] to [:name]
+    #   rule = Remap::Compiler.call do
+    #     get :name
+    #     get? :age
+    #   end
+    #
+    #   state = Remap::State.call({
+    #     name: "John"
+    #   })
+    #
+    #   output = rule.call(state) do |failure|
+    #     raise failure.exception
+    #   end
+    #
+    #   output.fetch(:value) # => { name: "John" }
+    #
+    # @see #get
+    #
+    # @return [Rule::Map::Optional]
+    def get?(*path, backtrace: Kernel.caller, &block)
+      map?(path, to: path, backtrace: backtrace, &block)
+    end
+
+    # Maps using mapper
     #
     # @param mapper [Remap]
     #
+    # @example Embed mapper Car into a person
+    #   class Car < Remap::Base
+    #     define do
+    #       map :car do
+    #         map :name, to: :car
+    #       end
+    #     end
+    #   end
+    #
+    #   rule = Remap::Compiler.call do
+    #     map :person do
+    #       embed Car
+    #     end
+    #   end
+    #
+    #   state = Remap::State.call({
+    #     person: {
+    #       car: {
+    #         name: "Volvo"
+    #       }
+    #     }
+    #   })
+    #
+    #   output = rule.call(state) do |failure|
+    #     raise failure.exception
+    #   end
+    #
+    #   output.fetch(:value) # => { car: "Volvo" }
+    #
     # @return [Rule::Embed]
-    def embed(mapper)
+    def embed(mapper, &block)
+      if block
+        raise ArgumentError, "#embed does not take a block"
+      end
+
       add Rule::Embed.new(mapper: mapper)
     rescue Dry::Struct::Error
       raise ArgumentError, "Embeded mapper must be [Remap::Mapper], got [#{mapper}]"
     end
 
-    # @param *path ([]) [Symbol, Array<Symbol>]
+    # Set a static value
+    #
+    # @param path ([]) [Symbol, Array<Symbol>]
     # @option to [Remap::Static]
     #
+    # @example Set static value to { name: "John" }
+    #   rule = Remap::Compiler.call do
+    #     set :name, to: value("John")
+    #   end
+    #
+    #   state = Remap::State.call({})
+    #
+    #   output = rule.call(state) do |failure|
+    #     raise failure.exception
+    #   end
+    #
+    #   output.fetch(:value) # => { name: "John" }
+    #
+    # @example Reference an option
+    #   rule = Remap::Compiler.call do
+    #     set :name, to: option(:name)
+    #   end
+    #
+    #   state = Remap::State.call({}, options: { name: "John" })
+    #
+    #   output = rule.call(state) do |failure|
+    #     raise failure.exception
+    #   end
+    #
+    #   output.fetch(:value) # => { name: "John" }
+    #
     # @return [Rule::Set]
     # @raise [ArgumentError]
     #   if no path given
     #   if path is not a Symbol or Array<Symbol>
-    def set(*path, to:)
-      add Rule::Set.new(path: { to: path.flatten, map: EMPTY_ARRAY }, value: to)
+    def set(*path, to:, &block)
+      if block
+        raise ArgumentError, "#set does not take a block"
+      end
+
+      add Rule::Set.new(path: path.flatten, value: to)
     rescue Dry::Struct::Error => e
       raise ArgumentError, e.message
     end
 
-    # Maps to {path} from {map} with {block} inbetween
+    # Maps to path from map with block in between
     #
     # @param path [Array<Symbol>, Symbol]
     # @param map [Array<Segment>, Segment]
     #
+    # @example From path [:name] to [:nickname]
+    #   rule = Remap::Compiler.call do
+    #     to :nickname, map: :name
+    #   end
+    #
+    #   state = Remap::State.call({
+    #     name: "John"
+    #   })
+    #
+    #   output = rule.call(state) do |failure|
+    #     raise failure.exception
+    #   end
+    #
+    #   output.fetch(:value) # => { nickname: "John" }
+    #
     # @return [Rule::Map]
-    def to(*path, map: EMPTY_ARRAY, &block)
-      map(*map, to: path, &block)
+    def to(*path, map: EMPTY_ARRAY, backtrace: Kernel.caller, &block)
+      map(*map, to: path, backtrace: backtrace, &block)
+    end
+
+    # Optional version of {#to}
+    #
+    # @example Map an optional field
+    #   rule = Remap::Compiler.call do
+    #     to :person do
+    #       to? :age, map: :age
+    #       to :name, map: :name
+    #     end
+    #   end
+    #
+    #   state = Remap::State.call({
+    #     name: "John"
+    #   })
+    #
+    #   output = rule.call(state) do |failure|
+    #     raise failure.exception
+    #   end
+    #
+    #   output.fetch(:value) # => { person: { name: "John" } }
+    # @see #to
+    #
+    # @return [Rule::Map::Optional]
+    def to?(*path, map: EMPTY_ARRAY, &block)
+      map?(*map, to: path, &block)
     end
 
     # Iterates over the input value, passes each value
     # to its block and merges the result back together
     #
+    # @example Map an array of hashes
+    #   rule = Remap::Compiler.call do
+    #     each do
+    #       map :name
+    #     end
+    #   end
+    #
+    #   state = Remap::State.call([{
+    #     name: "John"
+    #   }, {
+    #     name: "Jane"
+    #   }])
+    #
+    #   output = rule.call(state) do |failure|
+    #     raise failure.exception
+    #   end
+    #
+    #   output.fetch(:value) # => ["John", "Jane"]
+    #
     # @return [Rule::Each]]
     # @raise [ArgumentError] if no block given
     def each(&block)
       unless block
-        raise ArgumentError, "no block given"
+        raise ArgumentError, "#each requires a block"
       end
 
       add Rule::Each.new(rule: call(&block))
     end
 
-    # Wraps output in {type}
+    # Wraps output in type
     #
     # @param type [:array]
     #
     # @yieldreturn [Rule]
     #
+    # @example Wrap an output value in an array
+    #   rule = Remap::Compiler.call do
+    #     wrap(:array) do
+    #       map :name
+    #     end
+    #   end
+    #
+    #   state = Remap::State.call({
+    #     name: "John"
+    #   })
+    #
+    #   output = rule.call(state) do |failure|
+    #     raise failure.exception
+    #   end
+    #
+    #   output.fetch(:value) # => ["John"]
+    #
     # @return [Rule::Wrap]
     # @raise [ArgumentError] if type is not :array
     def wrap(type, &block)
       unless block
-        raise ArgumentError, "no block given"
+        raise ArgumentError, "#wrap requires a block"
       end
 
       add Rule::Wrap.new(type: type, rule: call(&block))
@@ -105,8 +359,28 @@ module Remap
 
     # Selects all elements
     #
+    # @example Select all keys in array
+    #   rule = Remap::Compiler.call do
+    #     map all, :name, to: :names
+    #   end
+    #
+    #   state = Remap::State.call([
+    #     { name: "John" },
+    #     { name: "Jane" }
+    #   ])
+    #
+    #   output = rule.call(state) do |failure|
+    #     raise failure.exception
+    #   end
+    #
+    #   output.fetch(:value) # => { names: ["John", "Jane"] }
+    #
     # @return [Rule::Path::Segment::Quantifier::All]
-    def all
+    def all(&block)
+      if block
+        raise ArgumentError, "all selector does not take a block"
+      end
+
       Selector::All.new(EMPTY_HASH)
     end
 
@@ -114,44 +388,136 @@ module Remap
     #
     # @param value [Any]
     #
+    # @example Set path to static value
+    #   rule = Remap::Compiler.call do
+    #     set :api_key, to: value("<SECRET>")
+    #   end
+    #
+    #   state = Remap::State.call({})
+    #
+    #   output = rule.call(state) do |failure|
+    #     raise failure.exception
+    #   end
+    #
+    #   output.fetch(:value) # => { api_key: "<SECRET>" }
+    #
     # @return [Rule::Static::Fixed]
-    def value(value)
+    def value(value, &block)
+      if block
+        raise ArgumentError, "option selector does not take a block"
+      end
+
       Static::Fixed.new(value: value)
     end
 
     # Static option to be selected
     #
+    # @example Set path to option
+    #   rule = Remap::Compiler.call do
+    #     set :meaning_of_life, to: option(:number)
+    #   end
+    #
+    #   state = Remap::State.call({}, options: { number: 42 })
+    #
+    #   output = rule.call(state) do |failure|
+    #     raise failure.exception
+    #   end
+    #
+    #   output.fetch(:value) # => { meaning_of_life: 42 }
+    #
     # @param id [Symbol]
     #
     # @return [Rule::Static::Option]
-    def option(id)
-      Static::Option.new(name: id)
+    def option(id, backtrace: Kernel.caller, &block)
+      if block
+        raise ArgumentError, "option selector does not take a block"
+      end
+
+      Static::Option.new(name: id, backtrace: backtrace)
     end
 
-    # Selects {index} element in input
+    # Selects index element in input
     #
     # @param index [Integer]
     #
+    # @example Select value at index
+    #   rule = Remap::Compiler.call do
+    #     map :names, at(1), to: :name
+    #   end
+    #
+    #   state = Remap::State.call({
+    #     names: ["John", "Jane"]
+    #   })
+    #
+    #   output = rule.call(state) do |failure|
+    #     raise failure.exception
+    #   end
+    #
+    #   output.fetch(:value) # => { name: "Jane" }
+    #
     # @return [Path::Segment::Key]
     # @raise [ArgumentError] if index is not an Integer
-    def at(index)
+    def at(index, &block)
+      if block
+        raise ArgumentError, "first selector does not take a block"
+      end
+
       Selector::Index.new(index: index)
     rescue Dry::Struct::Error
-      raise ArgumentError, "Selector at(index) requires an integer argument, got [#{index}] (#{index.class})"
+      raise ArgumentError,
+            "Selector at(index) requires an integer argument, got [#{index}] (#{index.class})"
     end
 
     # Selects first element in input
     #
+    # @example Select first value in an array
+    #   rule = Remap::Compiler.call do
+    #     map :names, first, to: :name
+    #   end
+    #
+    #   state = Remap::State.call({
+    #     names: ["John", "Jane"]
+    #   })
+    #
+    #   output = rule.call(state) do |failure|
+    #     raise failure.exception
+    #   end
+    #
+    #   output.fetch(:value) # => { name: "John" }
+    #
     # @return [Path::Segment::Key]]
-    def first
+    def first(&block)
+      if block
+        raise ArgumentError, "first selector does not take a block"
+      end
+
       at(0)
     end
     alias any first
 
     # Selects last element in input
     #
+    # @example Select last value in an array
+    #   rule = Remap::Compiler.call do
+    #     map :names, last, to: :name
+    #   end
+    #
+    #   state = Remap::State.call({
+    #     names: ["John", "Jane", "Linus"]
+    #   })
+    #
+    #   output = rule.call(state) do |failure|
+    #     raise failure.exception
+    #   end
+    #
+    #   output.fetch(:value) # => { name: "Linus" }
+    #
     # @return [Path::Segment::Key]
-    def last
+    def last(&block)
+      if block
+        raise ArgumentError, "last selector does not take a block"
+      end
+
       at(-1)
     end
 

data/lib/remap/constructor/argument.rb

@@ -2,16 +2,27 @@
 
 module Remap
   class Constructor
-    class Argument < Concrete
-      using State::Extension
+    using State::Extension
 
+    # Allows a class (target) to be called with a regular argument
+    class Argument < Concrete
+      # @return [:argument]
       attribute :strategy, Value(:argument), default: :argument
 
-      # Uses the {#method} method to initialize {#target} with {state}
-      # Target is only called if {state} is defined
+      # Uses the {#method} method to initialize {#target} with state
+      # Target is only called if state is defined
+      #
+      # Used by {Remap::Base} to define constructors for mapped data
       #
       # Fails if {#target} does not respond to {#method}
-      # Fails if {#target} cannot be called with {state}
+      # Fails if {#target} cannot be called with state
+      #
+      # @example Initialize a target with a state
+      #   target = ::Struct.new(:foo)
+      #   constructor = Remap::Constructor.call(strategy: :argument, target: target, method: :new)
+      #   state = Remap::State.call(:bar)
+      #   new_state = constructor.call(state)
+      #   new_state.fetch(:value).foo # => :bar
       #
       # @param state [State]
       #
@@ -20,7 +31,10 @@ module Remap
         super.fmap do |input|
           target.public_send(id, input)
         rescue ArgumentError => e
-          raise e.exception("Could not load target [#{target}] using the argument strategy with [#{input}] (#{input.class})")
+          raise e.exception("Failed to create [%p] with input [%s] (%s)" % [
+            target, input,
+            input.class
+          ])
         end
       end
     end

data/lib/remap/constructor/keyword.rb

@@ -2,15 +2,26 @@
 
 module Remap
   class Constructor
-    class Keyword < Concrete
-      using State::Extension
+    using State::Extension
 
+    # Allows a class (target) to be called with keyword arguments
+    class Keyword < Concrete
+      # @return [:keyword]
       attribute :strategy, Value(:keyword)
 
       # Calls {#target} as with keyword arguments
       #
       # Fails if {#target} does not respond to {#method}
-      # Fails if {#target} cannot be called with {state}
+      # Fails if {#target} cannot be called with state
+      #
+      # Used by {Remap::Base} to define constructors for mapped data
+      #
+      # @example Initialize a target with a state
+      #   target = OpenStruct
+      #   constructor = Remap::Constructor.call(strategy: :keyword, target: target, method: :new)
+      #   state = Remap::State.call({ foo: :bar })
+      #   new_state = constructor.call(state)
+      #   new_state.fetch(:value).foo # => :bar
       #
       # @param state [State]
       #
@@ -23,7 +34,12 @@ module Remap
 
           target.public_send(id, **input)
         rescue ArgumentError => e
-          raise e.exception("Could not load target [#{target}] using the keyword strategy using [#{input}] (#{input.class})")
+          raise e.exception("Failed to create [%p] with input [%s] (%s}) using method %s" % [
+            target,
+            input,
+            input.class,
+            id
+          ])
         end
       end
     end

data/lib/remap/constructor/none.rb

@@ -2,15 +2,14 @@
 
 module Remap
   class Constructor
+    # Default type used by {Remap::Base}
     class None < Concrete
       attribute :target, Types::Nothing
       attribute :strategy, Types::Any
       attribute :method, Types::Any
 
-      # Just returns the input state
-      #
-      # Fails if {#target} does not respond to {#method}
-      # Fails if {#target} cannot be called with {state}
+      # Used by {Remap::Base} as a default constructor
+      # Using it does nothing but return its input state
       #
       # @param state [State]
       #

data/lib/remap/constructor.rb

@@ -2,8 +2,11 @@
 
 module Remap
   class Constructor < Dry::Interface
+    # @return [Any]
+    attribute :target, Types::Any, not_eql: Nothing
+
+    # @return [Symbol]
     attribute :method, Symbol, default: :new
-    attribute :target, Types::Any.constrained(not_eql: Nothing)
 
     # Ensures {#target} responds to {#method}
     # Returns an error state unless above is true
@@ -19,12 +22,16 @@ module Remap
       end
     end
 
-    def id
-      attributes.fetch(:method)
-    end
-
+    # @return [Proc]
     def to_proc
       method(:call).to_proc
     end
+
+    private
+
+    # @return [Symbol]
+    def id
+      attributes.fetch(:method)
+    end
   end
 end