emu 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: 80e58ff8f1a11f69581ad745836d6a0af99aae8e46b51615d154f3114730c250
-  data.tar.gz: 942c66c48155f9298b0069df9a35dfa5ea96f0895e2cc8403a5f4441e8778e57
+SHA1:
+  metadata.gz: 6cb8dc3aaaa590096a21438a0df18dbe3e56e3b7
+  data.tar.gz: f39031150ff096ba68ef6dc3245bf5f69d9e1bdd
 SHA512:
-  metadata.gz: aecb49f1cd38e186d347cdbe4991a091e4e8318f48d87bd553b1c8da7aae61277bedbab55fcbc78fc9da876b96af974f44e95783f202cc0a776313646f1e4e9f
-  data.tar.gz: 4146a50e2062ae91ceb7a403e5510602a4725fa4c4320fa82fa6f40c41cc268bd2eb294732f3e724efd637df9767dd02b771a92b7e8b7038054eb032065fffc1
+  metadata.gz: 39934b762ce3e4aece0de5d59bab80202310f715a69377bdca63e1dae52cc6032459e9830d8440fdae1165600d0a6ccdc8fcf7020f2beb1836c3fec384170fee
+  data.tar.gz: 9b6b79a4711062e4928fb300f11d03049ca23d7921e4e3723f8aeace80285b0ede044af81002b9e1e174a29b81c2bfad864e10cdc010744f35f4350e186cc73a

data/README.md

@@ -1,8 +1,28 @@
 # Emu
