dry-monads 0.4.0 → 1.0.0.beta1

data/lib/dry/monads/errors.rb

@@ -1,14 +1,16 @@
 module Dry
   module Monads
+    # An unsuccessful result of extracting a value from a monad.
     class UnwrapError < StandardError
       def initialize(ctx)
         super("value! was called on #{ ctx.inspect }")
       end
     end
 
+    # An error thrown on returning a Failure of unknown type.
     class InvalidFailureTypeError < StandardError
       def initialize(failure)
-        super("Cannot create Failure from #{ failure.inspect }, it doesn't meet constraints")
+        super("Cannot create Failure from #{ failure.inspect }, it doesn't meet the constraints")
       end
     end
   end

data/lib/dry/monads/lazy.rb

@@ -0,0 +1,78 @@
+require 'concurrent/promise'
+
+require 'dry/monads/task'
+
+module Dry
+  module Monads
+    # Lazy is a twin of Task which is always executed on the current thread.
+    # The underlying mechanism provided by concurrent-ruby ensures the given
+    # computation is evaluated not more than once (compare with the built-in
+    # lazy assignement ||= which does not guarantee this).
+    class Lazy < Task
+      class << self
+        # @private
+        def new(promise = nil, &block)
+          if promise
+            super(promise)
+          else
+            super(Concurrent::Promise.new(executor: :immediate, &block))
+          end
+        end
+
+        private :[]
+      end
+
+      # Forces the compution and returns its value.
+      #
+      # @return [Object]
+      def value!
+        @promise.execute.value!
+      end
+      alias_method :force!, :value!
+
+      # Forces the computation. Note that if the computation
+      # thrown an error it won't be re-raised as opposed to value!/force!.
+      #
+      # @return [Lazy]
+      def force
+        @promise.execute
+        self
+      end
+
+      # @return [String]
+      def to_s
+        state = case promise.state
+                when :fulfilled
+                  value!.inspect
+                when :rejected
+                  "!#{ promise.reason.inspect }"
+                else
+                  '?'
+                end
+
+        "Lazy(#{ state })"
+      end
+      alias_method :inspect, :to_s
+
+      # Lazy constructors
+      #
+      module Mixin
+        # @see Dry::Monads::Lazy
+        Lazy = Lazy
+
+        # Lazy constructors
+        module Constructors
+          # Lazy computation contructor
+          #
+          # @param block [Proc]
+          # @return [Lazy]
+          def Lazy(&block)
+            Lazy.new(&block)
+          end
+        end
+
+        include Constructors
+      end
+    end
+  end
+end

data/lib/dry/monads/list.rb

@@ -1,9 +1,17 @@
 require 'dry/equalizer'
+require 'dry/core/deprecations'
+
 require 'dry/monads/maybe'
+require 'dry/monads/task'
+require 'dry/monads/result'
+require 'dry/monads/try'
+require 'dry/monads/validated'
 require 'dry/monads/transformer'
+require 'dry/monads/curry'
 
 module Dry
   module Monads
+    # The List monad.
     class List
       class << self
         # Builds a list.
@@ -23,7 +31,13 @@ module Dry
           if value.nil?
             List.new([], type)
           elsif value.respond_to?(:to_ary)
-            List.new(value.to_ary, type)
+            values = value.to_ary
+
+            if !values.empty? && type.nil? && values[0].respond_to?(:monad)
+              List.new(values, values[0].monad)
+            else
+              List.new(values, type)
+            end
           else
             raise TypeError, "Can't coerce #{value.inspect} to List"
           end
@@ -33,11 +47,19 @@ module Dry
         #
         # @param value [Object] any object
         # @return [List]
-        def pure(value, type = nil)
-          new([value], type)
+        def pure(value = Undefined, type = nil, &block)
+          if value.equal?(Undefined)
+            new([block])
+          elsif block
+            new([block], value)
+          else
+            new([value], type)
+          end
         end
       end
 
+      extend Dry::Core::Deprecations[:'dry-monads']
+
       include Dry::Equalizer(:value, :type)
       include Transformer
 
@@ -200,7 +222,7 @@ module Dry
       #
       # @return [Maybe<Object>]
       def head
