dry-monads 0.4.0 → 1.0.0.beta1

data/lib/dry/monads/transformer.rb

@@ -1,5 +1,6 @@
 module Dry
   module Monads
+    # Advanced tranformations.
     module Transformer
       # Lifts a block/proc over the 2-level nested structure.
       # This is essentially fmap . fmap (. is the function composition

data/lib/dry/monads/traverse.rb

@@ -0,0 +1,20 @@
+require 'dry/monads/validated'
+
+module Dry
+  module Monads
+    to_list = List::Validated.method(:pure)
+
+    id = -> x { x }
+
+    # List of default traverse functions for types.
+    # It is implicitly used by List#traverse for
+    # making common cases easier to handle.
+    Traverse = {
+      Validated => -> el { el.alt_map(to_list) }
+    }
+
+    # By default the identity function is used
+    Traverse.default = id
+    Traverse.freeze
+  end
+end

data/lib/dry/monads/try.rb

@@ -1,4 +1,5 @@
 require 'dry/equalizer'
+require 'dry/core/deprecations'
 
 require 'dry/monads/right_biased'
 require 'dry/monads/result'
@@ -11,19 +12,66 @@ module Dry
     #
     # @api public
     class Try
+      # @private
+      DEFAULT_EXCEPTIONS = [StandardError].freeze
+
+      # @return [Exception] Caught exception
       attr_reader :exception
 
-      # Calls the passed in proc object and if successful stores the result in a
-      # {Try::Value} monad, but if one of the specified exceptions was raised it stores
-      # it in a {Try::Error} monad.
-      #
-      # @param exceptions [Array<Exception>] list of exceptions to be rescued
-      # @param f [Proc] the proc to be called
-      # @return [Try::Value, Try::Error]
-      def self.lift(exceptions, f)
-        Value.new(exceptions, f.call)
-      rescue *exceptions => e
-        Error.new(e)
+      class << self
+        extend Dry::Core::Deprecations[:'dry-monads']
+
+        # Invokes a callable and if successful stores the result in the
+        # {Try::Value} type, but if one of the specified exceptions was raised it stores
+        # it in a {Try::Error}.
+        #
+        # @param exceptions [Array<Exception>] list of exceptions to rescue
+        # @param f [#call] callable object
+        # @return [Try::Value, Try::Error]
+        def run(exceptions, f)
+          Value.new(exceptions, f.call)
+        rescue *exceptions => e
+          Error.new(e)
+        end
+        deprecate :lift, :run
+
+        # Wraps a value with Value
+        #
+        # @overload pure(value, exceptions = DEFAULT_EXCEPTIONS)
+        #   @param value [Object] value for wrapping
+        #   @param exceptions [Array<Exceptions>] list of exceptions to rescue
+        #   @return [Try::Value]
+        #
+        # @overload pure(exceptions = DEFAULT_EXCEPTIONS, &block)
+        #   @param exceptions [Array<Exceptions>] list of exceptions to rescue
+        #   @param block [Proc] value for wrapping
+        #   @return [Try::Value]
+        #
+        def pure(value = Undefined, exceptions = DEFAULT_EXCEPTIONS, &block)
+          if value.equal?(Undefined)
+            Value.new(DEFAULT_EXCEPTIONS, block)
+          elsif block.nil?
+            Value.new(exceptions, value)
+          else
+            Value.new(value, block)
+          end
+        end
+
+        # Safely runs a block
+        #
+        # @example using Try with [] and a block (Ruby 2.5+)
+        #   include Dry::Monads::Try::Mixin
+        #
+        #   def safe_db_call
+        #     Try[DatabaseError] { db_call }
+        #   end
+        #
+        # @param exceptions [Array<Exception>]
+        # @return [Try::Value,Try::Error]
+        def [](*exceptions, &block)
+          raise ArgumentError, 'At least one exception type required' if exceptions.empty?
+          run(exceptions, block)
+        end
       end
 
       # Returns true for an instance of a {Try::Value} monad.
@@ -38,6 +86,13 @@ module Dry
       end
       alias_method :failure?, :error?
 