+[![Build Status](https://travis-ci.org/timhabermaas/emu.svg?branch=master)](https://travis-ci.org/timhabermaas/emu)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/emu`. To experiment with that code, run `bin/console` for an interactive prompt.
+Emu is a composable decoder and type coercion library. It can be used to
+transform Rails' `params`, the result of `JSON.parse` or any other input type
+to objects your business logic understands.
 
-TODO: Delete this and the text above, and describe your gem
+Its design is inspired by Elm's
+[`Json.Decode`](https://package.elm-lang.org/packages/elm-lang/core/5.1.1/Json-Decode)
+library in particular and [parser
+combinators](https://en.wikipedia.org/wiki/Parser_combinator) in general.
+
+## What sets it apart from the billion other coercing libraries?
+
+The three main differences are:
+
+* `Emu` is completely composable – there's no arbitrary difference between
+  decoders which return objects and decoders which return simple types. All
+  emus are equal!
+* `Emu` isn't restricted by a 1:1 relationship between input attributes and
+  output attributes – you can transform the input structure in any way
+  you desire.
+* `Emu` abstains from using a DSL. Everything can be accomplished by a
+  combination of method definitions and variable assignments. In particular
+  there's no need for `Library.register_type` calls.
 
 ## Installation
 
@@ -22,7 +42,185 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Here's an example converting a `Hash` with some wind speed and direction data into a single vector describing both
+parameters at once.
+
+```ruby
+require 'emu'
+
+direction =
+  (Emu.match('N') > [0, -1]) |
+  (Emu.match('E') > [-1, 0]) |
+  (Emu.match('S') > [0, 1]) |
+  (Emu.match('W') > [1, 0])
+
+speed = Emu.str_to_float
+
+wind = Emu.map_n(
+  Emu.from_key(:direction, direction),
+  Emu.from_key(:speed, speed)) do |(x, y), speed|
+    [x * speed, y * speed]
+end
+
+params = {
+  direction: "W",
+  speed: "4.5"
+}
+wind.run!(params) # => [4.5, 0.0]
+```
+
+This small example highlights almost all the features of `Emu`, hence there's a lot going on. So, let's break it down:
+
+_For a quick overview of the most common use cases, skip to [TODO](#foo)._
+
+All methods defined on the module `Emu` return a `Emu::Decoder`. A `Emu::Decoder` is a glorified lambda which can be run at a later time using `run!`. A decoder can either succeed or fail with a `Emu::DecodeError` exception:
+
+```ruby
+decoder = Emu.str_to_int # a decoder converting strings to integers
+decoder.run!("42") # => 42
+decoder.run!("foo") # => raise DecodeError, '`"foo"` is not an Integer'
+```
+
+The individual decoders defined on `Emu` can be split into two parts:
+
+* Basic decoders, e.g. `str_to_int` which takes a String and tries to convert it into an Integer and
+* Higher order decoders which take other decoders and wrap/manipulate them.
+
+
+### Basic decoders
+
+#### Primitive types (no type conversion)
+
+* `string`
+* `integer`
+* `float`
+* `boolean`
+* `raw`
+
+### Higher order decoders
+
+Just like "higher order functions" describe functions which take other functions as input "higher order decoders" describe decoders which take other decoders as input.
+
+* `fmap`
+* ...
+
+
+## Common Use-Cases
+
+### Decoding a Hash
+
+For decoding a Hash you use a combination of `from_key(x, d)` (to decode the value at key `x` using the decoder `d`) and `map_n` to combine
+multiple decoders into one:
+
+```ruby
+decoder = Emu.map_n(
+  Emu.from_key(:x, Emu.str_to_int),
+  Emu.from_key(:y, Emu.str_to_int)
+) do |x, y|
+  [x, y]
+end
+
+params = {
+  x: "32",
+  y: "2"
+}
+
+Emu.from_key(:x, Emu.str_to_int).run!(params) # => 32
+decoder.run!(params) # => [32, 2]
+```
+
+This gives you full control over optional keys, how to handle `nil`-values and makes it possible to map `n` keys to `y` values.
+
+### Building Custom Decoders
+
+You can build any decoder you want out of a combination of `raw`, `#then`, `succeed` and `fail`. For example the following
+describes a decoder which maps the input `"foo"` to `123` and fails for any other input.
+
+```ruby
+Emu.raw.then do |input|
+  if input == "foo"
+    Emu.succeed(123)
+  else
+    Emu.fail("bla")
+  end
+end
+```
+
+Usually you want to make use of existing decoders which handle coercing instead of building one with `raw` from scratch.
+For example the decoder which converts a String to a positive integer can be expressed as follows:
+
+```ruby
+Emu.str_to_int.then do |n|
+  if n > 0
+    Emu.succeed(n)
+  else
+    Emu.fail("#{int.inspect} must be positive")
+  end
+end
+```
+
+### Changing decoded values
+
+Converting 0-based indices to 1-based ones, uppercasing some string, converting from one (physical) unit to another, ... are all
+reasons where you want to run some function on a decoded value. That's what `fmap` provides:
+
+```ruby
+zero_based_index = Emu.str_to_int
+one_based_index = zero_based_index.fmap { |i| i + 1}
+zero_based_index.run!("12") # => 12
+one_based_index.run!("12") # => 13
+```
+
+_Note: You can't change the status of a decoder from success to failure by using only `Decoder#fmap`. You need `then` for that_
+
+### dependent decoding (bind/then)
+
+### Decoding Recursive Structures
+
+When decoding recursive structures we quickly run into the issue of endless recursion:
+
+```ruby
+{
+  name: 'Elvis Presley',
+  parent: {
+    name: 'R2D2',
+    parent: {
+      name: 'Barack Obama'
+      parent: nil
+    }
+  }
+}
+
+# person will be nil on the right-hand side => runtime error
+person =
+  Emu.map_n(
+    Emu.from_key(:name, Emu.string),
+    Emu.from_key(:parent, Emu.nil | person)) do |name, parent|
+      Person.new(name, parent)
+  end
+
+# person calls itself => infinite recursion
+def person
+  Emu.map_n(
+    Emu.from_key(:name, Emu.string),
+    Emu.from_key(:parent, Emu.nil | person)) do |name, parent|
+      Person.new(name, parent)
+  end
+end
+```
+
+This can be solved by wrapping the recursive call in `lazy`:
+
+```ruby
+person =
+  Emu.map_n(
+    Emu.from_key(:name, Emu.string),
+    Emu.from_key(:parent, Emu.nil | Emu.lazy { person })) do |name, parent|
+      Person.new(name, parent)
+  end
+```
+
+`lazy` takes a block which is only evaluated once you call `run` on the decoder. This avoids funky behavior when defining recursive decoders.
 
 ## Development
 

data/lib/emu.rb

@@ -18,6 +18,14 @@ module Emu
     end
   end
 
+  # Creates a decoder which converts a string to an integer. It uses ++Integer++
+  # for the conversion.
+  #
+  # @example
+  #   Emu.str_to_int.run!("42") # => 42
+  #   Emu.str_to_int.run!("a") # => raise DecodeError, "`\"a\"` can't be converted to an Integer"
+  #   Emu.str_to_int.run!(42) # => raise DecodeError, "`42` is not a String"
+  # @return [Emu::Decoder<Integer>]
   def self.str_to_int
     Decoder.new do |s|
       next Err.new("`#{s.inspect}` is not a String") unless s.is_a?(String)
@@ -25,11 +33,38 @@ module Emu
       begin
         Ok.new(Integer(s))
       rescue TypeError, ArgumentError
-        Err.new("`#{s.inspect}` can't be converted to an integer")
+        Err.new("`#{s.inspect}` can't be converted to an Integer")
+      end
+    end
+  end
+
+  # Creates a decoder which converts a string to a float. It uses ++Float++
+  # for the conversion.
+  #
+  # @example
+  #   Emu.str_to_float.run!("42.2") # => 42.2
+  #   Emu.str_to_float.run!("42") # => 42.0
+  #   Emu.str_to_float.run!("a") # => raise DecodeError, "`\"a\"` can't be converted to a Float"
+  #   Emu.str_to_float.run!(42) # => raise DecodeError, "`42` is not a String"
+  # @return [Emu::Decoder<Float>]
+  def self.str_to_float
+    Decoder.new do |s|
+      next Err.new("`#{s.inspect}` is not a String") unless s.is_a?(String)
+
+      begin
+        Ok.new(Float(s))
+      rescue TypeError, ArgumentError
+        Err.new("`#{s.inspect}` can't be converted to a Float")
       end
     end
   end
 
+  # Creates a decoder which only accepts integers.
+  #
+  # @example
+  #   Emu.integer.run!(2) # => 2
+  #   Emu.integer.run!("2") # => raise DecodeError, '`"2"` is not an Integer'
+  # @return [Emu::Decoder<Integer>]
   def self.integer
     Decoder.new do |i|
       next Err.new("`#{i.inspect}` is not an Integer") unless i.is_a?(Integer)
@@ -38,6 +73,30 @@ module Emu
     end
   end
 
+  # Creates a decoder which only accepts floats (including integers).
+  # Integers are converted to floats because the result type should be uniform.
+  #
+  # @example
+  #   Emu.float.run!(2) # => 2.0
+  #   Emu.float.run!(2.1) # => 2.1
+  #   Emu.float.run!("2") # => raise DecodeError, '`"2"` is not a Float'
+  # @return [Emu::Decoder<Float>]
+  def self.float
+    Decoder.new do |i|
+      next Err.new("`#{i.inspect}` is not a Float") unless i.is_a?(Float) || i.is_a?(Integer)
+
+      Ok.new(i.to_f)
+    end
+  end
+
+  # Creates a decoder which only accepts booleans.
+  #
+  # @example
+  #   Emu.boolean.run!(true) # => true
+  #   Emu.boolean.run!(false) # => false
+  #   Emu.boolean.run!(nil) # => raise DecodeError, "`nil` is not a Boolean"
+  #   Emu.boolean.run!(2) # => raise DecodeError, "`2` is not a Boolean"
+  # @return [Emu::Decoder<TrueClass|FalseClass>]
   def self.boolean
     Decoder.new do |b|
       next Err.new("`#{b.inspect}` is not a Boolean") unless b.is_a?(TrueClass) || b.is_a?(FalseClass)
@@ -46,6 +105,20 @@ module Emu
     end
   end
 
+  # Creates a decoder which converts a string to a boolean (<tt>true</tt>, <tt>false</tt>) value.
+  #
+  # <tt>"0"</tt> and <tt>"false"</tt> are considered ++false++, <tt>"1"</tt> and <tt>"true"</tt> are considered ++true++.
+  # Trying to decode any other value will fail.
+  #
+  # @example
+  #   Emu.str_to_bool.run!("true") # => true
+  #   Emu.str_to_bool.run!("1") # => true
+  #   Emu.str_to_bool.run!("false") # => false
+  #   Emu.str_to_bool.run!("0") # => false
+  #   Emu.str_to_bool.run!(true) # => raise DecodeError, "`true` is not a String"
+  #   Emu.str_to_bool.run!("2") # => raise DecodeError, "`\"2\"` can't be converted to a Boolean"
+  #
+  # @return [Emu::Decoder<TrueClass|FalseClass>]
   def self.str_to_bool
     Decoder.new do |s|
       next Err.new("`#{s.inspect}` is not a String") unless s.is_a?(String)
@@ -55,51 +128,191 @@ module Emu
       elsif s == "false" || s == "0"
         Ok.new(false)
       else
-        Err.new("`#{s.inspect}` can not be converted to a Boolean")
+        Err.new("`#{s.inspect}` can't be converted to a Boolean")
       end
     end
   end
 
-  def self.id
+  # Creates a decoder which always succeeds and yields the input.
+  #
+  # This might be useful if you don't care about the exact shape of
+  # of your data and don't have a need to inspect it (e.g. some binary
+  # data).
+  #
+  # @example
+  #   Emu.raw.run!(true) # => true
+  #   Emu.raw.run!("2") # => "2"
+  # @return [Emu::Decoder<a>]
+  def self.raw
     Decoder.new do |s|
       Ok.new(s)
     end
   end
 
-  def self.succeed(v)
+  # Creates a decoder which always succeeds with the provided value.
+  #
+  # @example
+  #   Emu.succeed("foo").run!(42) # => "foo"
+  # @param value [a] the value the decoder evaluates to
+  # @return [Emu::Decoder<a>]
+  def self.succeed(value)
     Decoder.new do |_|
-      Ok.new(v)
+      Ok.new(value)
     end
   end
 
-  def self.fail(e)
+  # Creates a decoder which always fails with the provided message.
+  #
+  # @example
+  #   Emu.fail("foo").run!(42) # => raise DecodeError, "foo"
+  # @param message [String] the error message the decoder evaluates to
+  # @return [Emu::Decoder<Void>]
+  def self.fail(message)
     Decoder.new do |_|
-      Err.new(e)
+      Err.new(message)
     end
   end
 
   # Returns a decoder which succeeds if the input value matches ++constant++.
+  # If the decoder succeeds it resolves to the input value.
   # #== is used for comparision, no type checks are performed.
   #
   # @example
   #   Emu.match(42).run!(42) # => 42
-  #   Emu.match(42).run!(41) # => raise DecodeError, "`41` doesn't match `42`"
-  # @param constant [Object] the value to match against
-  # @return [Emu::Decoder<Object>]
+  #   Emu.match(42).run!(41) # => raise DecodeError, "Input `41` doesn't match expected value `42`"
+  # @param constant [a] the value to match against
+  # @return [Emu::Decoder<a>]
   def self.match(constant)
     Decoder.new do |s|
-      s == constant ? Ok.new(s) : Err.new("`#{s.inspect}` doesn't match `#{constant.inspect}`")
+      s == constant ? Ok.new(s) : Err.new("Input `#{s.inspect}` doesn't match expected value `#{constant.inspect}`")
+    end
+  end
+
+  # Creates a decoder which only accepts `nil` values.
+  #
+  # @example
+  #   Emu.nil.run!(nil) # => nil
+  #   Emu.nil.run!(42) # => raise DecodeError, "`42` isn't `nil`"
+  # @return [Emu::Decoder<NilClass>]
+  def self.nil
+    Decoder.new do |s|
+      s.nil? ? Ok.new(s) : Err.new("`#{s.inspect}` isn't `nil`")
     end
   end
 
+  # Creates a decoder which extracts the value of a hash map according to the given key.
+  #
+  # @example
+  #   Emu.from_key(:a, Emu.str_to_int).run!({a: "42"}) # => 42
+  #   Emu.from_key(:a, Emu.str_to_int).run!({a: "a"}) # => raise DecodeError, '`"a"` can't be converted to an integer'
+  #   Emu.from_key(:a, Emu.str_to_int).run!({b: "42"}) # => raise DecodeError, '`{:b=>"42"}` doesn't contain key `:a`'
+  #
+  # @param key [a] the key of the hash map
+  # @param decoder [Emu::Decoder<b>] the decoder to apply to the value at key ++key++
+  # @return [Emu::Decoder<b>]
   def self.from_key(key, decoder)
     Decoder.new do |hash|
-      next Err.new("'#{hash}' doesn't contain key '#{key}'") unless hash.has_key?(key)
+      next Err.new("`#{hash.inspect}` is not a Hash") unless hash.respond_to?(:has_key?) && hash.respond_to?(:fetch)
+      next Err.new("`#{hash.inspect}` doesn't contain key `#{key.inspect}`") unless hash.has_key?(key)
 
       decoder.run(hash.fetch(key))
     end
   end
 
+  # Creates a decoder which extracts the value of a hash map according to the
+  # given key. If the key cannot be found ++nil++ will be returned.
+  #
+  # Note: If a key can be found, but the value decoder fails
+  # ++from_key_or_nil++ will fail as well. This is usually what you want,
+  # because this indicates bad data you don't know how to handle.
+  #
+  # @example
+  #   Emu.from_key_or_nil(:a, Emu.str_to_int).run!({a: "42"}) # => 42
+  #   Emu.from_key_or_nil(:a, Emu.str_to_int).run!({a: "a"}) # => raise DecodeError, '`"a"` can't be converted to an integer'
+  #   Emu.from_key_or_nil(:a, Emu.str_to_int).run!({b: "42"}) # => nil
+  #
+  # @param key [a] the key of the hash map
+  # @param decoder [Emu::Decoder<b>] the decoder to apply to the value at key ++key++
+  # @return [Emu::Decoder<b, NilClass>]
+  def self.from_key_or_nil(key, decoder)
+    Decoder.new do |hash|
+      next Err.new("`#{hash.inspect}` is not a Hash") unless hash.respond_to?(:has_key?) && hash.respond_to?(:fetch)
+      if hash.has_key?(key)
+        decoder.run(hash.fetch(key))
+      else
+        Ok.new(nil)
+      end
+    end
+  end
+
+  # Creates a decoder which extracts the value of an array at the given index.
+  #
+  # @example
+  #   Emu.at_index(0, Emu.str_to_int).run!(["42"]) # => 42
+  #   Emu.at_index(0, Emu.str_to_int).run!(["a"]) # => raise DecodeError, '`"a"` can't be converted to an integer'
+  #   Emu.at_index(1, Emu.str_to_int).run!(["42"]) # => raise DecodeError, '`["42"]` doesn't contain index `1`'
+  #
+  # @param index [Integer] the key of the hash map
+  # @param decoder [Emu::Decoder<b>] the decoder to apply to the value at index ++index++
+  # @return [Emu::Decoder<b>]
+  def self.at_index(index, decoder)
+    Decoder.new do |array|
+      next Err.new("`#{array.inspect}` doesn't contain index `#{index.inspect}`") if index >= array.length
+
+      decoder.run(array[index])
+    end
+  end
+
+  # Creates a decoder which decodes the values of an array and returns the decoded array.
+  #
+  # @example
+  #   Emu.array(Emu.str_to_int).run!(["42", "43"]) # => [42, 43]
+  #   Emu.array(Emu.str_to_int).run!("42") # => raise DecodeError, "`"a"` is not an Array"
+  #   Emu.array(Emu.str_to_int).run!(["a"]) # => raise DecodeError, '`"a"` can't be converted to an Integer'
+  #
+  # @param decoder [Emu::Decoder<b>] the decoder to apply to all values of the array
+  # @return [Emu::Decoder<b>]
+  def self.array(decoder)
+    Decoder.new do |array|
+      next Err.new("`#{array.inspect}` is not an Array") unless array.is_a?(Array)
+
+      result = []
+
+      i = 0
+      error_found = nil
+      while i < array.length && !error_found
+        r = decoder.run(array[i])
+        if r.error?
+          error_found = r
+        else
+          result << r.unwrap
+        end
+        i += 1
+      end
+
+      if error_found
+        error_found
+      else
+        Ok.new(result)
+      end
+    end
+  end
+
+  # Builds a decoder out of ++n++ decoders and maps a function over the result
+  # of the passed in decoders. For the block to be called all decoders must succeed.
+  #
+  # @example
+  #   d = Emu.map_n(Emu.string, Emu.str_to_int) do |string, integer|
+  #     string * integer
+  #   end
+  #
+  #   d.run!("3") # => "333"
+  #   d.run!("a") # => raise DecodeError, '`"a"` can't be converted to an Integer'
+  #
+  # @param decoders [Array<Decoder>] the decoders to map over
+  # @yield [a, b, c, ...] Passes the result of all decoders to the block
+  # @yieldreturn [z] the value the decoder should evaluate to
+  # @return [Emu::Decoder<z>]
   def self.map_n(*decoders, &block)
     raise "decoder count must match argument count of provided block" unless decoders.size == block.arity
 
@@ -116,4 +329,27 @@ module Emu
       end
     end
   end
+
+  # Wraps a decoder +d+ in a lazily evaluated block to avoid endless recursion when
+  # dealing with recursive data structures. <tt>Emu.lazy { d }.run!</tt> behaves exactly like
+  # +d.run!+.
+  #
+  # @example
+  #   person =
+  #     Emu.map_n(
+  #       Emu.from_key(:name, Emu.string),
+  #       Emu.from_key(:parent, Emu.nil | Emu.lazy { person })) do |name, parent|
+  #         Person.new(name, parent)
+  #     end
+  #
+  #   person.run!({name: "foo", parent: { name: "bar", parent: nil }}) # => Person("foo", Person("bar", nil))
+  #
+  # @yieldreturn [Emu::Decoder<a>] the wrapped decoder
+  # @return [Emu::Decoder<a>]
+  def self.lazy
+    Decoder.new do |input|
+      inner_decoder = yield
+      inner_decoder.run(input)
+    end
+  end
 end

data/lib/emu/version.rb

@@ -1,3 +1,3 @@
 module Emu
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: emu
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Tim Habermaas
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-12-23 00:00:00.000000000 Z
+date: 2019-03-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -62,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 3.0.0.beta1
+rubygems_version: 2.5.2.3
 signing_key: 
 specification_version: 4
 summary: Composable decoding library in the spirit of Json.Decode from Elm