dry-monads 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 578a10e9ec2b0ca63809f588c68d14a643a43f4b
-  data.tar.gz: 8d69e82a8e58de7488aca590a7f321c978431734
+  metadata.gz: ac64c7b3b46d180bb1109ba4272763f79ffc9f57
+  data.tar.gz: a44861c02c43c629b65cbada6d3cae5fc2f56917
 SHA512:
-  metadata.gz: f2d1786620c51d8ab53e8b59099143e8867f9ac2223b155a946bee1d6b23bc5740a4623250002e33df54562c371d802977b27553f2b70ab3270b906a51a75ead
-  data.tar.gz: 46bc1e583a5fbb1e597aad4ed157757aa960abe39bf3aab92af54110f17bebf09a10a1ce2d0d4f198f0dfc0174841fd3b360275a716d95e6c45f77f64e0e3175
+  metadata.gz: e2f903e40b08f17b314f95c773b0b161c084da2df3e59d56cd570c0f104166711f7ac8091fc1901d8118cfc36590493ab08f2d950cee914d83c1fa99855f5a4d
+  data.tar.gz: ef594ee9cc4766bbe519f12d13c398b4e7c8ae8458ec7a551348e559ce2e76de23fd9fcbaf4b7cbaa85b64feac074956004b83f96ce839320a2b88f4325fedc8

data/.rubocop.yml

@@ -1,5 +1,10 @@
 inherit_from: .rubocop_todo.yml
 
+AllCops:
+  Exclude:
+    - 'spec/integration/either_spec.rb'
+    - 'vendor/**/*'
+
 Style/Documentation:
   Enabled: false
 
@@ -24,6 +29,21 @@ Style/MultilineBlockChain:
 Style/GuardClause:
   Enabled: false
 
+Style/SymbolProc:
+  Exclude:
+    # This rule is broken in specs on purpose to make examples clearer
+    - 'spec/**/*'
+
+Style/SignalException:
+  Exclude:
+    - 'spec/**/*'
+
+Style/ModuleFunction:
+  Enabled: false
+
+Style/RescueModifier:
+  Enabled: false
+
 Metrics/LineLength:
   Max: 110
 

data/.travis.yml

@@ -1,16 +1,16 @@
 language: ruby
 sudo: false
 cache: bundler
-bundler_args: --without benchmarks tools
+bundler_args: --without benchmarks
 script:
   - bundle exec rake spec
+  - bundle exec rubocop
 rvm:
-  - 2.0
-  - 2.1
-  - 2.2
-  - 2.3.0
+  - 2.1.10
+  - 2.2.5
+  - 2.3.1
   - rbx-2
-  - jruby-9000
+  - jruby-9.1.1.0
   - ruby-head
 env:
   global:

data/README.md

