deterministic 0.12.1 → 0.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3c142a92639ccc4051cc59535565f1acb5816a25
-  data.tar.gz: c916f4398175f4a5a0d3fc2142263d9c999d7ac8
+  metadata.gz: 120b61f2caf3653ca63fc4bca59908c8c3add91b
+  data.tar.gz: 2813dd0b90f301a5afcbc7861e446c3bdc507f15
 SHA512:
-  metadata.gz: 5da47c489e0c973dfb02aa9d3f1a968b812855b3af4001f8c70ea72aa5ed8188a587713bf13df63b9af0dfadbd5f4420c93b90592e8442997e21dc9590b7b2a3
-  data.tar.gz: c7252b32ba1889a08a32c05aadb0c76469822f2a646f1bb1f54bf54a6e7c081c3e43640a57e66b68da0c6d88da5092638ac7a19de1fb56a397de741d72d3057d
+  metadata.gz: d3195c0fbd1f114843e7003e84b9e24ba129933986ef948f44f19be83202719148b44554d27146acd0addd728aab98bb265356ea1d14e8338b8eaee705bdd91e
+  data.tar.gz: 721194e06a0618864efffcf079f6cc4220c58b3e0a962e7f2c43186d01e2bcc8825d34999c7c8a4abe8270bd6153901d30dd46393f7e8327a14bdb640a95f094

data/HISTORY.md

@@ -1,3 +1,21 @@
+## v0.13.0
+
+- Add `Option#value_to_a`
+- Add `Option#+`
+- Make `None` a real monad (little impact on the real world)
+- Add `Either`
+- Add `Option#value_or`
+- `None#value` is now private
+
+## v0.12.1
+
+- Fix backwards compatibility with Ruby < 2.0.0
+
+## v0.12.0
+
+- Add Option
+- Nest `Success` and `Failure` under `Result`
+
 ## v0.10.0
 ** breaking changes **
 

data/README.md

