dry-monads 0.3.1 → 0.4.0

data/lib/dry/monads/errors.rb

@@ -0,0 +1,15 @@
+module Dry
+  module Monads
+    class UnwrapError < StandardError
+      def initialize(ctx)
+        super("value! was called on #{ ctx.inspect }")
+      end
+    end
+
+    class InvalidFailureTypeError < StandardError
+      def initialize(failure)
+        super("Cannot create Failure from #{ failure.inspect }, it doesn't meet constraints")
+      end
+    end
+  end
+end

data/lib/dry/monads/list.rb

@@ -25,7 +25,7 @@ module Dry
           elsif value.respond_to?(:to_ary)
             List.new(value.to_ary, type)
           else
-            raise ArgumentError, "Can't coerce #{value.inspect} to List"
+            raise TypeError, "Can't coerce #{value.inspect} to List"
           end
         end
 
@@ -89,14 +89,14 @@ module Dry
       end
 
       # Maps a block over the list. Acts as `Array#map`.
-      # Requires a block.
+      # Note that this method returns an Array instance, not a List
       #
-      # @return [List]
+      # @return [List,Enumerator]
       def map(&block)
         if block
           fmap(block)
         else
-          raise ArgumentError, "Missing block"
+          value.map(&block)
         end
       end
 
@@ -118,7 +118,8 @@ module Dry
       #
       # @return [String]
       def inspect
-        "List#{ value.inspect }"
+        type_ann = typed? ? "<#{ type.name.split('::').last }>" : ''
+        "List#{ type_ann }#{ value.inspect }"
       end
       alias_method :to_s, :inspect
 
@@ -235,11 +236,11 @@ module Dry
 
       # Traverses the list with a block (or without it).
       # This methods "flips" List structure with the given monad (obtained from the type).
-      # Note that traversing requires the list to be types.
+      # Note that traversing requires the list to be typed.
       # Also if a block given, its returning type must be equal list's type.
       #
       # @example
-      #   List<Either>[Right(1), Right(2)].traverse # => Right([1, 2])
+      #   List<Result>[Success(1), Success(2)].traverse # => Success([1, 2])
       #   List<Maybe>[Some(1), None, Some(3)].traverse # => None
       #
       # @return [Monad] Result is a monadic value

data/lib/dry/monads/maybe.rb

@@ -1,4 +1,6 @@
 require 'dry/equalizer'
+require 'dry/core/deprecations'
+require 'dry/core/constants'
 
 require 'dry/monads/right_biased'
 require 'dry/monads/transformer'
@@ -9,9 +11,10 @@ module Dry
     #
     # @api public
     class Maybe
-      include Dry::Equalizer(:value)
       include Transformer
 
+      extend Dry::Core::Deprecations[:'dry-monads']
+
       class << self
         # Wraps the given value with into a Maybe object.
         #
@@ -39,11 +42,13 @@ module Dry
       def none?
         is_a?(None)
       end
+      alias_method :failure?, :none?
 
       # Returns true for an instance of a {Maybe::Some} monad.
       def some?
         is_a?(Some)
       end
+      alias_method :success?, :some?
 
       # Returns self, added to keep the interface compatible with that of Either monad types.
       #
@@ -64,10 +69,9 @@ module Dry
       #
       # @api public
       class Some < Maybe
+        include Dry::Equalizer(:value!)
         include RightBiased::Right
 
-        attr_reader :value
-
         def initialize(value)
           raise ArgumentError, 'nil cannot be some' if value.nil?
           @value = value
@@ -89,9 +93,9 @@ module Dry
 
         # @return [String]
         def to_s
-          "Some(#{value.inspect})"
+          "Some(#{ @value.inspect })"
         end
-        alias inspect to_s
+        alias_method :inspect, :to_s
       end
 
       # Represents an absence of a value, i.e. the value nil.
@@ -100,14 +104,9 @@ module Dry
       class None < Maybe
         include RightBiased::Left
 
-        @instance = new
+        @instance = new.freeze
         singleton_class.send(:attr_reader, :instance)
 
