deterministic 0.14.1 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 168526a86344e4c8cbab6c7a61cc5d498db3d404
-  data.tar.gz: cdfa647cd679132878d0deab9cbae65a1c8a9ecd
+  metadata.gz: 8a1e76d13413c85adaf4807bc4967275b85a0436
+  data.tar.gz: c3eae53b159a16996c9f384c15b5274fe90b14f1
 SHA512:
-  metadata.gz: e4280111607d96258055bef389cc7f2c046ed3fe09f3762467b55e3b14ed63257fe43453aef46a28615bfd19b65c882bffe160cb4cd97c3d613f67ae028cd2df
-  data.tar.gz: ca9701d45bf4682a57b33ac9b323aba4381db78ba52b3b67c8e838dc7b001056a177a3f33c843adc265019f9439fbc8e82a216f904a51ccc241fd69219df272a
+  metadata.gz: 3955dda1c3e00c7a3814d5bb766453a3615c29a65cdec56e21a91bcdf4feff8d55f5f7bb1999d78116306d3bca59d7d30de620bc80f70e6df25b1c6eb7f349f8
+  data.tar.gz: 84da7a63dab19f2fa754ad4694c7b3b00eccf3e5684d00caa5e5d9d854cb4f46075ea597f089685967e6f710cdd1dbe66e36833824d333bd981d452206c6ce75

data/README.md

