dry-monads 1.3.5 → 1.4.0

data/lib/dry/monads/list.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
-require 'dry/equalizer'
+require "dry/core/equalizer"
 
-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'
+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
@@ -83,7 +83,7 @@ module Dry
         end
       end
 
-      extend Dry::Core::Deprecations[:'dry-monads']
+      extend Dry::Core::Deprecations[:"dry-monads"]
 
       include Dry::Equalizer(:value, :type)
       include Transformer
@@ -136,14 +136,14 @@ module Dry
       end
 
       # Maps a block over the list. Acts as `Array#map`.
-      # Note that this method returns an Array instance, not a List
+      # If called without a block, this method returns an enumerator, not a List
       #
       # @return [List,Enumerator]
       def map(&block)
-        if block
+        if block_given?
           fmap(block)
         else
-          value.map(&block)
+          value.map
         end
       end
 
@@ -165,7 +165,7 @@ module Dry
       #
       # @return [String]
       def inspect
-        type_ann = typed? ? "<#{type.name.split('::').last}>" : ''
+        type_ann = typed? ? "<#{type.name.split("::").last}>" : ""
         "List#{type_ann}#{value.inspect}"
       end
       alias_method :to_s, :inspect
@@ -192,8 +192,8 @@ module Dry
       #
       # @param initial [Object] Initial value
       # @return [Object]
-      def fold_left(initial)
-        value.reduce(initial) { |acc, v| yield(acc, v) }
+      def fold_left(initial, &block)
+        value.reduce(initial, &block)
       end
       alias_method :foldl, :fold_left
       alias_method :reduce, :fold_left
@@ -224,8 +224,8 @@ module Dry
       # Filters elements with a block
       #
       # @return [List]
-      def filter
-        coerce(value.select { |e| yield(e) })
+      def filter(&block)
+        coerce(value.select(&block))
       end
       alias_method :select, :filter
 
@@ -265,10 +265,10 @@ module Dry
       def typed(type = nil)
         if type.nil?
           if size.zero?
-            raise ArgumentError, 'Cannot infer a 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 '\
+              "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)} }}"
             )
@@ -298,7 +298,7 @@ module Dry
       # @return [Monad] Result is a monadic value
       def traverse(proc = nil, &block)
         unless typed?
-          raise StandardError, 'Cannot traverse an untyped list'
+          raise StandardError, "Cannot traverse an untyped list"
         end
 
         cons = type.pure { |list, i| list + List.pure(i) }
@@ -315,8 +315,8 @@ module Dry
       #
       # @param list [List]
       # @return [List]
-      def apply(list = Undefined)
-        v = Undefined.default(list) { yield }
+      def apply(list = Undefined, &block)
+        v = Undefined.default(list, &block)
         fmap(Curry).bind { |f| v.fmap { |x| f.(x) } }
       end
 
@@ -329,7 +329,7 @@ module Dry
 
       # Returns self.
       #
-      # @return [Result::Success, Result::Failure]
+      # @return [List]
       def to_monad
         self
       end
@@ -345,7 +345,7 @@ module Dry
       #       Some(n / divisor)
       #     end
       #   end
-      #   # => List[4, 2]
+      #   # => List[2, 4]
       #
       # @example without block
       #   List[Some(5), None(), Some(3)].collect.map { |x| x * 2 }
@@ -422,10 +422,10 @@ module Dry
       # List of results
       Result = ListBuilder[Result]
 
-      # List of results
+      # List of maybes
       Maybe = ListBuilder[Maybe]
 
-      # List of results
+      # List of tries
       Try = ListBuilder[Try]
 
       # List of validation results
@@ -449,9 +449,9 @@ module Dry
       end
     end
 
-    require 'dry/monads/registry'
+    require "dry/monads/registry"
     register_mixin(:list, List::Mixin)
   end
 end
 
-require 'dry/monads/traverse'
+require "dry/monads/traverse"

data/lib/dry/monads/maybe.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
-require 'dry/equalizer'
-require 'dry/core/deprecations'
+require "dry/core/equalizer"
+require "dry/core/deprecations"
+require "dry/core/class_attributes"
 
-require 'dry/monads/right_biased'
-require 'dry/monads/transformer'
-require 'dry/monads/unit'
-require 'dry/monads/constants'
+require "dry/monads/right_biased"
+require "dry/monads/transformer"
+require "dry/monads/unit"
+require "dry/monads/constants"
 
 module Dry
   module Monads
@@ -15,9 +16,13 @@ module Dry
     # @api public
     class Maybe
       include Transformer
+      extend Core::ClassAttributes
+
+      defines :warn_on_implicit_nil_coercion
+      warn_on_implicit_nil_coercion true
 
       class << self