-        # @return [nil]
-        def value
-          nil
-        end
-
         # If a block is given passes internal value to it and returns the result,
         # otherwise simply returns the parameter val.
         #
@@ -144,7 +143,18 @@ module Dry
         def to_s
           'None'
         end
-        alias inspect to_s
+        alias_method :inspect, :to_s
+
+        # @api private
+        def eql?(other)
+          other.is_a?(None)
+        end
+        alias_method :==, :eql?
+
+        # @api private
+        def hash
+          None.instance.object_id
+        end
       end
 
       # A module that can be included for easier access to Maybe monads.
@@ -153,22 +163,31 @@ module Dry
         Some = Some
         None = None
 
-        # @param value [Object] the value to be stored in the monad
-        # @return [Maybe::Some, Maybe::None]
-        def Maybe(value)
-          Maybe.lift(value)
-        end
+        module Constructors
+          # @param value [Object] the value to be stored in the monad
+          # @return [Maybe::Some, Maybe::None]
+          def Maybe(value)
+            Maybe.lift(value)
+          end
 
-        # @param value [Object] the value to be stored in the monad
-        # @return [Maybe::Some]
-        def Some(value)
-          Some.new(value)
-        end
+          # @param value [Object] the value to be stored in the monad
+          # @return [Maybe::Some]
+          def Some(value = Dry::Core::Constants::Undefined, &block)
+            if value.equal?(Dry::Core::Constants::Undefined)
+              raise ArgumentError, 'No value given' if block.nil?
+              Some.new(block)
+            else
+              Some.new(value)
+            end
+          end
 
-        # @return [Maybe::None]
-        def None
-          None.instance
+          # @return [Maybe::None]
+          def None
+            None.instance
+          end
         end
+
+        include Constructors
       end
     end
   end

data/lib/dry/monads/result.rb