+      # Returns self.
+      #
+      # @return [Maybe::Some, Maybe::None]
+      def to_monad
+        self
+      end
+
       # Represents a result of a successful execution.
       #
       # @api public
@@ -45,6 +100,7 @@ module Dry
         include Dry::Equalizer(:value!, :catchable)
         include RightBiased::Right
 
+        # @private
         attr_reader :catchable
 
         # @param exceptions [Array<Exception>] list of exceptions to be rescued
@@ -104,9 +160,8 @@ module Dry
 
         # @return [Result::Success]
         def to_result
-          Dry::Monads::Success(@value)
+          Dry::Monads::Result::Success.new(@value)
         end
-        alias_method :to_either, :to_result
 
         # @return [String]
         def to_s
@@ -129,14 +184,13 @@ module Dry
 
         # @return [Maybe::None]
         def to_maybe
-          Dry::Monads::None()
+          Maybe::None.new(RightBiased::Left.trace_caller)
         end
 
         # @return [Result::Failure]
         def to_result
-          Dry::Monads::Failure(exception)
+          Result::Failure.new(exception, RightBiased::Left.trace_caller)
         end
-        alias_method :to_either, :to_result
 
         # @return [String]
         def to_s
@@ -185,37 +239,55 @@ module Dry
       #   Foo.new(10, 2).average # => 5
       #   Foo.new(10, 0).average # => nil
       module Mixin
+        # @see Dry::Monads::Try
         Try = Try
 
-        DEFAULT_EXCEPTIONS = [StandardError].freeze
-
-        # A convenience wrapper for {Monads::Try.lift}.
-        # If no exceptions are provided it falls back to StandardError.
-        # In general, relying on this behaviour is not recommended as it can lead to unnoticed
-        # bugs and it is always better to explicitly specify a list of exceptions if possible.
-        #
-        # @param exceptions [Array<Exception>]
-        def Try(*exceptions, &f)
-          catchable = exceptions.empty? ? DEFAULT_EXCEPTIONS : exceptions.flatten
-          Try.lift(catchable, f)
+        module Constructors
+          # A convenience wrapper for {Monads::Try.run}.
+          # If no exceptions are provided it falls back to StandardError.
+          # In general, relying on this behaviour is not recommended as it can lead to unnoticed
+          # bugs and it is always better to explicitly specify a list of exceptions if possible.
+          #
+          # @param exceptions [Array<Exception>]
+          # @return [Try]
+          def Try(*exceptions, &f)
+            catchable = exceptions.empty? ? Try::DEFAULT_EXCEPTIONS : exceptions.flatten
+            Try.run(catchable, f)
+          end
         end
 
+        include Constructors
+
+        # Value constructor
+        #
+        # @overload Value(value)
+        #   @param value [Object]
+        #   @return [Try::Value]
+        #
+        # @overload Value(&block)
+        #   @param block [Proc] a block to be wrapped with Value
+        #   @return [Try::Value]
+        #
         def Value(value = Undefined, exceptions = DEFAULT_EXCEPTIONS, &block)
-          if value.equal?(Undefined)
-            raise ArgumentError, 'No value given' if block.nil?
-            Try::Value.new(exceptions, block)
-          else
-            Try::Value.new(exceptions, value)
-          end
+          v = Undefined.default(value, block)
+          raise ArgumentError, 'No value given' if !value.nil? && v.nil?
+          Value.new(exceptions, v)
         end
 
+        # Error constructor
+        #
+        # @overload Error(value)
+        #   @param error [Exception]
+        #   @return [Try::Error]
+        #
+        # @overload Error(&block)
+        #   @param block [Proc] a block to be wrapped with Error
+        #   @return [Try::Error]
+        #
         def Error(error = Undefined, &block)
-          if error.equal?(Undefined)
-            raise ArgumentError, 'No value given' if block.nil?
-            Try::Error.new(block)
-          else
-            Try::Error.new(error)
-          end
+          v = Undefined.default(error, block)
+          raise ArgumentError, 'No value given' if v.nil?
+          Try::Error.new(v)
         end
       end
     end