@@ -2,7 +2,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/deterministic.png)](http://badge.fury.io/rb/deterministic)
 
-Deterministic is to help your code to be more confident, it's specialty is flow control of actions that either succeed or fail.
+Deterministic is to help your code to be more confident, by utilizing functional programming patterns.
 
 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.
 
@@ -30,6 +30,9 @@ Deterministic provides different monads, here is a short guide, when to use whic
 #### Maybe
 - an object may be nil, you want to avoid endless nil? checks
 
+#### Enums (Algebraic Data Types)
+- roll your own pattern
+
 ## Usage
 
 ### Result: Success & Failure
@@ -103,12 +106,6 @@ Failure(1).or_else { |n| Success(n)}   # => Success(1)
 
 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
 
 You can easily chain the execution of several operations. Here we got some nice function composition.  
@@ -118,14 +115,17 @@ The following aliases are defined
 
 ```ruby
 alias :>> :map
-alias :>= :try
-alias :** :pipe       # the operator must be right associative
+alias :<< :pipe
 ```
 
 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
+Success(params) >>
+  validate >>
+  build_request << log >>
+  send << log >>
+  build_response
 ```
 
 #### Complex Example in a Builder Class
@@ -203,9 +203,8 @@ Now that you have some result, you want to control flow by providing patterns.
 
 ```ruby
 Success(1).match do
-  success { |v| "success #{v}"}
-  failure { |v| "failure #{v}"}
-  result  { |v| "result #{v}"}
+  Success(s) { |v| "success #{s}"}
+  Failure(f) { |v| "failure #{f}"}
 end # => "success 1"
 ```
 Note1: the inner value has been unwrapped! 
@@ -214,19 +213,11 @@ Note2: only the __first__ matching pattern block will be executed, so order __ca
 
 The result returned will be the result of the __first__ `#try` or `#let`. As a side note, `#try` is a monad, `#let` is a functor.
 
-Values for patterns are good, too:
-
-```ruby
-Success(1).match do
-  success(1) {|v| "Success #{v}" }
-end # => "Success 1"
-```
-
-You can and should also use procs for patterns:
+Guards
 
 ```ruby
 Success(1).match do
-  success ->(v) { v == 1 } {|v| "Success #{v}" }
+  Success(s, where { s == 1 }) { "Success #{s}" }
 end # => "Success 1"
 ```
 
@@ -234,7 +225,7 @@ Also you can match the result class
 
 ```ruby
 Success([1, 2, 3]).match do
-  success(Array) { |v| v.first }
+  Success(s, where { s.is_a?(Array)} ) { s.first }
 end # => 1
 ```
 
@@ -242,23 +233,15 @@ If no match was found a `NoMatchError` is raised, so make sure you always cover
 
 ```ruby
 Success(1).match do
-  failure(1) { "you'll never get me" }
+  Failure(f) { "you'll never get me" }
 end # => NoMatchError
 ```
 
-A way to have a catch-all would be using an `any`:
-
-```ruby
-Success(1).match do
-  any { "catch-all" }
-end # => "catch-all"
-```
+Matches must be exhaustive, otherwise an error will be raised, showing the variants which have not been covered.
 
 ## core_ext
 You can use a core extension, to include Result in your own class or in Object, i.e. in all classes.
 
-
-
 ```ruby
 require 'deterministic/core_ext/object/result'
 
@@ -275,23 +258,35 @@ Some(1).some?                          # #=> true
 Some(1).none?                          # #=> false
 None.some?                             # #=> false
 None.none?                             # #=> true
+```
 
+Maps an `Option` with the value `a` to the same `Option` with the value `b`.
+
+```ruby
 Some(1).fmap { |n| n + 1 }             # => Some(2)
 None.fmap { |n| n + 1 }                # => None
+```
 
+Maps a `Result` with the value `a` to another `Result` with the value `b`.
+
+```ruby
 Some(1).map  { |n| Some(n + 1) }       # => Some(2)
 Some(1).map  { |n| None }              # => None
 None.map     { |n| Some(n + 1) }       # => None
+```
 
+Get the inner value or provide a default for a `None`. Calling `#value` on a `None` will raise a `NoMethodError`
+
+```ruby
 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
+Add the inner values of option using `+`.
 
+```ruby
 Some(1) + Some(1)                      # => Some(2)
 Some([1]) + Some(1)                    # => TypeError: No implicit conversion
 None + Some(1)                         # => Some(1)
@@ -315,15 +310,87 @@ Option.try! { 1 }                      # => Some(1)
 Option.try! { raise "error"}           # => None
 ```
 
-### Pattern Matching 
+### Pattern Matching
 ```ruby
 Some(1).match {
-  some(1) { |n| n + 1 }
-  some    { 1 }
-  none    { 0 }
+  Some(s, where { s == 1 }) { s + 1 }
+  Some(s)                   { 1 }
+  None()                    { 0 }
 }                                      # => 2
 ```
 
+## Enums
+All the above are implemented using enums, see their definition, for more details.
+
+Define it, with all variants:
+
+```ruby
+Threenum = Deterministic::enum {
+            Nullary()
+            Unary(:a)
+            Binary(:a, :b)
+           }
+
+Threenum.variants                      # => [:Nullary, :Unary, :Binary]
+```
+
+Initialize
+
+```ruby
+n = Threenum.Nullary                   # => Threenum::Nullary.new()
+n.value                                # => Error
+
+u = Threenum.Unary(1)                  # => Threenum::Unary.new(1)
+u.value                                # => 1
+
+b = Threenum::Binary(2, 3)             # => Threenum::Binary(2, 3)
+b.value                                # => { a:2, b: 3 }
+```
+
+Pattern matching
+
+```ruby
+Threenum::Unary(5).match {
+  Nullary()     { 0 }
+  Unary(u)      { u }
+  Binary(a, b)  { a + b }
+}                                      # => 5
+
+# or
+t = Threenum::Unary(5)
+Threenum.match(t) {
+  Nullary()     { 0 }
+  Unary(u)      { u }
+  Binary(a, b)  { a + b }
+}                                      # => 5
+```
+
+If you want the whole thing use the arg passed to the block (second case)
+
+```ruby
+def drop(n)
+  match {
+    Cons(h, t, where { n > 0 }) { t.drop(n - 1) }
+    Cons(_, _) { |c| c }
+    Nil() { raise EmptyListError}
+  }
+end
+```
+
+See the linked list implementation in the specs for more examples
+
+With guard clauses
+
+```ruby
+Threenum::Unary(5).match {
+  Nullary()     { 0 }
+  Unary(u)      { u }
+  Binary(a, b, where { a.is_a?(Fixnum) && b.is_a?(Fixnum)})  { a + b }
+  Binary(a, b)  { raise "Expected a, b to be numbers" }
+}                                      # => 5
+```
+
+All matches must be exhaustive, i.e. cover all variants
 
 ## Maybe
 The simplest NullObject wrapper there can be. It adds `#some?` and `#null?` to `Object` though.

data/lib/deterministic.rb

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

data/lib/deterministic/enum.rb

@@ -0,0 +1,203 @@
+module Deterministic
+  module Enum
+    class MatchError < StandardError; end
+  end
+
+  class EnumBuilder
+    def initialize(parent)
+      @parent = parent
+    end
+
+    class DataType
+      module AnyEnum
+        include Deterministic::Monad
+
+        def match(&block)
+          parent.match(self, &block)
+        end
+
+        def to_s
+          value.to_s
+        end
+
+        def name
+          self.class.name.split("::")[-1]
+        end
+      end
+
+      module Nullary
+        def initialize(*args)
+          @value = nil
+        end
+
+        def inspect
+          name
+        end
+      end
+
+      module Binary
+        def initialize(*init)
+          raise ArgumentError, "Expected arguments for #{args}, got #{init}" unless (init.count == 1 && init[0].is_a?(Hash)) || init.count == args.count
+          if init.count == 1 && init[0].is_a?(Hash)
+            @value = Hash[args.zip(init[0].values)]
+          else
+            @value = Hash[args.zip(init)]
+          end
+        end
+
+        def inspect
+          params = value.map { |k, v| "#{k}: #{v.inspect}" }
+          "#{name}(#{params.join(', ')})"
+        end
+      end
+
+      def self.create(parent, name, args)
+        raise ArgumentError, "#{args} may not contain the reserved name :value" if args.include? :value
+        dt = Class.new(parent)
+
+        dt.instance_eval {
+          class << self; public :new; end
+          include AnyEnum
+          define_method(:args) { args }
+
+          define_method(:parent) { parent }
+          private :parent
+        }
+
+        if args.count == 0
+          dt.instance_eval {
+            include Nullary
+            private :value
+          }
+        elsif args.count == 1
+          dt.instance_eval {
+            define_method(args[0].to_sym) { value }
+          }
+        else
+          dt.instance_eval {
+            include Binary
+
+            args.each do |m|
+              define_method(m) do
+                @value[m]
+              end
+            end
+          }
+        end
+        dt
+      end
+
+      class << self
+        public :new;
+      end
+    end
+
+    def method_missing(m, *args)
+      @parent.const_set(m, DataType.create(@parent, m, args))
+    end
+  end
+
+module_function
+  def enum(&block)
+    mod = Class.new do # the enum to be built
+      class << self; private :new; end
+
+      def self.match(obj, &block)
+        matcher = self::Matcher.new(obj)
+        matcher.instance_eval(&block)
+
+        variants_in_match = matcher.matches.collect {|e| e[1].name.split('::')[-1].to_sym}.uniq.sort
+        variants_not_covered = variants - variants_in_match
+        raise Enum::MatchError, "Match is non-exhaustive, #{variants_not_covered} not covered" unless variants_not_covered.empty?
+
+        type_matches = matcher.matches.select { |r| r[0].is_a?(r[1]) }
+
+        type_matches.each { |match|
+          obj, type, block, args, guard = match
+
+          if args.count == 0
+            return instance_exec(obj, &block)
+          else
+            raise Enum::MatchError, "Pattern (#{args.join(', ')}) must match (#{obj.args.join(', ')})" if args.count != obj.args.count
+            context = exec_context(obj, args)
+
+            if guard
+              if context.instance_exec(obj, &guard)
+                return context.instance_exec(obj, &block)
+              end
+            else
+              return context.instance_exec(obj, &block)
+            end
+          end
+        }
+
+        raise Enum::MatchError, "No match could be made"
+      end
+
+      def self.variants; constants - [:Matcher, :MatchError]; end
+
+      private
+      def self.exec_context(obj, args)
+        if obj.is_a?(Deterministic::EnumBuilder::DataType::Binary)
+          Struct.new(*(args)).new(*(obj.value.values))
+        else
+          Struct.new(*(args)).new(obj.value)
+        end
+      end
+    end
+    enum = EnumBuilder.new(mod)
+    enum.instance_eval(&block)
+
+    type_variants = mod.constants
+
+    matcher = Class.new {
+      def initialize(obj)
+        @obj = obj
+        @matches = []
+        @vars = []
+      end
+
+      attr_reader :matches, :vars
+
+      def where(&guard)
+        guard
+      end
+
+      def method_missing(m)
+        m
+      end
+
+      type_variants.each { |m|
+        define_method(m) { |*args, &block|
+          raise ArgumentError, "No block given to `#{m}`" if block.nil?
+          type = Kernel.eval("#{mod.name}::#{m}")
+
+          if args.count > 0 && args[-1].is_a?(Proc)
+            guard = args.delete_at(-1)
+          end
+
+          @matches << [@obj, type, block, args, guard]
+        }
+      }
+    }
+
+    mod.const_set(:Matcher, matcher)
+
+    type_variants.each { |variant|
+      mod.singleton_class.class_exec {
+        define_method(variant) { |*args|
+          const_get(variant).new(*args)
+        }
+      }
+    }
+    mod
+  end
+
+  def impl(enum_type, &block)
+    enum_type.variants.each { |v|
+      name = "#{enum_type.name}::#{v.to_s}"
+      type = Kernel.eval(name)
+      type.class_eval(&block)
+    }
+  end
+end