@@ -0,0 +1,250 @@
+require 'dry/equalizer'
+require 'dry/core/constants'
+
+require 'dry/monads/right_biased'
+require 'dry/monads/transformer'
+require 'dry/monads/maybe'
+
+module Dry
+  module Monads
+    # Represents an operation which either succeeded or failed.
+    #
+    # @api public
+    class Result
+      include Transformer
+
+      attr_reader :success, :failure
+
+      class << self
+        # Wraps the given value with Success
+        #
+        # @param value [Object] the value to be stored inside Success
+        # @return [Result::Success]
+        def pure(value)
+          Success.new(value)
+        end
+      end
+
+      # Returns self, added to keep the interface compatible with other monads.
+      #
+      # @return [Result::Success, Result::Failure]
+      def to_result
+        self
+      end
+      alias_method :to_either, :to_result
+
+      # Returns the Result monad.
+      # This is how we're doing polymorphism in Ruby 😕
+      #
+      # @return [Monad]
+      def monad
+        Result
+      end
+
+      # Represents a value of a successful operation.
+      #
+      # @api public
+      class Success < Result
+        include RightBiased::Right
+        include Dry::Equalizer(:value!)
+
+        alias_method :success, :value!
+
+        # @param value [Object] a value of a successful operation
+        def initialize(value)
+          @value = value
+        end
+
+        # Apply the second function to value.
+        #
+        # @api public
+        def result(_, f)
+          f.(@value)
+        end
+
+        # Returns false
+        def failure?
+          false
+        end
+        alias_method :left?, :failure?
+
+        # Returns true
+        def success?
+          true
+        end
+        alias_method :right?, :success?
+
+        # Does the same thing as #bind except it also wraps the value
+        # in an instance of Result::Success monad. This allows for easier
+        # chaining of calls.
+        #
+        # @example
+        #   Dry::Monads.Success(4).fmap(&:succ).fmap(->(n) { n**2 }) # => Success(25)
+        #
+        # @param args [Array<Object>] arguments will be transparently passed through to #bind
+        # @return [Result::Success]
+        def fmap(*args, &block)
+          Success.new(bind(*args, &block))
+        end
+
+        # @return [String]
+        def to_s
+          "Success(#{ @value.inspect })"
+        end
+        alias_method :inspect, :to_s
+
+        # @return [Maybe::Some]
+        def to_maybe
+          Kernel.warn 'Success(nil) transformed to None' if @value.nil?
+          Dry::Monads::Maybe(@value)
+        end
+
+        # Transform to a Failure instance
+        #
+        # @return [Result::Failure]
+        def flip
+          Failure.new(@value)
+        end
+      end
+
+      # Represents a value of a failed operation.
+      #
+      # @api public
+      class Failure < Result
+        include RightBiased::Left
+        include Dry::Equalizer(:failure)
+
+        # @api private
+        def failure
+          @value
+        end
+        alias_method :left, :failure
+
+        # @param value [Object] a value in an error state
+        def initialize(value)
+          @value = value
+        end
+
+        # Apply the first function to value.
+        #
+        # @api public
+        def result(f, _)
+          f.(@value)
+        end
+
+        # Returns true
+        def failure?
+          true
+        end
+        alias_method :left?, :failure?
+
+        # Returns false
+        def success?
+          false
+        end
+        alias_method :right?, :success?
+
+        # If a block is given passes internal value to it and returns the result,
+        # otherwise simply returns the first argument.
+        #
+        # @example
+        #   Dry::Monads.Failure(ArgumentError.new('error message')).or(&:message) # => "error message"
+        #
+        # @param args [Array<Object>] arguments that will be passed to a block
+        #                             if one was given, otherwise the first
+        #                             value will be returned
+        # @return [Object]
+        def or(*args)
+          if block_given?
+            yield(@value, *args)
+          else
+            args[0]
+          end
+        end
+
+        # A lifted version of `#or`. Wraps the passed value or the block result with Result::Success.
+        #
+        # @example
+        #   Dry::Monads.Failure.new('no value').or_fmap('value') # => Success("value")
+        #   Dry::Monads.Failure.new('no value').or_fmap { 'value' } # => Success("value")
+        #
+        # @param args [Array<Object>] arguments will be passed to the underlying `#or` call
+        # @return [Result::Success] Wrapped value
+        def or_fmap(*args, &block)
+          Success.new(self.or(*args, &block))
+        end
+
+        # @return [String]
+        def to_s
+          "Failure(#{ @value.inspect })"
+        end
+        alias_method :inspect, :to_s
+
+        # @return [Maybe::None]
+        def to_maybe
+          Maybe::None.instance
+        end
+
+        # Transform to a Success instance
+        #
+        # @return [Result::Success]
+        def flip
+          Success.new(@value)
+        end
+
+        # @see Dry::Monads::RightBiased::Left#value_or
+        def value_or(val = nil)
+          if block_given?
+            yield(@value)
+          else
+            val
+          end
+        end
+
+        # @param other [Result]
+        # @return [Boolean]
+        def ===(other)
+          Failure === other && failure === other.failure
+        end
+      end
+
+      # A module that can be included for easier access to Result monads.
+      module Mixin
+        Success = Dry::Monads::Result::Success
+        Failure = Dry::Monads::Result::Failure
+
+        module Constructors
+          # @param value [Object] the value to be stored in the monad
+          # @return [Result::Success]
+          def Success(value = Dry::Core::Constants::Undefined, &block)
+            if value.equal?(Dry::Core::Constants::Undefined)
+              raise ArgumentError, 'No value given' if block.nil?
+              Success.new(block)
+            else
+              Success.new(value)
+            end
+          end
+          alias_method :Right, :Success
+
+          # @param value [Object] the value to be stored in the monad
+          # @return [Result::Failure]
+          def Failure(value = Dry::Core::Constants::Undefined, &block)
+            if value.equal?(Dry::Core::Constants::Undefined)
+              raise ArgumentError, 'No value given' if block.nil?
+              Failure.new(block)
+            else
+              Failure.new(value)
+            end
+          end
+          alias_method :Left, :Failure
+        end
+
+        include Constructors
+      end
+    end
+
+    Either = Result
+    Result::Right = Result::Success
+    Result::Left = Result::Failure
+  end
+end