data/lib/dry/monads/validated.rb

@@ -0,0 +1,283 @@
+require 'dry/monads/maybe'
+require 'dry/monads/result'
+
+module Dry
+  module Monads
+    # Validated is similar to Result and represents an outcome of a validation.
+    # The difference between Validated and Result is that the former implements
+    # `#apply` in a way that concatenates errors. This means that the error type
+    # has to have `+` implemented (be a semigroup). This plays nice with arrays and lists.
+    # Also, List<Validated>#traverse implicitly uses a block that wraps errors with
+    # a list so that you don't have to do it manually.
+    #
+    # @example using with List
+    #   List::Validated[Valid('London'), Invalid(:name_missing), Invalid(:email_missing)]
+    #   # => Invalid(List[:name_missing, :email_missing])
+    #
+    # @example with valid results
+    #   List::Validated[Valid('London'), Valid('John')]
+    #   # => Valid(List['London', 'John'])
+    #
+    class Validated
+      class << self
+        # Wraps a value with `Valid`.
+        #
+        # @overload pure(value)
+        #   @param value [Object] value to be wrapped with Valid
+        #   @return [Validated::Valid]
+        #
+        # @overload pure(&block)
+        #   @param block [Object] block to be wrapped with Valid
+        #   @return [Validated::Valid]
+        #
+        def pure(value = Undefined, &block)
+          Valid.new(Undefined.default(value, block))
+        end
+      end
+
+      # Returns self.
+      #
+      # @return [Validated::Valid, Validated::Invalid]
+      def to_monad
+        self
+      end
+
+      # Bind/flat_map is not implemented
+      #
+      def bind(*)
+        # See https://typelevel.org/cats/datatypes/validated.html for details on why
+        raise NotImplementedError, "Validated is not a monad because it would violate the monad laws"
+      end
+
+      # Valid result
+      #
+      class Valid < Validated
+        include Dry::Equalizer(:value!)
+
+        def initialize(value)
+          @value = value
+        end
+
+        # Extracts the value
+        #
+        # @return [Object]
+        def value!
+          @value
+        end
+
+        # Applies another Valid to the stored function
+        #
+        # @overload apply(val)
+        #   @example
+        #     Validated.pure { |x| x + 1 }.apply(Valid(2)) # => Valid(3)
+        #
+        #   @param val [Validated::Valid,Validated::Invalid]
+        #   @return [Validated::Valid,Validated::Invalid]
+        #
+        # @overload apply
+        #   @example
+        #     Validated.pure { |x| x + 1 }.apply { Valid(4) } # => Valid(5)
+        #
+        #   @yieldreturn [Validated::Valid,Validated::Invalid]
+        #   @return [Validated::Valid,Validated::Invalid]
+        #
+        # @return [Validated::Valid]
+        def apply(val = Undefined)
+          Undefined.default(val) { yield }.fmap(Curry.(value!))
+        end
+
+        # Lifts a block/proc over Valid
+        #
+        # @overload fmap(proc)
+        #   @param proc [#call]
+        #   @return [Validated::Valid]
+        #
+        # @overload fmap
+        #   @param block [Proc]
+        #   @return [Validated::Valid]
+        #
+        def fmap(proc = Undefined, &block)
+          f = Undefined.default(proc, block)
+          self.class.new(f.(value!))
+        end
+
+        # Ignores values and returns self, see {Invalid#alt_map}
+        #
+        # @return [Validated::Valid]
+        def alt_map(_ = nil)
+          self
+        end
+
+        # Ignores arguments, returns self
+        #
+        # @return [Validated::Valid]
+        def or(_ = nil)
+          self
+        end
+
+        # @return [String]
+        def inspect
+          "Valid(#{ value!.inspect })"
+        end
+        alias_method :to_s, :inspect
+
+        # Converts to Maybe::Some
+        #
+        # @return [Maybe::Some]
+        def to_maybe
+          Maybe.pure(value!)
+        end
+
+        # Converts to Result::Success
+        #
+        # @return [Result::Success]
+        def to_result
+          Result.pure(value!)
+        end
+      end
+
+      # Invalid result
+      #
+      class Invalid < Validated
+        # The value stored inside
+        #
+        # @return [Object]
+        attr_reader :error
+
+        # Line where the value was constructed
+        #
+        # @return [String]
+        # @api public
+        attr_reader :trace
+
+        include Dry::Equalizer(:error)
+
+        def initialize(error, trace = RightBiased::Left.trace_caller)
+          @error = error
+          @trace = trace
+        end
+
+        # Collects errors (ignores valid results)
+        #
+        # @overload apply(val)
+        #   @param val [Validated::Valid,Validated::Invalid]
+        #   @return [Validated::Invalid]
+        #
+        # @overload apply
+        #   @yieldreturn [Validated::Valid,Validated::Invalid]
+        #   @return [Validated::Invalid]
+        #
+        def apply(val = Undefined)
+          Undefined.default(val) { yield }.alt_map { |v| @error + v }
+        end
+
+        # Lifts a block/proc over Invalid
+        #
+        # @overload alt_map(proc)
+        #   @param proc [#call]
+        #   @return [Validated::Invalid]
+        #
+        # @overload alt_map
+        #   @param block [Proc]
+        #   @return [Validated::Invalid]
+        #
+        def alt_map(proc = Undefined, &block)
+          f = Undefined.default(proc, block)
+          self.class.new(f.(error), RightBiased::Left.trace_caller)
+        end
+
+        # Ignores the passed argument and returns self
+        #
+        # @return [Validated::Invalid]
+        def fmap(_ = nil)
+          self
+        end
+
+        # Yields the given callable and returns the result
+        #
+        # @overload or(proc)
+        #   @param proc [#call]
+        #   @return [Object]
+        #
+        # @overload or
+        #   @param block [Proc]
+        #   @return [Object]
+        #
+        def or(proc = Undefined, &block)
+          Undefined.default(proc, block).call
+        end
+
+        # @return [String]
+        def inspect
+          "Invalid(#{ @error.inspect })"
+        end
+        alias_method :to_s, :inspect
+
+        # Converts to Maybe::None
+        #
+        # @return [Maybe::None]
+        def to_maybe
+          Maybe::None.new(RightBiased::Left.trace_caller)
+        end
+
+        # Concerts to Result::Failure
+        #
+        # @return [Result::Failure]
+        def to_result
+          Result::Failure.new(error, RightBiased::Left.trace_caller)
+        end
+      end
+
+      # Mixin with Validated constructors
+      #
+      module Mixin
+
+        # Successful validation result
+        # @see Dry::Monads::Validated::Valid
+        Valid = Valid
+
+        # Unsuccessful validation result
+        # @see Dry::Monads::Validated::Invalid
+        Invalid = Invalid
+
+        # Actual constructor methods
+        #
+        module Constructors
+          # Valid constructor
+          #
+          # @overload Valid(value)
+          #   @param value [Object]
+          #   @return [Valdated::Valid]
+          #
+          # @overload Valid(&block)
+          #   @param block [Proc]
+          #   @return [Valdated::Valid]
+          #
+          def Valid(value = Undefined, &block)
+            v = Undefined.default(value, block)
+            raise ArgumentError, 'No value given' if !value.nil? && v.nil?
+            Valid.new(v)
+          end
+
+          # Invalid constructor
+          #
+          # @overload Invalid(value)
+          #   @param value [Object]
+          #   @return [Valdated::Invalid]
+          #
+          # @overload Invalid(&block)
+          #   @param block [Proc]
+          #   @return [Valdated::Invalid]
+          #
+          def Invalid(value = Undefined, &block)
+            v = Undefined.default(value, block)
+            raise ArgumentError, 'No value given' if !value.nil? && v.nil?
+            Invalid.new(v, RightBiased::Left.trace_caller)
+          end
+        end
+
+        include Constructors
+      end
+    end
+  end
+end