ruby-monads 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 20b2534e81fe4b81311ea0dc9b9ab696edab9a2cffc124ef922bb9d26edc87b8
+  data.tar.gz: 050a8dea7bfeb6dea6b6635c90ce216968208d73346023440ef4410cbdd00e62
+SHA512:
+  metadata.gz: 0a8ce58d40d7c361e1e860c1700b5edbbbb927698449ecddc412fdd3ce6f3bc3f3bd1e923ef62ab33fd7f92e13fc3b7f1afb7e7d7cfb79337bda0cfcb9aacf19
+  data.tar.gz: 604d7fddc645a0e08591d192736339eacc17174a39f3d4b58500c4aaa9df19b02c5917cd7cc6f0cfcfeedb5ee62ca2673fd611e00216d603671ec6e174ec00ee

data/.gems

@@ -0,0 +1 @@
+cutest -v 1.2.3

data/.gitignore

@@ -0,0 +1 @@
+*.gem

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Guillaume BOUDON
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/Makefile

@@ -0,0 +1,4 @@
+.PHONY: test
+
+test:
+	cutest -r ./test/helper.rb ./test/*_test.rb

data/README.md

@@ -0,0 +1,68 @@
+# ruby-monads
+
+These are some Ruby implementations of some common monads.
+
+## Usage
+
+If you don't already have it installed:
+
+```sh
+gem install ruby-monads
+```
+
+As these are just some new abstractions, just include it:
+
+```ruby
+require "monads"
+
+include Monads
+```
+
+## Monads
+
+### Maybe
+
+The maybe monad returns one of the following classes, wether it wraps a value or not:
+
+- `Maybe.unit(42)` returns an instance of `Just` wrapping the `42` value
+- `Maybe.unit(nil)` returns an instance of `Nothing` wrapping no value
+
+#### Examples
+
+```ruby
+just = Maybe.unit("Hello, World!")     # => #<Monads::Just @value="Hello, World!">
+nothing = Maybe.unit(nil)              # => #<Monads::Nothing>
+
+just.upcase                            # => #<Monads::Just @value="HELLO, WORLD!">
+just.upcase.split.unwrap([])           # => ["HELLO,", "WORLD!"]
+just.bind { |v| Maybe.unit(nil) }      # => #<Monads::Nothing>
+just.fmap { |v| v.gsub(/\w/, "*") }    # => #<Monads::Just @value="*****, *****!">
+Maybe.unit(just).join                  # => #<Monads::Just @value="Hello, World!">
+
+nothing.upcase                         # => #<Monads::Nothing>
+nothing.upcase.split.unwrap([])        # => []
+nothing.bind { |v| just }              # => #<Monads::Nothing>
+nothing.fmap { |v| v.gsub(/\w/, "*") } # => #<Monads::Nothing>
+Maybe.unit(nothing).join               # => #<Monads::Nothing>
+```
+
+## Why this gem
+
+This gem is heavily inspired by the following monads implementations:
+
+- [Monadic](https://github.com/pzol/monadic)
+- [Monads](https://github.com/tomstuart/monads)
+
+These gems, and many others are really great, and it was very instructive to learn about this topic in my beloved language. However, after reading a lot of implementations and articles, I had a clear opinion of how I wanted it:
+
+- _Minimalist:_ as simple an lightweight as possible
+- _Respectful of uses:_ respectful of the usual terms ([Monad (functional programming)](https://en.wikipedia.org/wiki/Monad_(functional_programming))), like `Maybe`, `unit`, `bind`, `join`, etc.
+- _Vanilla Ruby syntax:_ I love some of the abstractions I discovered (`>=` operator, `Just(value)` syntax). However, I also love vanilla Ruby. So, I wanted to target new methods and abstractions, not new syntaxes comming from other languages.
+
+## Tests
+
+Test suite uses [cutest](https://github.com/djanowski/cutest). You can execute it with:
+
+```sh
+make
+```

data/lib/monads.rb

@@ -0,0 +1,4 @@
+require_relative "monads/monad"
+
+require_relative "monads/maybe"
+require_relative "monads/result"

data/lib/monads/maybe.rb

@@ -0,0 +1,47 @@
+module Monads
+  class Maybe
+    include Monads::Monad
+
+    # unit :: a -> M a
+    def self.unit(value)
+      value.nil? || value.is_a?(Nothing) ? Nothing.new : Just.new(value)
+    end
+
+    # bind :: (a -> M b) -> M a -> M b
+    def bind(&block)
+      ensure_monadic_result(&block).call
+    end
+
+    # unwrap :: a -> M a -> a
+    def unwrap(default_value)
+      @value || default_value
+    end
+
+    private
+
+    def monad_type
+      Maybe
+    end
+  end
+
+  class Just < Maybe
+    public_class_method :new
+
+    def self.new(value)
+      raise TypeError, "value should not be of #{value.class}" if value.nil?
+      super
+    end
+  end
+
+  class Nothing < Maybe
+    public_class_method :new
+
+    def initialize
+    end
+
+    # bind :: (a -> M b) -> M a -> M b
+    def bind(&block)
+      self
+    end
+  end
+end

data/lib/monads/monad.rb

@@ -0,0 +1,44 @@
+module Monads
+  module Monad
+    def self.included(base)
+      base.class_eval do
+        private_class_method :new
+      end
+    end
+
+    def initialize(value)
+      @value = value
+    end
+
+    # fmap :: (a -> b) -> M a -> M b
+    def fmap(&block)
+      bind do |value|
+        self.class.unit(block.call(value))
+      end
+    end
+
+    # join :: M (M a) -> M a
+    def join
+      value = @value.is_a?(monad_type) ? @value.unwrap(nil) : @value
+      monad_type.unit(value)
+    end
+
+    def method_missing(method, *args, &block)
+      fmap do |value|
+        value.public_send(method, *args, &block)
+      end
+    end
+
+    private
+
+    def ensure_monadic_result(&block)
+      proc do
+        block.call(@value).tap do |result|
+          unless result.is_a?(monad_type)
+            raise TypeError, "block must return #{monad_type.name}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monads/result.rb

@@ -0,0 +1,52 @@
+module Monads
+  class Result
+    include Monads::Monad
+
+    FAILURE_TRIGGER = StandardError
+
+    # unit :: a -> M a
+    def self.unit(value)
+      value.is_a?(FAILURE_TRIGGER) ? Failure.new(value) : Success.new(value)
+    end
+
+    # bind :: (a -> M b) -> M a -> M b
+    def bind(&block)
+      return self if is_a?(Failure)
+
+      begin
+        ensure_monadic_result(&block).call
+      rescue FAILURE_TRIGGER => error
+        Failure.new(error)
+      end
+    end
+
+    # unwrap :: a -> M a -> a
+    def unwrap(default_value = @value)
+      is_a?(Failure) ? default_value : @value
+    end
+
+    private
+
+    def monad_type
+      Result
+    end
+  end
+
+  class Success < Result
+    public_class_method :new
+
+    def self.new(value)
+      raise TypeError, "value should not be of #{value.class}" if value.is_a?(FAILURE_TRIGGER)
+      super
+    end
+  end
+
+  class Failure < Result
+    public_class_method :new
+
+    def self.new(value)
+      raise TypeError, "value should not be of #{value.class}" unless value.is_a?(FAILURE_TRIGGER)
+      super
+    end
+  end
+end

data/ruby-monads.gemspec

@@ -0,0 +1,14 @@
+Gem::Specification.new do |s|
+  s.name = "ruby-monads"
+  s.version = "0.1.0"
+  s.summary = "Some common monads"
+  s.description = "Simple and minimalist ruby implementation of some common monads"
+  s.author = "Guillaume BOUDON"
+  s.email = "guillaumeboudon@gmail.com"
+  s.homepage = "https://github.com/guillaumeboudon/ruby-monads"
+  s.license = "MIT"
+
+  s.files = `git ls-files`.split("\n")
+
+  s.add_development_dependency "cutest", "~> 1.2", ">= 1.2.3"
+end

data/test/helper.rb

@@ -0,0 +1,3 @@
+require_relative "../lib/monads"
+
+include Monads

data/test/maybe_test.rb

@@ -0,0 +1,63 @@
+print "\n\"Maybe\" monad test suite"
+
+setup do
+  [Maybe.unit("Hello, World!"), Maybe.unit(nil)]
+end
+
+test "Maybe::new" do
+  assert_raise NoMethodError do Maybe.new(42) end
+
+  assert_raise TypeError do Just.new(nil) end
+  assert Just.new(42).is_a?(Just)
+
+  assert_raise ArgumentError do Nothing.new(42) end
+  assert Nothing.new.is_a?(Nothing)
+end
+
+test "Maybe::unit" do |just, nothing|
+  assert just.is_a?(Maybe)
+  assert just.is_a?(Just)
+  assert !just.is_a?(Nothing)
+
+  assert nothing.is_a?(Maybe)
+  assert !nothing.is_a?(Just)
+  assert nothing.is_a?(Nothing)
+
+  assert Maybe.unit(just).is_a?(Just)
+  assert Maybe.unit(nothing).is_a?(Nothing)
+end
+
+test "Maybe#bind" do |just, nothing|
+  assert just.bind { |v| Maybe.unit(v.to_sym) }.is_a?(Just)
+  assert just.bind { |v| Maybe.unit(nil) }.is_a?(Nothing)
+  assert_raise TypeError do just.bind { |v| v.to_sym } end
+
+  assert nothing.bind { |v| Maybe.unit(42) }.is_a?(Nothing)
+  assert nothing.bind { |v| Maybe.unit(nil) }.is_a?(Nothing)
+  assert nothing.bind { |v| v.to_sym }.is_a?(Nothing)
+end
+
+test "Maybe#fmap" do |just, nothing|
+  assert just.fmap(&:to_sym).is_a?(Just)
+  assert just.fmap { |v| nil }.is_a?(Nothing)
+
+  assert nothing.fmap(&:to_sym).is_a?(Nothing)
+  assert nothing.fmap { |v| 42 }.is_a?(Nothing)
+end
+
+test "Maybe#join" do |just, nothing|
+  assert_equal Maybe.unit(just).join.unwrap("default"), "Hello, World!"
+  assert_equal Maybe.unit(nothing).join.unwrap("default"), "default"
+end
+
+test "Maybe#unwrap" do |just, nothing|
+  assert_equal just.unwrap("default"), "Hello, World!"
+  assert_equal just.unwrap(nil), "Hello, World!"
+  assert_equal nothing.unwrap("default"), "default"
+  assert_equal nothing.unwrap(nil), nil
+end
+
+test "Maybe accepts methods chaining" do |just, nothing|
+  assert_equal just.upcase.reverse.split.unwrap([]), ["!DLROW", ",OLLEH"]
+  assert_equal nothing.upcase.reverse.split.unwrap([]), []
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: ruby-monads
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Guillaume BOUDON
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2020-08-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: cutest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.3
+description: Simple and minimalist ruby implementation of some common monads
+email: guillaumeboudon@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gems"
+- ".gitignore"
+- LICENSE
+- Makefile
+- README.md
+- lib/monads.rb
+- lib/monads/maybe.rb
+- lib/monads/monad.rb
+- lib/monads/result.rb
+- ruby-monads.gemspec
+- test/helper.rb
+- test/maybe_test.rb
+homepage: https://github.com/guillaumeboudon/ruby-monads
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key:
+specification_version: 4
+summary: Some common monads
+test_files: []