-        extend Core::Deprecations[:'dry-monads']
+        extend Core::Deprecations[:"dry-monads"]
 
         # Wraps the given value with into a Maybe object.
         #
@@ -105,7 +110,9 @@ module Dry
         end
 
         def initialize(value = Undefined)
-          raise ArgumentError, 'nil cannot be some' if value.nil?
+          raise ArgumentError, "nil cannot be some" if value.nil?
+
+          super()
 
           @value = Undefined.default(value, Unit)
         end
@@ -121,14 +128,65 @@ module Dry
         # @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)
+          next_value = bind(*args, &block)
+
+          if next_value.nil?
+            if self.class.warn_on_implicit_nil_coercion
+              Core::Deprecations.warn(
+                "Block passed to Some#fmap returned `nil` and was chained to None. "\
+                "This is literally an unlawful behavior and it will not be supported in "\
+                "dry-monads 2. \nPlease, replace `.fmap` with `.maybe` in places where you "\
+                "expect `nil` as block result.\n"\
+                "You can opt out of these warnings with\n"\
+                "Dry::Monads::Maybe.warn_on_implicit_nil_coercion false",
+                uplevel: 0,
+                tag: :'dry-monads'
+              )
+            end
+            Monads.None()
+          else
+            Some.new(next_value)
+          end
+        end
+
+        # Does the same thing as #bind except it also wraps the value
+        # in an instance of the Maybe monad. This allows for easier
+        # chaining of calls.
+        #
+        # @example
+        #   Dry::Monads.Some(4).maybe(&:succ).maybe(->(n) { n**2 }) # => Some(25)
+        #   Dry::Monads.Some(4).maybe(&:succ).maybe(->(_) { nil }) # => None()
+        #
+        # @param args [Array<Object>] arguments will be transparently passed through to #bind
+        # @return [Maybe::Some, Maybe::None] Wrapped result, i.e. nil will be mapped to None,
+        #                                    other values will be wrapped with Some
+        def maybe(*args, &block)
           Maybe.coerce(bind(*args, &block))
         end
-        alias_method :maybe, :fmap
+
+        # Accepts a block and runs it against the wrapped value.
+        # If the block returns a trurhy value the result is self,
+        # otherwise None. If no block is given, the value serves
+        # and its result.
+        #
+        # @param with [#call] positional block
+        # @param block [Proc] block
+        #
+        # @return [Maybe::None, Maybe::Some]
+        def filter(with = Undefined, &block)
+          block = Undefined.default(with, block || IDENTITY)
+
+          if block.(@value)
+            self
+          else
+            Monads.None()
+          end
+        end
 
         # @return [String]
         def to_s
           if Unit.equal?(@value)
-            'Some()'
+            "Some()"
           else
             "Some(#{@value.inspect})"
           end
@@ -146,7 +204,7 @@ module Dry
         singleton_class.send(:attr_reader, :instance)
 
         # @api private
-        def self.method_missing(m, *)
+        def self.method_missing(m, *) # rubocop:disable Style/MissingRespondToMissing
           if (instance.methods(true) - methods(true)).include?(m)
             raise ConstructorNotAppliedError.new(m, :None)
           else
@@ -161,6 +219,7 @@ module Dry
         attr_reader :trace
 
         def initialize(trace = RightBiased::Left.trace_caller)
+          super()
           @trace = trace
         end
 
@@ -202,7 +261,7 @@ module Dry
 
         # @return [String]
         def to_s
-          'None'
+          "None"
         end
         alias_method :inspect, :to_s
 
@@ -230,6 +289,13 @@ module Dry
         def deconstruct
           EMPTY_ARRAY
         end
+
+        # @see Maybe::Some#filter
+        #
+        # @return [Maybe::None]
+        def filter(_ = Undefined)
+          self
+        end
       end
 
       # A module that can be included for easier access to Maybe monads.
@@ -301,9 +367,9 @@ module Dry
         # None values are removed
         #
         # @example
-        #   Maybe::Hash.filter(foo: Some(1), bar: Some(2)) # => Some(foo: 1, bar: 2)
-        #   Maybe::Hash.filter(foo: Some(1), bar: None())  # => None()
-        #   Maybe::Hash.filter(foo: None(), bar: Some(2))  # => None()
+        #   Maybe::Hash.filter(foo: Some(1), bar: Some(2)) # => { foo: 1, bar: 2 }
+        #   Maybe::Hash.filter(foo: Some(1), bar: None())  # => { foo: 1 }
+        #   Maybe::Hash.filter(foo: None(), bar: Some(2))  # => { bar: 2 }
         #
         # @param hash [::Hash<Object,Maybe>]
         # @return [::Hash]
@@ -325,10 +391,12 @@ module Dry
 
     class Result
       class Success < Result
-        # @return [Maybe::Some]
+        extend Core::Deprecations[:"dry-monads"]
+
+        # @return [Maybe]
         def to_maybe