-        Maybe.coerce(value.first)
+        Monads::Maybe.coerce(value.first)
       end
 
       # Returns list's tail.
@@ -218,8 +240,13 @@ module Dry
       def typed(type = nil)
         if type.nil?
           if size.zero?
-            raise ArgumentError, "Cannot infer monad for an empty list"
+            raise ArgumentError, "Cannot infer a monad for an empty list"
           else
+            self.class.warn(
+              "Automatic monad inference is deprecated, pass a type explicitly "\
+              "or use a predefined constant, e.g. List::Result\n"\
+              "#{caller.find { |l| l !~ %r{(lib/dry/monads)|(gems)} }}"
+            )
             self.class.new(value, value[0].monad)
           end
         else
@@ -244,17 +271,28 @@ module Dry
       #   List<Maybe>[Some(1), None, Some(3)].traverse # => None
       #
       # @return [Monad] Result is a monadic value
-      def traverse
+      def traverse(proc = nil, &block)
         unless typed?
           raise StandardError, "Cannot traverse an untyped list"
         end
 
-        foldl(type.pure(EMPTY)) { |acc, el|
-          acc.bind { |unwrapped|
-            mapped = block_given? ? yield(el) : el
-            mapped.fmap { |i| unwrapped + List[i] }
-          }
-        }
+        cons = type.pure { |list, i| list + List.pure(i) }
+        with = proc || block || Traverse[type]
+
+        foldl(type.pure(EMPTY)) do |acc, el|
+          cons.
+            apply(acc).
+            apply { with.(el) }
+        end
+      end
+
+      # Applies the stored functions to the elements of the given list.
+      #
+      # @param list [List]
+      # @return [List]
+      def apply(list = Undefined)
+        v = Undefined.default(list) { yield }
+        fmap(Curry).bind { |f| v.fmap { |x| f.(x) } }
       end
 
       # Returns the List monad.
@@ -264,6 +302,13 @@ module Dry
         List
       end
 
+      # Returns self.
+      #
+      # @return [Result::Success, Result::Failure]
+      def to_monad
+        self
+      end
+
       private
 
       def coerce(other)
@@ -273,10 +318,60 @@ module Dry
       # Empty list
       EMPTY = List.new([].freeze).freeze
 
+      # @private
+      class ListBuilder
+        class << self
+          alias_method :[], :new
+        end
+
+        attr_reader :type
+
+        def initialize(type)
+          @type = type
+        end
+
+        def [](*args)
+          List.new(args, type)
+        end
+
+        def coerce(value)
+          List.coerce(value, type)
+        end
+
+        def pure(val = Undefined, &block)
+          value = Undefined.default(val, block)
+          List.pure(value, type)
+        end
+      end
+
+      # List of tasks
+      Task = ListBuilder[Task]
+
+      # List of results
+      Result = ListBuilder[Result]
+
+      # List of results
+      Maybe = ListBuilder[Maybe]
+
+      # List of results
+      Try = ListBuilder[Try]
+
+      # List of validation results
+      Validated = ListBuilder[Validated]
+
+      # List contructors.
+      #
+      # @api public
       module Mixin
+
+        # @see Dry::Monads::List
         List = List
+
+        # @see Dry::Monads::List
         L = List
 
+        # List constructor.
+        # @return [List]
         def List(value)
           List.coerce(value)
         end
@@ -284,3 +379,5 @@ module Dry
     end
   end
 end
+
+require 'dry/monads/traverse'

data/lib/dry/monads/maybe.rb

@@ -1,6 +1,6 @@
 require 'dry/equalizer'
-require 'dry/core/deprecations'
 require 'dry/core/constants'
+require 'dry/core/deprecations'
 
 require 'dry/monads/right_biased'
 require 'dry/monads/transformer'
@@ -13,12 +13,12 @@ module Dry
     class Maybe
       include Transformer
 
-      extend Dry::Core::Deprecations[:'dry-monads']
-
       class << self
+        extend Dry::Core::Deprecations[:'dry-monads']
+
         # Wraps the given value with into a Maybe object.
         #
