remap 2.1.0 → 2.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3b3344d7c0ab3825ba1bb0a80c5ddbd7a00d57dbf762b0e26cd3cc6216e0644
-  data.tar.gz: 30db4e775e16a7923c46d4f1ca41b0b207ab0bb21cf791179a8fd76cbad9d455
+  metadata.gz: 6b79008354032e3417442fc906736d8837942692da12022111ded8bdf43ed254
+  data.tar.gz: 4c8cc74b50b7549fb79749c378f6cc4507fc3628d83519a791ce2c9ede7686fc
 SHA512:
-  metadata.gz: e590c6d048e6cbb822c6bc49428f05e0dd6ead0f0f8752d563b5660adf422e61f1f8e2dc899490fedbdeb34bb36e3dc047906b7fe7eacf9a2711021c6f4a1d5f
-  data.tar.gz: 58ebb654582cbcfbfc776fb90a8ff2ce88a840642f1c1669c755478cb582f254f7f41a844762f7a228ed8a812e320aab073836dba190a15a3f0a42406a8740a0
+  metadata.gz: c710ac63224b18a156d0576e1116622e04ebd4ca51992c7736fbe38390c40737da90df958e75ff8b42ec2bacfaaac4827a86f68b6049cdf027ba4beabb8cb52c
+  data.tar.gz: 18270d4afa3d650343b535ac915580557e326ed42bbc9b7aa4be00e414935c38f0da4fd5e2e8da55136dd900ac4245f8aa9e98c9f79162908fb7f1ff6d35beca

data/lib/remap/compiler.rb

@@ -11,7 +11,7 @@ module Remap
 
     # Constructs a rule tree given block
     #
-    # @example Compiles two rules
+    # @example Compiles two rules, [get] and [map]
     #   rule = Remap::Compiler.call do
     #     get :name
     #     get :age
@@ -42,6 +42,21 @@ module Remap
     # @param path ([]) [Array<Segment>, Segment]
     # @param to ([]) [Array<Symbol>, Symbol]
     #
+    # @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(
@@ -55,6 +70,24 @@ module Remap
 
     # 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]
@@ -72,6 +105,21 @@ module Remap
     #
     # @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)
@@ -79,6 +127,22 @@ module Remap
 
     # 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]
@@ -90,6 +154,35 @@ module Remap
     #
     # @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, &block)
       if block
@@ -101,9 +194,37 @@ module Remap
       raise ArgumentError, "Embeded mapper must be [Remap::Mapper], got [#{mapper}]"
     end
 
+    # 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
@@ -123,6 +244,21 @@ module Remap
     # @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, backtrace: Kernel.caller, &block)
       map(*map, to: path, backtrace: backtrace, &block)
@@ -130,6 +266,23 @@ module Remap
 
     # 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]
@@ -140,6 +293,25 @@ module Remap
     # 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)
@@ -156,6 +328,23 @@ module Remap
     #
     # @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)
@@ -170,6 +359,22 @@ 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(&block)
       if block
@@ -183,6 +388,19 @@ 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, &block)
       if block
@@ -194,6 +412,19 @@ module Remap
 
     # 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]
@@ -209,6 +440,21 @@ module Remap
     #
     # @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, &block)
@@ -224,6 +470,21 @@ module Remap
 
     # 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(&block)
       if block
@@ -236,6 +497,21 @@ module Remap
 
     # 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(&block)
       if block

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: remap
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.1.4
 platform: ruby
 authors:
 - Linus Oleander