-          Kernel.warn 'Success(nil) transformed to None' if @value.nil?
-          Dry::Monads::Maybe(@value)
+          warn "Success(nil) transformed to None" if @value.nil?
+          ::Dry::Monads::Maybe(@value)
         end
       end
 
@@ -389,7 +457,7 @@ module Dry
       end
     end
 
-    require 'dry/monads/registry'
+    require "dry/monads/registry"
     register_mixin(:maybe, Maybe::Mixin)
   end
 end

data/lib/dry/monads/registry.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'concurrent/map'
+require "concurrent/map"
 
 module Dry
   # Common, idiomatic monads for Ruby
@@ -10,16 +10,16 @@ module Dry
     @registry = {}
     @constructors = nil
     @paths = {
-      do: 'dry/monads/do/all',
-      lazy: 'dry/monads/lazy',
-      list: 'dry/monads/list',
-      maybe: 'dry/monads/maybe',
-      task: 'dry/monads/task',
-      try: 'dry/monads/try',
-      validated: 'dry/monads/validated',
+      do: "dry/monads/do/all",
+      lazy: "dry/monads/lazy",
+      list: "dry/monads/list",
+      maybe: "dry/monads/maybe",
+      task: "dry/monads/task",
+      try: "dry/monads/try",
+      validated: "dry/monads/validated",
       result: [
-        'dry/monads/result',
-        'dry/monads/result/fixed'
+        "dry/monads/result",
+        "dry/monads/result/fixed"
       ]
     }.freeze
     @mixins = Concurrent::Map.new

data/lib/dry/monads/result.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-require 'dry/equalizer'
+require "dry/core/equalizer"
 
-require 'dry/monads/constants'
-require 'dry/monads/right_biased'
-require 'dry/monads/transformer'
-require 'dry/monads/conversion_stubs'
-require 'dry/monads/unit'
+require "dry/monads/constants"
+require "dry/monads/right_biased"
+require "dry/monads/transformer"
+require "dry/monads/conversion_stubs"
+require "dry/monads/unit"
 
 module Dry
   module Monads
@@ -86,6 +86,7 @@ module Dry
 
         # @param value [Object] a value of a successful operation
         def initialize(value)
+          super()
           @value = value
         end
 
@@ -134,7 +135,7 @@ module Dry
         # @return [String]
         def to_s
           if Unit.equal?(@value)
-            'Success()'
+            "Success()"
           else
             "Success(#{@value.inspect})"
           end
@@ -147,6 +148,13 @@ module Dry
         def flip
           Failure.new(@value, RightBiased::Left.trace_caller)
         end
+
+        # Ignores values and returns self, see {Failure#alt_map}
+        #
+        # @return [Result::Success]
+        def alt_map(_ = nil)
+          self
+        end
       end
 
       # Represents a value of a failed operation.
@@ -188,6 +196,7 @@ module Dry
         # @param value [Object] failure value
         # @param trace [String] caller line
         def initialize(value, trace = RightBiased::Left.trace_caller)
+          super()
           @value = value
           @trace = trace
         end
@@ -218,7 +227,8 @@ module Dry
         # otherwise simply returns the first argument.
         #
         # @example
-        #   Dry::Monads.Failure(ArgumentError.new('error message')).or(&:message) # => "error message"
+        #   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
@@ -232,7 +242,8 @@ module Dry
           end
         end
 
-        # A lifted version of `#or`. Wraps the passed value or the block result with Result::Success.
+        # 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")
@@ -247,7 +258,7 @@ module Dry
         # @return [String]
         def to_s
           if Unit.equal?(@value)
-            'Failure()'
+            "Failure()"
           else
             "Failure(#{@value.inspect})"
           end
@@ -287,6 +298,21 @@ module Dry
         def either(_, g)
           g.(failure)
         end
+
+        # Lifts a block/proc over Failure
+        #
+        # @overload alt_map(proc)
+        #   @param proc [#call]
+        #   @return [Result::Failure]
+        #
+        # @overload alt_map
+        #   @param block [Proc]
+        #   @return [Result::Failure]
+        #
+        def alt_map(proc = Undefined, &block)
+          f = Undefined.default(proc, block)
+          self.class.new(f.(failure), RightBiased::Left.trace_caller)
+        end
       end
 
       # A module that can be included for easier access to Result monads.
@@ -448,7 +474,7 @@ module Dry
       end
 
       class Invalid < Validated
-        # Concerts to Result::Failure
+        # Converts to Result::Failure
         #
         # @return [Result::Failure]
         def to_result
@@ -457,7 +483,7 @@ module Dry
       end
     end
 
-    require 'dry/monads/registry'
+    require "dry/monads/registry"
     register_mixin(:result, Result::Mixin)
   end
 end