-        # @param value [Object] the value to be stored in the monad
+        # @param value [Object] value to be stored in the monad
         # @return [Maybe::Some, Maybe::None]
         def coerce(value)
           if value.nil?
@@ -27,14 +27,15 @@ module Dry
             Some.new(value)
           end
         end
-        alias_method :lift, :coerce
+        deprecate :lift, :coerce
 
         # Wraps the given value with `Some`.
         #
-        # @param value [Object] the value to be stored inside Some
+        # @param value [Object] value to be wrapped with Some
+        # @param block [Object] block to be wrapped with Some
         # @return [Maybe::Some]
-        def pure(value)
-          Some.new(value)
+        def pure(value = Undefined, &block)
+          Some.new(Undefined.default(value, block))
         end
       end
 
@@ -57,6 +58,13 @@ module Dry
         self
       end
 
+      # Returns self.
+      #
+      # @return [Maybe::Some, Maybe::None]
+      def to_monad
+        self
+      end
+
       # Returns the Maybe monad.
       # This is how we're doing polymorphism in Ruby 😕
       #
@@ -85,10 +93,10 @@ module Dry
         #   Dry::Monads.Some(4).fmap(&:succ).fmap(->(n) { n**2 }) # => Some(25)
         #
         # @param args [Array<Object>] arguments will be transparently passed through to #bind
-        # @return [Maybe::Some, Maybe::None] Lifted result, i.e. nil will be mapped to None,
+        # @return [Maybe::Some, Maybe::None] Wrapped result, i.e. nil will be mapped to None,
         #                                    other values will be wrapped with Some
         def fmap(*args, &block)
-          self.class.lift(bind(*args, &block))
+          self.class.coerce(bind(*args, &block))
         end
 
         # @return [String]
@@ -107,6 +115,15 @@ module Dry
         @instance = new.freeze
         singleton_class.send(:attr_reader, :instance)
 
+        # Line where the value was constructed
+        #
+        # @return [String]
+        attr_reader :trace
+
+        def initialize(trace = RightBiased::Left.trace_caller)
+          @trace = trace
+        end
+
         # If a block is given passes internal value to it and returns the result,
         # otherwise simply returns the parameter val.
         #
@@ -125,7 +142,7 @@ module Dry
           end
         end
 
-        # A lifted version of `#or`. Applies `Maybe.lift` to the passed value or
+        # A lifted version of `#or`. Applies `Maybe.coerce` to the passed value or
         # to the block result.
         #
         # @example
@@ -136,7 +153,7 @@ module Dry
         # @return [Maybe::Some, Maybe::None] Lifted `#or` result, i.e. nil will be mapped to None,
         #                                    other values will be wrapped with Some
         def or_fmap(*args, &block)
-          Maybe.lift(self.or(*args, &block))
+          Maybe.coerce(self.or(*args, &block))
         end
 
         # @return [String]
@@ -151,7 +168,7 @@ module Dry
         end
         alias_method :==, :eql?
 
-        # @api private
+        # @private
         def hash
           None.instance.object_id
         end
@@ -159,31 +176,40 @@ module Dry
 
       # A module that can be included for easier access to Maybe monads.
       module Mixin
+        # @see Dry::Monads::Maybe
         Maybe = Maybe
+        # @see Maybe::Some
         Some = Some
+        # @see Maybe::None
         None = None
 
+        # @private
         module Constructors
           # @param value [Object] the value to be stored in the monad
           # @return [Maybe::Some, Maybe::None]
           def Maybe(value)
-            Maybe.lift(value)
+            Maybe.coerce(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
+          # Some constructor
+          #
+          # @overload Some(value)
+          #   @param value [Object] any value except `nil`
+          #   @return [Maybe::Some]
+          #
+          # @overload Some(&block)
+          #   @param block [Proc] a block to be wrapped with Some
+          #   @return [Maybe::Some]
+          #
+          def Some(value = Undefined, &block)
+            v = Undefined.default(value, block)
+            raise ArgumentError, 'No value given' if !value.nil? && v.nil?
+            Some.new(v)
           end
 
           # @return [Maybe::None]
           def None
-            None.instance
+            None.new(RightBiased::Left.trace_caller)
           end
         end