@@ -6,6 +6,29 @@ Deterministic is to help your code to be more confident, it's specialty is flow
 
 This is a spiritual successor of the [Monadic gem](http://github.com/pzol/monadic). The goal of the rewrite is to get away from a bit to forceful aproach I took in Monadic, especially when it comes to coercing monads, but also a more practical but at the same time more strict adherence to monad laws.
 
+## Patterns
+
+Deterministic provides different monads, here is a short guide, when to use which
+
+#### Result: Success & Failure
+- an operation which can succeed or fail
+- the result (content) of of the success or failure is important
+- you are building one thing
+- chaining: if one fails (Failure), don't execute the rest
+
+#### Option: Some & None
+- an operation which returns either some result or nothing
+- in case it returns nothing it is not important to know why
+- you are working rather with a collection of things
+- chaining: execute all and then select the successful ones (Some)
+
+#### Either: Left & Right
+- an operation which returns several good and bad results
+- the results of both are important
+- chaining: if one fails, continue, the content of the failed and successful are important
+
+#### Maybe
+- an object may be nil, you want to avoid endless nil? checks
 
 ## Usage
 
@@ -19,8 +42,6 @@ Failure(1).to_s                        # => "1"
 Failure(Failure(1))                    # => Failure(1)
 ```
 
-#### `fmap(self: Result(a), op: |a| -> b) -> Result(b)`
-
 Maps a `Result` with the value `a` to the same `Result` with the value `b`.
 
 ```ruby
@@ -28,82 +49,62 @@ Success(1).fmap { |v| v + 1}           # => Success(2)
 Failure(1).fmap { |v| v - 1}           # => Failure(0)
 ```
 
-#### `bind(self: Result(a), op: |a| -> Result(b)) -> Result(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)
+Failure(1).bind { |v| Success(v - 1) } # => Success(0)
 ```
 
-#### `map(self: Success(a), op: |a| -> Result(b)) -> Result(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(self: Failure(a), op: |a| -> Result(b)) -> Result(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)
+Failure(1).map_err { |n| n + 1 }       # => Success(2)
+Success(0).map_err { |n| n + 1 }       # => Success(0)
 ```
 
-#### `try(self: Success(a),  op: |a| -> Result(b)) -> Result(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(self: Success(a), other: Result(b)) -> Result(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)
+Success(1).and Success(2)              # => Success(2)
+Failure(1).and Success(2)              # => Failure(1)
 ```
 
-#### `and_then(self: Success(a), op: |a| -> Result(b)) -> Result(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)
+Success(1).and_then { Success(2) }     # => Success(2)
+Failure(1).and_then { Success(2) }     # => Failure(1)
 ```
 
-#### `or(self: Failure(a), other: Result(b)) -> Result(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)
+Success(1).or Success(2)               # => Success(1)
+Failure(1).or Success(1)               # => Success(1)
 ```
 
-#### `or_else(self: Failure(a),  op: |a| -> Result(b)) -> Result(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)
+Success(1).or_else { Success(2) }      # => Success(1)
+Failure(1).or_else { |n| Success(n)}   # => Success(1)
 ```
 
-#### `pipe(self: Result(a), op: |Result(a)| -> b) -> Result(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)
+Success(1).try { |n| log(n.value) }    # => Success(1)
 ```
 
 The value or block result must always be a `Result` i.e. `Success` or `Failure`.
@@ -256,7 +257,7 @@ end # => "catch-all"
 ## core_ext
 You can use a core extension, to include Result in your own class or in Object, i.e. in all classes.
 
-## Result
+
 
 ```ruby
 require 'deterministic/core_ext/object/result'
@@ -267,6 +268,62 @@ Success(1).success? # => true
 Failure(1).result?  # => true
 ```
 
+## Option
+
+```ruby
+Some(1).some?                          # #=> true
+Some(1).none?                          # #=> false
+None.some?                             # #=> false
+None.none?                             # #=> true
+
+Some(1).fmap { |n| n + 1 }             # => Some(2)
+None.fmap { |n| n + 1 }                # => None
+
+Some(1).map  { |n| Some(n + 1) }       # => Some(2)
+Some(1).map  { |n| None }              # => None
+None.map     { |n| Some(n + 1) }       # => None
+
+Some(1).value                          # => 1
+Some(1).value_or(2)                    # => 1
+None.value                             # => NoMethodError
+None.value_or(0)                       # => 0
+
+Some(1).value_to_a                     # => Some([1])
+Some([1]).value_to_a                   # => Some([1])
+None.value_to_a                        # => None
+
+Some(1) + Some(1)                      # => Some(2)
+Some([1]) + Some(1)                    # => TypeError: No implicit conversion
+None + Some(1)                         # => Some(1)
+Some(1) + None                         # => Some(1)
+Some([1]) + None + Some([2])           # => Some([1, 2])
+```
+
+### Coercion
+```ruby
+Option.any?(nil)                       # => None
+Option.any?([])                        # => None
+Option.any?({})                        # => None
+Option.any?(1)                         # => Some(1)
+
+Option.some?(nil)                      # => None
+Option.some?([])                       # => Some([])
+Option.some?({})                       # => Some({})
+Option.some?(1)                        # => Some(1)
+
+Option.try! { 1 }                      # => Some(1)
+Option.try! { raise "error"}           # => None
+```
+
+### Pattern Matching 
+```ruby
+Some(1).match {
+  some(1) { |n| n + 1 }
+  some    { 1 }
+  none    { 0 }
+}                                      # => 2
+```
+
 
 ## Maybe
 The simplest NullObject wrapper there can be. It adds `#some?` and `#null?` to `Object` though.

data/lib/deterministic/either.rb

@@ -0,0 +1,35 @@
+module Deterministic
+  class Either
+    include Monad
+    class << self
+      public :new
+    end
+
+    def initialize(left=[], right=[])
+      @left, @right = left, right
+    end
+
+    attr_reader :left, :right
+
+    def +(other)
+      raise Deterministic::Monad::NotMonadError, "Expected an Either, got #{other.class}" unless other.is_a? Either
+
+      Either.new(left + other.left, right + other.right)
+    end
+
+    undef :value
+
+    def inspect
+      "Either(left: #{left.inspect}, right: #{right.inspect})"
+    end
+
+  end
+module_function
+  def Left(value)
+    Either.new(Array[value], [])
+  end
+
+  def Right(value)
+    Either.new([], Array[value])
+  end
+end

data/lib/deterministic/match.rb

@@ -18,9 +18,10 @@ module Deterministic
       end
 
       def call
-        matcher = @collection.detect { |m| m.matches?(@container.value) }
+        value = @container.respond_to?(:value) ? @container.value : nil
+        matcher = @collection.detect { |m| m.matches?(value)  }
         raise NoMatchError, "No match could be made for #{@container.inspect}" if matcher.nil?
-        @context.instance_exec(@container.value, &matcher.block)
+        @context.instance_exec(value, &matcher.block)
       end
 
       # catch-all

data/lib/deterministic/monad.rb

@@ -2,6 +2,7 @@ module Deterministic
   module Monad
     class NotMonadError < StandardError; end
 
+    # Basicly the `pure` function
     def initialize(value)
       @value = join(value)
     end

data/lib/deterministic/option.rb

@@ -45,6 +45,22 @@ module Deterministic
       bind(proc || block)
     end
 
+    ## Convert the inner value to an Array
+    def value_to_a
+      map { self.class.new(Array(value)) }
+    end
+
+    ## Add the inner values of two Some
+    def +(other)
+      return other if none?
+      fmap { |v| 
+        other.match {
+          some { v + other.value }
+          none { self }
+        }
+      }
+    end
+
     def some?
       is_a? Some
     end
@@ -53,35 +69,36 @@ module Deterministic
       is_a? None
     end
 
+    def value_or(default)
+      return default if none?
+      return value
+    end
+
     class Some < Option
       class << self; public :new; end
     end
 
     class None < Option
       class << self; public :new; end
-      def initialize(*args); end
+      def initialize(*args)
+        @value = self
+      end
 
       def inspect
         "None"
       end
 
-      # def value
-      #   self
-      # end
-      def none(*args)
+      private :value
+
+      def fmap(*args)
         self
       end
 
-      alias :fmap :none
-      alias :map :none
+      alias :map :fmap
 
       def ==(other)
         other.class == self.class
       end
-
-      # def value
-      #   self # raise "value called on a None"
-      # end
     end
   end
 

data/lib/deterministic/result.rb

@@ -18,7 +18,11 @@ module Deterministic
     end
 
     include PatternMatching
-    include Chain
+
+    # This is an abstract class, can't ever instantiate it directly
+    class << self
+      protected :new
+    end
 
     def success?
       is_a? Success
@@ -28,6 +32,8 @@ module Deterministic
       is_a? Failure
     end
 
+    # `pipe(self: Result(a), op: |Result(a)| -> b) -> Result(a)`
+    # Executes the block passed, but completely ignores its result. If an error is raised within the block it will **NOT** be catched.
     def pipe(proc=nil, &block)
       (proc || block).call(self)
       self
@@ -35,32 +41,61 @@ module Deterministic
 
     alias :** :pipe
 
+    # `pipe(self: Result(a), op: |Result(a)| -> b) -> Result(a)`
+    # Replaces `Success a` with `Result b`. If a `Failure` is passed as argument, it is ignored.
     def and(other)
       return self if failure?
       raise NotMonadError, "Expected #{other.inspect} to be an Result" unless other.is_a? Result
       other
     end
 
+    # `and_then(self: Success(a), op: |a| -> Result(b)) -> Result(b)`
+    # Replaces `Success a` with the result of the block. If a `Failure` is passed as argument, it is ignored.
     def and_then(&block)
       return self if failure?
       bind(&block)
     end
 
+    # `or(self: Failure(a), other: Result(b)) -> Result(b)` 
+    # Replaces `Failure a` with `Result`. If a `Failure` is passed as argument, it is ignored.
     def or(other)
       return self if success?
       raise NotMonadError, "Expected #{other.inspect} to be an Result" unless other.is_a? Result
       return other
     end
 
+    # `or_else(self: Failure(a),  op: |a| -> Result(b)) -> Result(b)`
+    # Replaces `Failure a` with the result of the block. If a `Success` is passed as argument, it is ignored.
     def or_else(&block)
       return self if success?
       bind(&block)
     end
 
-    # This is an abstract class, can't ever instantiate it directly
-    class << self
-      protected :new
+    # `map(self: Success(a), op: |a| -> Result(b)) -> Result(b)`
+    # Maps a `Success` with the value `a` to another `Result` with the value `b`. It works like `#bind` but only on `Success`.
+    def map(proc=nil, &block)
+      return self if failure?
+      bind(proc || block)
+    end
+
+    alias :>> :map
+
+    # `map_err(self: Failure(a), op: |a| -> Result(b)) -> Result(b)`
+    # Maps a `Failure` with the value `a` to another `Result` with the value `b`. It works like `#bind` but only on `Failure`.
+    def map_err(proc=nil, &block)
+      return self if success?
+      bind(proc || block)
+    end
+
+    # `pipe(self: Result(a), op: |Result(a)| -> b) -> Result(a)`
+    # Executes the block passed, but completely ignores its result. If an error is raised within the block it will **NOT** be catched.
+    def try(proc=nil, &block)
+      map(proc, &block)
+    rescue => err
+      Failure(err)
     end
+
+    alias :>= :try
     
     class Failure < Result
       class << self; public :new; end

data/lib/deterministic/version.rb

@@ -1,3 +1,3 @@
 module Deterministic
-  VERSION = "0.12.1"
+  VERSION = "0.13.1"
 end

data/lib/deterministic.rb

@@ -6,7 +6,7 @@ module Deterministic; end
 
 require 'deterministic/monad'
 require 'deterministic/match'
-require 'deterministic/result/chain'
 require 'deterministic/result'
 require 'deterministic/option'
+require 'deterministic/either'
 require 'deterministic/null'

data/spec/lib/deterministic/either_spec.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+
+include Deterministic
+
+describe Deterministic::Either do
+  it "+ does not change operands" do
+    l = Left(1)
+    r = Right(2)
+
+    either = l + r
+    expect(l).to eq Left(1)
+    expect(r).to eq Right(2)
+    expect(either).to eq Either.new([1], [2])
+  end
+
+  it "allows adding multiple Eithers" do
+    either = Left(1) + Left(2) + Right(:a) + Right(:b)
+    expect(either.left).to eq [1, 2]
+    expect(either.right).to eq [:a, :b]
+  end
+
+  it "works" do
+    actual = [1, 2, 3, 4].inject(Either.new) { |acc, value|
+      acc + (value % 2 == 0 ? Right(value) : Left(value))
+    }
+    expect(actual).to eq Either.new([1, 3], [2, 4])
+  end
+
+end

data/spec/lib/deterministic/option_spec.rb

@@ -11,6 +11,7 @@ describe Deterministic::Option do
 
   # any?
   specify { expect(described_class.any?(nil)).to be_none }
+  specify { expect(described_class.any?(None)).to be_none }
   specify { expect(described_class.any?("")).to  be_none }
   specify { expect(described_class.any?([])).to  be_none }
   specify { expect(described_class.any?({})).to  be_none }
@@ -21,21 +22,53 @@ describe Deterministic::Option do
   specify { expect(described_class.try! { raise "error" }).to be_none }
 end
 
-describe Deterministic::Option::Some do
-   it_behaves_like 'a Monad' do
-    let(:monad) { described_class }
-  end
+describe Deterministic::Option do
+  #  it_behaves_like 'a Monad' do
+  #   let(:monad) { described_class }
+  # end
+
+  specify { expect(Option::Some.new(0)).to be_a Option::Some }
+  specify { expect(Option::Some.new(0)).to eq Some(0) }
+
+  specify { expect(Option::None.new).to eq Option::None.new }
+  specify { expect(Option::None.new).to eq None }
+
+  # some?, none?
+  specify { expect(None.some?).to be_falsey }
+  specify { expect(None.none?).to be_truthy }
+  specify { expect(Some(0).some?).to be_truthy }
+  specify { expect(Some(0).none?).to be_falsey }
+
+  # value, value_or
+  specify { expect(Some(0).value).to eq 0 }
+  specify { expect(Some(1).value_or(2)).to eq 1}
+  specify { expect { None.value }.to raise_error NoMethodError }
+  specify { expect(None.value_or(2)).to eq 2}
+
+  # fmap
+  specify { expect(Some(1).fmap { |n| n + 1}).to eq Some(2) }
+  specify { expect(None.fmap { |n| n + 1}).to eq None }
+
+  # map
+  specify { expect(Some(1).map { |n| Some(n + 1)}).to eq Some(2) }
+  specify { expect(Some(1).map { |n| None }).to eq None }
+  specify { expect(None.map { |n| nil }).to eq None }
 
-  specify { expect(described_class.new(0)).to be_a Option::Some }
-  specify { expect(described_class.new(0)).to eq Some(0) }
-  specify { expect(described_class.new(0).some?).to be_truthy }
-  specify { expect(described_class.new(0).none?).to be_falsey }
-  specify { expect(described_class.new(0).value).to eq 0 }
+  # to_a
+  specify { expect(Some(1).value_to_a). to eq Some([1])}
+  specify { expect(Some([1]).value_to_a). to eq Some([1])}
+  specify { expect(None.value_to_a). to eq None}
 
-  specify { expect(described_class.new(1).fmap { |n| n + 1}).to eq Some(2) }
-  specify { expect(described_class.new(1).map { |n| Some(n + 1)}).to eq Some(2) }
-  specify { expect(described_class.new(1).map { |n| None }).to eq None }
+  # +
+  specify { expect(Some(1) + None).to eq Some(1) }
+  specify { expect(Some(1) + None + None).to eq Some(1) }
+  specify { expect(Some(1) + Some(1)).to eq Some(2) }
+  specify { expect(None + Some(1)).to eq Some(1) }
+  specify { expect(None + None + Some(1)).to eq Some(1) }
+  specify { expect(None + None + Some(1) + None).to eq Some(1) }
+  specify { expect { Some([1]) + Some(1)}.to raise_error TypeError}
 
+  # match
   specify {
     expect(
       Some(0).match {
@@ -75,18 +108,14 @@ describe Deterministic::Option::Some do
 
 end
 
-describe Deterministic::Option::None do
-  #  it_behaves_like 'a Monad' do
-  #   let(:monad) { described_class }
-  # end
-
-  specify { expect(described_class.new).to eq None }
-  specify { expect(described_class.new.some?).to be_falsey }
-  specify { expect(described_class.new.none?).to be_truthy }
-  # specify { expect { described_class.new.value }.to raise_error RuntimeError }
+describe Deterministic::Option::Some do
+   it_behaves_like 'a Monad' do
+    let(:monad) { described_class }
+  end
+end
 
-  specify { expect(described_class.new.fmap { |n| n + 1}).to eq None }
-  specify { expect(described_class.new.map { |n| nil }).to eq None }
-  specify { expect(described_class.new).to eq Option::None.new }
-  specify { expect(described_class.new).to eq None }
+describe Deterministic::Option::None do
+   it_behaves_like 'a Monad' do
+    let(:monad) { described_class }
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: deterministic
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.13.1
 platform: ruby
 authors:
 - Piotr Zolnierek
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-26 00:00:00.000000000 Z
+date: 2014-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -127,27 +127,28 @@ files:
 - lib/deterministic.rb
 - lib/deterministic/core_ext/object/result.rb
 - lib/deterministic/core_ext/result.rb
+- lib/deterministic/either.rb
 - lib/deterministic/match.rb
 - lib/deterministic/maybe.rb
 - lib/deterministic/monad.rb
 - lib/deterministic/null.rb
 - lib/deterministic/option.rb
 - lib/deterministic/result.rb
-- lib/deterministic/result/chain.rb
 - lib/deterministic/version.rb
 - spec/examples/bookings_spec.rb
 - spec/examples/config_spec.rb
 - spec/examples/validate_address_spec.rb
 - spec/lib/deterministic/core_ext/object/either_spec.rb
 - spec/lib/deterministic/core_ext/result_spec.rb
+- spec/lib/deterministic/either_spec.rb
 - spec/lib/deterministic/maybe_spec.rb
 - spec/lib/deterministic/monad_axioms.rb
 - spec/lib/deterministic/monad_spec.rb
 - spec/lib/deterministic/null_spec.rb
 - spec/lib/deterministic/option_spec.rb
-- spec/lib/deterministic/result/chain_spec.rb
 - spec/lib/deterministic/result/failure_spec.rb
 - spec/lib/deterministic/result/match_spec.rb
+- spec/lib/deterministic/result/result_map.rb
 - spec/lib/deterministic/result/result_shared.rb
 - spec/lib/deterministic/result/success_spec.rb
 - spec/lib/deterministic/result_spec.rb
@@ -182,14 +183,15 @@ test_files:
 - spec/examples/validate_address_spec.rb
 - spec/lib/deterministic/core_ext/object/either_spec.rb
 - spec/lib/deterministic/core_ext/result_spec.rb
+- spec/lib/deterministic/either_spec.rb
 - spec/lib/deterministic/maybe_spec.rb
 - spec/lib/deterministic/monad_axioms.rb
 - spec/lib/deterministic/monad_spec.rb
 - spec/lib/deterministic/null_spec.rb
 - spec/lib/deterministic/option_spec.rb
-- spec/lib/deterministic/result/chain_spec.rb
 - spec/lib/deterministic/result/failure_spec.rb
 - spec/lib/deterministic/result/match_spec.rb
+- spec/lib/deterministic/result/result_map.rb
 - spec/lib/deterministic/result/result_shared.rb
 - spec/lib/deterministic/result/success_spec.rb
 - spec/lib/deterministic/result_spec.rb

data/lib/deterministic/result/chain.rb

@@ -1,27 +0,0 @@
-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
-