@@ -11,6 +11,7 @@
 [![Code Climate](https://img.shields.io/codeclimate/github/dry-rb/dry-monads.svg)][code_climate]
 [![Test Coverage](https://img.shields.io/codeclimate/coverage/github/dry-rb/dry-monads.svg)][code_climate]
 [![API Documentation Coverage](http://inch-ci.org/github/dry-rb/dry-monads.svg)][inch]
+![No monkey-patches](https://img.shields.io/badge/monkey--patches-0-brightgreen.svg)
 
 Monads for Ruby.
 
@@ -46,4 +47,4 @@ prompt that will allow you to experiment.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at [https://github.com/dry-rb/dry-monads]().
+Bug reports and pull requests are welcome on GitHub at <https://github.com/dry-rb/dry-monads>.

data/dry-monads.gemspec

@@ -25,6 +25,7 @@ Gem::Specification.new do |spec|
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
+  spec.add_dependency 'dry-equalizer'
 
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake'

data/lib/dry/monads.rb

@@ -1,27 +1,41 @@
+require 'dry/equalizer'
 require 'dry/monads/either'
 require 'dry/monads/maybe'
 require 'dry/monads/try'
 
 module Dry
+  # @api public
   module Monads
     extend self
 
+    # Stores the given value in one of the subtypes of {Maybe} monad.
+    # It is essentially a wrapper for {Maybe.lift}.
+    #
+    # @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)
       Maybe::Some.new(value)
     end
 
+    # @return [Maybe::None]
     def None
       Maybe::Some::None.instance
     end
 
+    # @param value [Object] the value to be stored in the monad
+    # @return [Either::Right]
     def Right(value)
       Either::Right.new(value)
     end
 
+    # @param value [Object] the value to be stored in the monad
+    # @return [Either::Left]
     def Left(value)
       Either::Left.new(value)
     end

data/lib/dry/monads/either.rb

@@ -1,100 +1,167 @@
 module Dry
   module Monads
+    # Represents a value which is either correct or an error.
+    #
+    # @api public
     class Either
+      include Dry::Equalizer(:right, :left)
       attr_reader :right, :left
 
-      def ==(other)
-        other.is_a?(Either) && right == other.right && left == other.left
-      end
-
+      # Returns true for an instance of a {Either::Right} monad.
       def right?
         is_a? Right
       end
       alias success? right?
 
+      # Returns true for an instance of a {Either::Left} monad.
       def left?
         is_a? Left
       end
       alias failure? left?
 
+      # Returns self, added to keep the interface compatible with other monads.
+      #
+      # @return [Either::Right, Either::Left]
       def to_either
         self
       end
 
+      # Represents a value that is in a correct state, i.e. everything went right.
+      #
+      # @api public
       class Right < Either
         alias value right
 
+        # @param right [Object] a value in a correct state
         def initialize(right)
           @right = right
         end
 
-        def bind(proc = nil)
-          if proc
-            proc.call(value)
+        # Calls the passed in Proc object with value stored in self
+        # and returns the result.
+        #
+        # If proc is nil, it expects a block to be given and will yield to it.
+        #
+        # @example
+        #   Dry::Monads.Right(4).bind(&:succ) # => 5
+        #
+        # @param [Array<Object>] args arguments that will be passed to a block
+        #                             if one was given, otherwise the first
+        #                             value assumed to be a Proc (callable)
+        #                             object and the rest of args will be passed
+        #                             to this object along with the internal value
+        # @return [Object] result of calling proc or block on the internal value
+        def bind(*args)
+          if block_given?
+            yield(value, *args)
           else
-            yield(value)
+            args[0].call(value, *args.drop(1))
           end
         end
 
-        def fmap(proc = nil, &block)
-          Right.new(bind(&(proc || block)))
+        # Does the same thing as #bind except it also wraps the value
+        # in an instance of Either::Right monad. This allows for easier
+        # chaining of calls.
+        #
+        # @example
+        #   Dry::Monads.Right(4).fmap(&:succ).fmap(->(n) { n**2 }) # => Right(25)
+        #
+        # @param [Array<Object>] args arguments will be transparently passed through to #bind
+        # @return [Either::Right]
+        def fmap(*args, &block)
+          Right.new(bind(*args, &block))
         end
 
-        def or(_val = nil)
+        # Ignores arguments and returns self. It exists to keep the interface
+        # identical to that of {Either::Left}.
+        #
+        # @return [Either::Right]
+        def or(*)
           self
         end
 
+        # @return [String]
         def to_s
           "Right(#{value.inspect})"
         end
         alias inspect to_s
 
+        # @return [Maybe::Some]
         def to_maybe
           Maybe::Some.new(value)
         end
       end
 
+      # Represents a value that is in an incorrect state, i.e. something went wrong.
+      #
+      # @api public
       class Left < Either
         alias value left
 
+        # @param left [Object] a value in an error state
         def initialize(left)
           @left = left
         end
 
-        def bind(_proc = nil)
+        # Ignores the input parameter and returns self. It exists to keep the interface
+        # identical to that of {Either::Right}.
+        #
+        # @return [Either::Left]
+        def bind(*)
           self
         end
 
-        def fmap(_proc = nil)
+        # Ignores the input parameter and returns self. It exists to keep the interface
+        # identical to that of {Either::Right}.
+        #
+        # @return [Either::Left]
+        def fmap(*)
           self
         end
 
-        def or(val = nil)
+        # If a block is given passes internal value to it and returns the result,
+        # otherwise simply returns the parameter val.
+        #
+        # @example
+        #   Dry::Monads.Left(ArgumentError.new('error message')).or(&:message) # => "error message"
+        #
+        # @param [Array<Object>] args 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)
+            yield(value, *args)
           else
-            val
+            args[0]
           end
         end
 
+        # @return [String]
         def to_s
           "Left(#{value.inspect})"
         end
         alias inspect to_s
 
+        # @return [Maybe::None]
         def to_maybe
           Maybe::None.instance
         end
       end
 
+      # A module that can be included for easier access to Either monads.
       module Mixin
         Right = Right
         Left = Left
 
+        # @param value [Object] the value to be stored in the monad
+        # @return [Either::Right]
         def Right(value)
           Right.new(value)
         end
 
+        # @param value [Object] the value to be stored in the monad
+        # @return [Either::Left]
         def Left(value)
           Left.new(value)
         end

data/lib/dry/monads/maybe.rb

@@ -1,6 +1,15 @@
 module Dry
   module Monads
+    # Represents a value which can exist or not, i.e. it could be nil.
+    #
+    # @api public
     class Maybe
+      include Dry::Equalizer(:value)
+
+      # Lifts the given value into Maybe::None or Maybe::Some monad.
+      #
+      # @param value [Object] the value to be stored in the monad
+      # @return [Maybe::Some, Maybe::None]
       def self.lift(value)
         if value.nil?
           None.instance
@@ -9,22 +18,26 @@ module Dry
         end
       end
 
-      def ==(other)
-        other.is_a?(Maybe) && value == other.value
-      end
-
+      # Returns true for an instance of a {Maybe::None} monad.
       def none?
         is_a?(None)
       end
 
+      # Returns true for an instance of a {Maybe::Some} monad.
       def some?
         is_a?(Some)
       end
 
+      # Returns self, added to keep the interface compatible with that of Either monad types.
+      #
+      # @return [Maybe::Some, Maybe::None]
       def to_maybe
         self
       end
 
+      # Represents a value that is present, i.e. not nil.
+      #
+      # @api public
       class Some < Maybe
         attr_reader :value
 
@@ -33,71 +46,128 @@ module Dry
           @value = value
         end
 
-        def bind(proc = nil)
-          if proc
-            proc.call(value)
+        # Calls the passed in Proc object with value stored in self
+        # and returns the result.
+        #
+        # If proc is nil, it expects a block to be given and will yield to it.
+        #
+        # @example
+        #   Dry::Monads.Some(4).bind(&:succ) # => 5
+        #
+        # @param [Array<Object>] args arguments that will be passed to a block
+        #                             if one was given, otherwise the first
+        #                             value assumed to be a Proc (callable)
+        #                             object and the rest of args will be passed
+        #                             to this object along with the internal value
+        # @return [Object] result of calling proc or block on the internal value
+        def bind(*args)
+          if block_given?
+            yield(value, *args)
           else
-            yield(value)
+            args[0].call(value, *args.drop(1))
           end
         end
 
-        def fmap(proc = nil, &block)
-          self.class.lift(bind(&(proc || block)))
+        # Does the same thing as #bind except it also wraps the value
+        # in an instance of Maybe::Some monad. This allows for easier
+        # chaining of calls.
+        #
+        # @example
+        #   Dry::Monads.Some(4).fmap(&:succ).fmap(->(n) { n**2 }) # => Some(25)
+        #
+        # @param [Array<Object>] args arguments will be transparently passed through to #bind
+        # @return [Maybe::Some, Maybe::None] Lifted 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))
         end
 
-        def or(_val = nil)
+        # Ignores arguments and returns self. It exists to keep the interface
+        # identical to that of {Maybe::None}.
+        #
+        # @return [Maybe::Some]
+        def or(*)
           self
         end
 
+        # @return [String]
         def to_s
           "Some(#{value.inspect})"
         end
         alias inspect to_s
       end
 
+      # Represents an absence of a value, i.e. the value nil.
+      #
+      # @api public
       class None < Maybe
         @instance = new
         singleton_class.send(:attr_reader, :instance)
 
+        # @return [nil]
         def value
           nil
         end
 
-        def bind(_proc = nil)
+        # Ignores arguments and returns self. It exists to keep the interface
+        # identical to that of {Maybe::Some}.
+        #
+        # @return [Maybe::None]
+        def bind(*)
           self
         end
 
-        def fmap(_proc = nil)
+        # Ignores arguments and returns self. It exists to keep the interface
+        # identical to that of {Maybe::Some}.
+        #
+        # @return [Maybe::None]
+        def fmap(*)
           self
         end
 
-        def or(val = nil)
+        # If a block is given passes internal value to it and returns the result,
+        # otherwise simply returns the parameter val.
+        #
+        # @example
+        #   Dry::Monads.None.or('no value') # => "no value"
+        #   Dry::Monads.None.or { Time.now } # => current time
+        #
+        # @param val [Object, nil]
+        # @return [Object]
+        def or(*args)
           if block_given?
-            yield(value)
+            yield(*args)
           else
-            val
+            args[0]
           end
         end
 
+        # @return [String]
         def to_s
           'None'
         end
         alias inspect to_s
       end
 
+      # A module that can be included for easier access to Maybe monads.
       module Mixin
         Maybe = Maybe
         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
 
+        # @param value [Object] the value to be stored in the monad
+        # @return [Maybe::Some]
         def Some(value)
           Some.new(value)
         end
 
+        # @return [Maybe::None]
         def None
           None.instance
         end

data/lib/dry/monads/try.rb

@@ -1,96 +1,178 @@
 module Dry
   module Monads
+    # Represents a value which can be either success or a failure (an exception).
+    # Use it to wrap code that can raise exceptions.
+    #
+    # @api public
     class Try
       attr_reader :exception, :value
 
+      # Calls the passed in proc object and if successful stores the result in a
+      # {Try::Success} monad, but if one of the specified exceptions was raised it stores
+      # it in a {Try::Failure} monad.
+      #
+      # @param exceptions [Array<Exception>] list of exceptions to be rescued
+      # @param f [Proc] the proc to be called
+      # @return [Try::Success, Try::Failure]
       def self.lift(exceptions, f)
         Success.new(exceptions, f.call)
       rescue *exceptions => e
         Failure.new(e)
       end
 
+      # Returns true for an instance of a {Try::Success} monad.
       def success?
         is_a? Success
       end
 
+      # Returns true for an instance of a {Try::Failure} monad.
       def failure?
         is_a? Failure
       end
 
+      # Represents a result of a successful execution.
+      #
+      # @api public
       class Success < Try
+        include Dry::Equalizer(:value, :catchable)
         attr_reader :catchable
 
+        # @param exceptions [Array<Exception>] list of exceptions to be rescued
+        # @param value [Object] the value to be stored in the monad
         def initialize(exceptions, value)
           @catchable = exceptions
           @value = value
         end
 
-        def bind(proc = nil)
-          if proc
-            proc.call(value)
+        # Calls the passed in Proc object with value stored in self
+        # and returns the result.
+        #
+        # If proc is nil, it expects a block to be given and will yield to it.
+        #
+        # @example
+        #   success = Dry::Monads::Try::Success.new(ZeroDivisionError, 10)
+        #   success.bind(->(n) { n / 2 }) # => 5
+        #   success.bind { |n| n / 0 } # => Try::Failure(ZeroDivisionError: divided by 0)
+        #
+        # @param [Array<Object>] args arguments that will be passed to a block
+        #                             if one was given, otherwise the first
+        #                             value assumed to be a Proc (callable)
+        #                             object and the rest of args will be passed
+        #                             to this object along with the internal value
+        # @return [Object, Try::Failure]
+        def bind(*args)
+          if block_given?
+            yield(value, *args)
           else
-            yield(@value)
+            args[0].call(value, *args.drop(1))
           end
         rescue *catchable => e
           Failure.new(e)
         end
 
-        def fmap(proc = nil, &block)
-          Try.lift(catchable, -> { (block || proc).call(@value) })
-        end
-
-        def ==(other)
-          other.is_a?(Success) && @value == other.value && @catchable == other.catchable
+        # Does the same thing as #bind except it also wraps the value
+        # in an instance of a Try monad. This allows for easier
+        # chaining of calls.
+        #
+        # @example
+        #   success = Dry::Monads::Try::Success.new(ZeroDivisionError, 10)
+        #   success.fmap(&:succ).fmap(&:succ).value # => 12
+        #   success.fmap(&:succ).fmap { |n| n / 0 }.fmap(&:succ).value # => nil
+        #
+        # @param [Array<Object>] args extra arguments for the block, arguments are being processes
+        #                             just as in #bind
+        # @return [Try::Success, Try::Failure]
+        def fmap(*args, &block)
+          if block
+            Try.lift(catchable, -> { yield(value, *args) })
+          else
+            Try.lift(catchable, -> { args[0].call(value, *args.drop(1)) })
+          end
         end
 
+        # @return [Maybe]
         def to_maybe
-          Dry::Monads::Maybe(@value)
+          Dry::Monads::Maybe(value)
         end
 
+        # @return [Either::Right]
         def to_either
-          Dry::Monads::Right(@value)
+          Dry::Monads::Right(value)
         end
 
+        # @return [String]
         def to_s
           "Try::Success(#{value.inspect})"
         end
         alias inspect to_s
       end
 
+      # Represents a result of a failed execution.
+      #
+      # @api public
       class Failure < Try
+        include Dry::Equalizer(:exception)
+
+        # @param exception [Exception]
         def initialize(exception)
           @exception = exception
         end
 
-        def bind(_f = nil)
+        # Ignores arguments and returns self. It exists to keep the interface
+        # identical to that of {Try::Success}.
+        #
+        # @return [Try::Failure]
+        def bind(*)
           self
         end
 
-        def fmap(_f = nil)
+        # Ignores arguments and returns self. It exists to keep the interface
+        # identical to that of {Try::Success}.
+        #
+        # @return [Try::Failure]
+        def fmap(*)
           self
         end
 
+        # @return [Maybe::None]
         def to_maybe
           Dry::Monads::None()
         end
 
+        # @return [Either::Left]
         def to_either
-          Dry::Monads::Left(@exception)
-        end
-
-        def ==(other)
-          other.is_a?(Failure) && @exception == other.exception
+          Dry::Monads::Left(exception)
         end
 
+        # @return [String]
         def to_s
           "Try::Failure(#{exception.class}: #{exception.message})"
         end
         alias inspect to_s
       end
 
+      # A module that can be included for easier access to Try monads.
+      #
+      # @example
+      #   class Foo
+      #     include Dry::Monads::Try::Mixin
+      #
+      #     attr_reader :average
+      #
+      #     def initialize(total, count)
+      #       @average = Try(ZeroDivisionError) { total / count }.value
+      #     end
+      #   end
+      #
+      #   Foo.new(10, 2).average # => 5
+      #   Foo.new(10, 0).average # => nil
       module Mixin
         Try = Try
 
+        # A convenience wrapper for {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.
         def Try(*exceptions, &f)
           catchable = exceptions.any? ? exceptions.flatten : [StandardError]
           Try.lift(catchable, f)

data/lib/dry/monads/version.rb

@@ -1,5 +1,5 @@
 module Dry
   module Monads
-    VERSION = '0.0.2'.freeze
+    VERSION = '0.1.0'.freeze
   end
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: dry-monads
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Nikita Shilnikov
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-06-29 00:00:00.000000000 Z
+date: 2016-08-23 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-equalizer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement