deterministic 0.8.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7e4df729f9e00305be8b4bfa828c627dd581ad07
-  data.tar.gz: 0e1c862ea8004b24bbe65d1d86aa93946013fdad
+  metadata.gz: d6ccf85126958f17b98ac22932b29ed508584250
+  data.tar.gz: 689d36f2f3b71bcc6192129514a8ca14b2b32001
 SHA512:
-  metadata.gz: bef331eed029917b69da1e1059b75f2d43a63ce00bac59f16e589e78de61349e57624f57bc84dac8b7011045043fae28f2fa74831b7d13fea07e2f9f90b805b9
-  data.tar.gz: adb613df744063e6ac84bee504c2c050d70ace2add63a8b93978efbc128f84e78fee9e205c983f90de7025d7511591e802f3286a3573c314644673b640ad09b7
+  metadata.gz: c3c067aab6e1418a829a72505ad33f5822d3f7c749ece67aa903c306e7910ab2158cf5005f439d3dceffe032394f321109fc618c892b4324e85a2a469c8de6eb
+  data.tar.gz: 9500d35aedd9849fd2893534b6a220256ac71696b973e86978b4d714233a17a31acd017efdd55cd0dee18afdd25522ab05a0f357e2023819784067fecce687b4

data/HISTORY.md

@@ -0,0 +1,17 @@
+## v0.10.0
+** breaking changes **
+
+- Remove `Either#<<`
+- Rename `Either` to `Result`
+- Add `Result#pipe` aka `Result#**`
+- Add `Result#map` and `Result#map_err`
+
+## v0.9.0
+** breaking changes **
+
+- Remove `Either.attempt_all` in favor of `Either#>>` and `Either#>=`
+  This greatly reduces the complexity and the code necessary.
+
+## 0.8.0 - v0.8.1
+
+- Introduce `Either#>>` and `Either#>=`

data/README.md

@@ -9,79 +9,153 @@ This is a spiritual successor of the [Monadic gem](http://github.com/pzol/monadi
 
 ## Usage
 
-### Success & Failure
+### Result: Success & Failure
 
 ```ruby
-Success(1).to_s             # => "1"
-Success(1) << Success(2)    # => Success(2)
-Success(Success(1))         # => Success(1)
-Success(1).map { |v| v + 1} # => Success(2)
-Success({a:1}).to_json      # => '{"Success": {"a":1}}'
-
-Failure(1).to_s             # => "1"
-Failure(1) << Failure(2)    # => Failure(1)
-Failure(Failure(1))         # => Failure(1)
-Failure(1).map { |v| v + 1} # => Failure(2)
-Failure({a:1}).to_json      # => '{"Failure": {"a":1}}'
+Success(1).to_s                        # => "1"
+Success(Success(1))                    # => Success(1)
+
+Failure(1).to_s                        # => "1"
+Failure(Failure(1))                    # => Failure(1)
 ```
 
-Chaining successful actions
+#### `fmap :: R a -> (a -> b) -> R b`
+
+Maps a `Result` with the value `a` to the same `Result` with the value `b`.
 
 ```ruby
-Success(1).and Success(2)            # => Success(2)
-Success(1).and_then { Success(2) }   # => Success(2)
+Success(1).fmap { |v| v + 1}           # => Success(2)
+Failure(1).fmap { |v| v - 1}           # => Failure(0)
+```
 
-Success(1).or Success(2)             # => Success(1)
-Success(1).or_else { Success(2) }    # => Success(1)
+#### `bind :: R a -> (a -> R b) -> R b`
+
+Maps a `Result` with the value `a` to another `Result` with the value `b`.
+
+```ruby
+Success(1).bind { |v| Failure(v + 1) } # => Failure(2)
+Failure(1).fmap { |v| Success(v - 1) } # => Success(0)
+```
+
+#### `map :: S a -> (a -> R b) -> R b`
+
+Maps a `Success` with the value `a` to another `Result` with the value `b`. It works like `#bind` but only on `Success`.
+
+```ruby
+Success(1).map { |n| n + 1 }           # => Success(2)
+Failure(0).map { |n| n + 1 }           # => Failure(0)
+```
+
+#### `map_err :: F a -> (a -> R b) -> R b`
+
+Maps a `Failure` with the value `a` to another `Result` with the value `b`. It works like `#bind` but only on `Failure`.
+
+```ruby
+Failure(1).map_err { |n| n + 1 } # => Success(2)
+Success(0).map_err { |n| n + 1 } # => Success(0)
 ```
 
-Chaining failed actions
+#### `try :: S a -> ( a -> R b) -> R b`
+
+Just like `#map`, transforms `a` to another `Result`, but it will also catch raised exceptions and wrap them with a `Failure`.
+
+```ruby
+Success(0).try { |n| raise "Error" }   # => Failure(Error)
+```
+
+#### `and :: S a -> R b -> R b`
+
+Replaces `Success a` with `Result b`. If a `Failure` is passed as argument, it is ignored.
 
 ```ruby
+Success(1).and Success(2)            # => Success(2)
 Failure(1).and Success(2)            # => Failure(1)
+```
+
+#### `and_then :: S a -> (a -> R b) -> R b`
+
+Replaces `Success a` with the result of the block. If a `Failure` is passed as argument, it is ignored.
+
+```ruby
+Success(1).and_then { Success(2) }   # => Success(2)
 Failure(1).and_then { Success(2) }   # => Failure(1)
+```
+
+#### `or :: F a -> R b -> R b` 
+Replaces `Failure a` with `Result`. If a `Failure` is passed as argument, it is ignored.
 
+```ruby
+Success(1).or Success(2)             # => Success(1)
 Failure(1).or Success(1)             # => Success(1)
-Failure(1).or_else { |v| Success(v)} # => Success(1)
 ```
 
-The value or block result must always be a `Success` or `Failure`
+#### `or_else :: F a -> (a -> R b) -> R b`
+
+Replaces `Failure a` with the result of the block. If a `Success` is passed as argument, it is ignored.
+
+```ruby
+Success(1).or_else { Success(2) }    # => Success(1)
+Failure(1).or_else { |n| Success(n)} # => Success(1)
+```
+
+#### `pipe :: R a -> (R a -> b) -> R a`
+
+Executes the block passed, but completely ignores its result. If an error is raised within the block it will **NOT** be catched.
+
+```ruby
+Success(1).try { |n| log(n.value) }  # => Success(1)
+```
+
+The value or block result must always be a `Result` i.e. `Success` or `Failure`.
+
+### Result Chaining
 
-### Either.chain
 You can easily chain the execution of several operations. Here we got some nice function composition.  
 The method must be a unary function, i.e. it always takes one parameter - the context, which is passed from call to call.
 
+The following aliases are defined
+
+```ruby
+alias :>> :map
+alias :>= :try
+alias :** :pipe       # the operator must be right associative
+```
+
+This allows the composition of procs or lambdas and thus allow a clear definiton of a pipeline.
+
+```ruby
+Success(params) >> validate >> build_request ** log >> send ** log >> build_response
+```
+
+#### Complex Example in a Builder Class
+
 ```ruby
 class Foo
   include Deterministic
-  alias :m :method
+  alias :m :method # method conveniently returns a Proc to a method
 
-  def call
-    setup >> m(:validate) >> m(:send)
+  def call(params)
+    Success(params) >> m(:validate) >> m(:send)
   end
 
-  def setup
-    Success(1)
-  end
-
-  def validate(ctx)
+  def validate(params)
     # do stuff
-    Success(ctx + 1)
+    Success(validate_and_cleansed_params)
   end
 
-  def send(ctx)
+  def send(clean_params)
     # do stuff
-    Success(ctx + 1)
+    Success(result)
   end
 end
 
 Foo.new.call # Success(3)
 ```
 
-Chaining works with blocks (`#chain` is an alias for `#>>`)
+Chaining works with blocks (`#map` is an alias for `#>>`)
 
 ```ruby
-Success(1).chain {|ctx| Success(ctx + 1)}
+Success(1).map {|ctx| Success(ctx + 1)}
 ```
 
 it also works with lambdas
@@ -107,75 +181,21 @@ end
 Success(0) >> method(:works) >> method(:breaks) >> method(:never_executed) # Failure(2)
 ```
 
-`#chain` aka `#>>` will not catch any exceptions raised. If you want automatic exception handling, the `#try` aka `#>=` will catch an error and wrap it with a failure
+`#map` aka `#>>` will not catch any exceptions raised. If you want automatic exception handling, the `#try` aka `#>=` will catch an error and wrap it with a failure
 
 ```ruby
 def error(ctx)
-  raise "error #{1}"
+  raise "error #{ctx}"
 end
 
 Success(1) >= method(:error) # Failure(RuntimeError(error 1))
 ```
 
-### Either.attempt_all
-The basic idea is to execute a chain of units of work and make sure all return either `Success` or `Failure`.
-This remains for compatibility reasons, personally I would use the `>>` chaining.
-
-
-```ruby
-Either.attempt_all do
-  try { 1 }
-  try { |prev| prev + 1 }
-end # => Success(2)
-```
-Take notice, that the result of of unit of work will be passed to the next one. So the result of prepare_somehing will be something in the second try.
-
-If any of the units of work in between fail, the rest will not be executed and the last `Failure` will be returned.
-
-```ruby
-Either.attempt_all do
-  try { 1 }
-  try { raise "error" }
-  try { 2 }
-end # => Failure(RuntimeError("error"))
-```
-
-However, the real fun starts if you use it with your own context. You can use this as a state container (meh!) or to pass a dependency locator:
-
-```ruby
-  class Context
-    attr_accessor :env, :settings
-    def some_service
-    end
-  end
-
-  # exemplary unit of work
-  module LoadSettings
-    def self.call(env)
-      settings = load(env)
-      settings.nil? ? Failure('could not load settings') : Success(settings)
-    end
-
-    def load(env)
-    end
-  end
-
-  Either.attempt_all(context) do
-    # this unit of work explicitly returns success or failure
-    # no exceptions are catched and if they occur, well, they behave as expected
-    # methods from the context can be accessed, the use of self for setters is necessary
-    let { self.settings = LoadSettings.call(env) }
-
-    # with #try all exceptions will be transformed into a Failure
-    try { do_something }
-  end
-```
-
 ### Pattern matching
 Now that you have some result, you want to control flow by providing patterns.
 `#match` can match by
 
- * success, failure, either or any
+ * success, failure, result or any
  * values
  * lambdas
  * classes
@@ -184,7 +204,7 @@ Now that you have some result, you want to control flow by providing patterns.
 Success(1).match do
   success { |v| "success #{v}"}
   failure { |v| "failure #{v}"}
-  either  { |v| "either #{v}"}
+  result  { |v| "result #{v}"}
 end # => "success 1"
 ```
 Note1: the inner value has been unwrapped! 
@@ -217,18 +237,6 @@ Success([1, 2, 3]).match do
 end # => 1
 ```
 
-Combining `#attempt_all` and `#match` is the ultimate sophistication:
-
-```ruby
-Either.attempt_all do
-  try { 1 }
-  try { |v| v + 1 }
-end.match do
-  success(1) { |v| "We made it to step #{v}" }
-  success(2) { |v| "The correct answer is #{v}"}
-end # => "The correct answer is 2"
-```
-
 If no match was found a `NoMatchError` is raised, so make sure you always cover all possible outcomes.
 
 ```ruby
@@ -246,59 +254,19 @@ end # => "catch-all"
 ```
 
 ## core_ext
-You can use a core extension, to include Either in your own class or in Object, i.e. in all classes.
+You can use a core extension, to include Result in your own class or in Object, i.e. in all classes.
 
-In a class, as a mixin
+## Result
 
 ```ruby
-require "deterministic/core_ext/either" # this includes Deterministic in the global namespace!
-class UnderTest
-  include Deterministic::CoreExt::Either
-  def test
-    attempt_all do
-      try { foo }
-    end
-  end
-
-  def foo
-    1
-  end
-end
+require 'deterministic/core_ext/object/result'
 
-ut = UnderTest.new
-ut.test # => Success(1)
+[1].success?        # => false
+Success(1).failure? # => false
+Success(1).success? # => true
+Failure(1).result?  # => true
 ```
 
-To add it to all classes
-
-```ruby
-require "deterministic/core_ext/object/either" # this includes Deterministic  to Object
-
-class UnderTest
-  def test
-    attempt_all do
-      try { foo }
-    end
-  end
-
-  def foo
-    1
-  end
-end
-
-ut = UnderTest.new
-ut.test # => Success(1)
-```
-
-or use it on built-in classes
-
-```ruby
-require "deterministic/core_ext/object/either"
-h = {a:1}
-h.attempt_all do
-  try { |s| s[:a] + 1}
-end # => Success(2)
-```
 
 ## Maybe
 The simplest NullObject wrapper there can be. It adds `#some?` and `#none?` to `Object` though.
@@ -307,7 +275,7 @@ The simplest NullObject wrapper there can be. It adds `#some?` and `#none?` to `
 require 'deterministic/maybe' # you need to do this explicitly
 Maybe(nil).foo        # => None
 Maybe(nil).foo.bar    # => None
-Mmaybe({a: 1})[:a]     # => 1
+Maybe({a: 1})[:a]     # => 1
 
 Maybe(nil).none?      # => true
 Maybe({}).none?       # => false
@@ -332,7 +300,7 @@ null.foo              # => NoMethodError
 
 ## Inspirations
  * My [Monadic gem](http://github.com/pzol/monadic) of course
- * `#attempt_all` was somewhat inspired by [An error monad in Clojure](http://brehaut.net/blog/2011/error_monads)
+ * `#attempt_all` was somewhat inspired by [An error monad in Clojure](http://brehaut.net/blog/2011/error_monads) (attempt all has now been removed)
  * [Pithyless' rumblings](https://gist.github.com/pithyless/2216519)
  * [either by rsslldnphy](https://github.com/rsslldnphy/either)
  * [Functors, Applicatives, And Monads In Pictures](http://adit.io/posts/2013-04-17-functors,_applicatives,_and_monads_in_pictures.html)

data/lib/deterministic/core_ext/object/result.rb

@@ -0,0 +1,6 @@
+require "deterministic/core_ext/result"
+
+include Deterministic
+class Object
+  include Deterministic::CoreExt::Result
+end

data/lib/deterministic/core_ext/{either.rb → result.rb}

@@ -2,7 +2,7 @@ include Deterministic
 
 module Deterministic
   module CoreExt
-    module Either
+    module Result
       def success?
         self.is_a? Success
       end
@@ -11,13 +11,9 @@ module Deterministic
         self.is_a? Failure
       end
 
-      def either?
+      def result?
         success? || failure?
       end
-
-      def attempt_all(context=self, &block)
-        Deterministic::Either::AttemptAll.new(context, &block).call(self)
-      end
     end
   end
 end

data/lib/deterministic/monad.rb

@@ -16,17 +16,17 @@ module Deterministic
     # The functor: takes a function (a -> b) and applies it to the inner value of the monad (Ma),
     # boxes it back to the same monad (Mb)
     # fmap :: (a -> b) -> M a -> M b
-    def map(proc=nil, &block)
+    def fmap(proc=nil, &block)
       result = (proc || block).call(value)
       self.class.new(result)
     end
 
     # The monad: takes a function which returns a monad (of the same type), applies the function
-    # bind :: M a  -> (a -> Mb) -> M b
+    # bind :: (a -> Mb) -> M a  -> M b
     # the self.class, i.e. the containing monad is passed as a second (optional) arg to the function
     def bind(proc=nil, &block)
       (proc || block).call(value, self.class).tap do |result|
-        raise NotMonadError, "Expected #{result.inspect} to be an Either" unless result.is_a? self.class
+        raise NotMonadError, "Expected #{result.inspect} to be an Result" unless result.is_a? self.class
       end
     end
     alias :'>>=' :bind

data/lib/deterministic/result/chain.rb

@@ -0,0 +1,27 @@
+module Deterministic
+  class Result
+    module Chain
+      def map(proc=nil, &block)
+        return self if failure?
+        bind(proc || block)
+      end
+
+      alias :>> :map
+
+      def map_err(proc=nil, &block)
+        return self if success?
+        bind(proc || block)
+      end
+
+      def try(proc=nil, &block)
+        map(proc, &block)
+      rescue => err
+        Failure(err)
+      end
+
+      alias :>= :try
+
+    end
+  end
+end
+

data/lib/deterministic/result/failure.rb

@@ -0,0 +1,5 @@
+module Deterministic
+  class Failure < Result
+    class << self; public :new; end
+  end
+end

data/lib/deterministic/{either → result}/match.rb

@@ -4,7 +4,7 @@ module Deterministic::PatternMatching
     context ||= block.binding.eval('self')
     match = Match.new(self, context)
     match.instance_eval &block
-    match.result
+    match.call
   end
 
   class NoMatchError < StandardError; end
@@ -16,14 +16,14 @@ module Deterministic::PatternMatching
       @collection = []
     end
 
-    def result
+    def call
       matcher = @collection.detect { |m| m.matches?(@container.value) }
-      raise NoMatchError, "No could be made for #{@container}" if matcher.nil?
+      raise NoMatchError, "No match could be made for #{@container.inspect}" if matcher.nil?
       @context.instance_exec(@container.value, &matcher.block)
     end
 
-    # TODO: Either specific DSL, will need to move it to Either, later on
-    %w[Success Failure Either].each do |s|
+    # TODO: Result specific DSL, will need to move it to Result, later on
+    %w[Success Failure Result].each do |s|
       define_method s.downcase.to_sym do |value=nil, &block|
         klas = Module.const_get(s)
         push(klas, value, block)

data/lib/deterministic/result/success.rb

@@ -0,0 +1,5 @@
+module Deterministic
+  class Success < Result
+    class << self; public :new; end
+  end
+end

data/lib/deterministic/{either.rb → result.rb}

@@ -1,13 +1,13 @@
 module Deterministic
   # Abstract parent of Success and Failure
-  class Either
+  class Result
     include Monad
     include Deterministic::PatternMatching
     include Chain
 
     def bind(proc=nil, &block)
-      (proc || block).call(value, self.class).tap do |result|
-        raise NotMonadError, "Expected #{result.inspect} to be an Either" unless result.is_a? self.class.superclass
+      (proc || block).call(value).tap do |result|
+        raise NotMonadError, "Expected #{result.inspect} to be an Result" unless result.is_a? self.class.superclass
       end
     end
 
@@ -19,9 +19,33 @@ module Deterministic
       is_a? Failure
     end
 
-    def <<(other)
+    def pipe(proc=nil, &block)
+      (proc || block).call(self)
+      self
+    end
+
+    alias :** :pipe
+
+    def and(other)
+      return self if failure?
+      raise NotMonadError, "Expected #{other.inspect} to be an Result" unless other.is_a? Result
+      other
+    end
+
+    def and_then(&block)
       return self if failure?
-      return other if other.is_a? Either
+      bind(&block)
+    end
+
+    def or(other)
+      return self if success?
+      raise NotMonadError, "Expected #{other.inspect} to be an Result" unless other.is_a? Result
+      return other
+    end
+
+    def or_else(&block)
+      return self if success?
+      bind(&block)
     end
 
     # This is an abstract class, can't ever instantiate it directly
@@ -40,7 +64,6 @@ module Deterministic
   end
 
 module_function
-
   def Success(value)
     Success.new(value)
   end

data/lib/deterministic/version.rb

@@ -1,3 +1,3 @@
 module Deterministic
-  VERSION = "0.8.1"
+  VERSION = "0.10.0"
 end

data/lib/deterministic.rb

@@ -5,10 +5,9 @@ warn "WARN: Deterministic is meant to run on Ruby 2+" if RUBY_VERSION.to_f < 2
 module Deterministic; end
 
 require 'deterministic/monad'
-require 'deterministic/either/match'
-require 'deterministic/either/chain'
-require 'deterministic/either'
-require 'deterministic/either/attempt_all'
-require 'deterministic/either/success'
-require 'deterministic/either/failure'
+require 'deterministic/result/match'
+require 'deterministic/result/chain'
+require 'deterministic/result'
+require 'deterministic/result/success'
+require 'deterministic/result/failure'
 require 'deterministic/none'

data/spec/examples/bookings_spec.rb

@@ -33,10 +33,8 @@ module Examples
       end
 
       def call(dirty_params)
-        result = Either.attempt_all(self) do
-          try {          parse_params(dirty_params) }
-          let { |params| read_bookings(params)           }
-        end.match(world) do
+
+        ( parse_params(dirty_params) >> method(:read_bookings) ).match(world) do
           success(Array)         { |bookings| booking_list(bookings) }
           success                { |booking|  booking(booking)       }
           failure(:no_bookings)  { empty_booking_list                }
@@ -49,7 +47,7 @@ module Examples
       attr_reader   :bookings_repo, :world
 
       def parse_params(dirty_params)
-        dirty_params
+        Success(dirty_params)
       end
 
       def read_bookings(params)

data/spec/lib/deterministic/core_ext/object/either_spec.rb

@@ -1,28 +1,11 @@
 require "spec_helper"
-require "deterministic/core_ext/object/either"
+require "deterministic/core_ext/object/result"
 
-describe Deterministic::CoreExt::Either, "object", isolate: true do
+describe Deterministic::CoreExt::Result, "object", isolate: true do
   it "does something" do
     h = {a: 1}
     expect(h.success?).to be_falsey
     expect(h.failure?).to be_falsey
-    expect(h.either?).to be_falsey
-  end
-
-  it "use attempt_all in an instance" do
-    class UnderTest
-      def test
-        attempt_all do
-          try { foo }
-        end
-      end
-
-      def foo
-        1
-      end
-    end
-
-    ut = UnderTest.new
-    expect(ut.test).to eq Success(1)
+    expect(h.result?).to be_falsey
   end
 end