maybe.rb 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b0161b9efdecf4cc33db1c2e09e5485b026ce291
+  data.tar.gz: f38f123c09332b4b3f180e0d654e25a36071b048
+SHA512:
+  metadata.gz: b49abd1dd5b67ba7974e1d8896e86afed9fa7c5d228169322cc414bedf074396be964173bd6797ee4909ee6f4549b7b9078c25adf0d0af855ecc68abb2020a7d
+  data.tar.gz: 272a780ec77be12dfb3e228de4215312a26ef2ff0cc847de9e016eff55d7ee9e2baa026ac7d6ed7c286799abc5f9d82df1fb158d77ae306e86be1e03ec0539dd

data/.yardopts

@@ -0,0 +1,13 @@
+./lib/maybe/**/*.rb ./lib/maybe.rb
+-m markdown
+-M kramdown
+-o yardoc
+-r ./README.md
+--private
+--protected
+--asset ./doc/css/common.css:css/common.css
+--verbose
+-
+./doc/*.md
+LICENSE
+CONTRIBUTING.md

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2015, Olery B.V.
+
+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/README.md

@@ -0,0 +1,127 @@
+# Maybe.rb
+
+> I had a grey horse called maybe, we could not decide what to call her and the
+> US exchange student kept saying "ahh maybe" when we suggested names.
+
+A gem providing a very simple Maybe monad for Ruby, minus all the other
+functional programming features often seen in other libraries (such as `bind`).
+
+So why would one want to use a Maybe monad? Well, maybe you're writing Ruby, and
+maybe you've got code like this:
+
+    number = some_array[0]['some_hash_key'] || 0
+
+This code however is not guaranteed to always work. For example, if `some_array`
+contains the result of a database query then it might be empty. In such a case
+you'll get the dreaded nil error:
+
+    NoMethodError: undefined method `[]' for nil:NilClass
+
+There are a few ways you can work around this, for example using an `if`
+statement:
+
+    if some_array[0]
+      number = some_array[0]['some_hash_key']
+    else
+      number = 0
+    end
+
+This can be shortened a bit using the ternary operator:
+
+    number = some_array[0] ? some_array[0]['some_hash_key'] : 0
+
+Alternatively you can take the Ostrich approach and just bury your head in the
+sand:
+
+    number = some_array[0]['some_hash_key'] rescue 0
+
+Ostrich based programming however has its problems. Because in the above case we
+rescue _all_ errors we could potentially rescue too much and introduce bugs as a
+result. For example, if `some_array` were a method returning data from an API,
+and said API would raise an authentication error we'd never know.
+
+Another problem of the statement based solution is code duplication. Even when
+using the ternary operator we have to repeat some part of the code we're trying
+to access (`some_array[0]` in the above example).
+
+Using this particular Gem we can write the above code as following:
+
+    number = Maybe.new(some_array)[0]['some_hash_key'].or(0)
+
+This particular syntax can be made a bit shorter by loading the `maybe/pollute`
+file which adds `Object#maybe`, allowing you to write the following instead:
+
+    number = some_array.maybe[0]['some_hash_key'].or(0)
+
+This is disabled by default and the `Maybe` class itself doesn't rely on it and
+because it's not too pleasant for a library to implicitly patch built-in Ruby
+classes.
+
+## Usage
+
+Load the Gem:
+
+    require 'maybe'
+
+Optionally pollute `Object` so you can just call `maybe` on any object:
+
+    require 'maybe/polluate'
+
+Wrap a value using the `Maybe` class directly:
+
+    numbers = [10]
+
+    Maybe.new(numbers)[1].or(20) # => 20
+
+Using `Object#maybe`:
+
+    numbers = [10]
+
+    numbers.maybe[1].or(20) # => 20
+
+The Maybe class also allows you to use a block instead of the `[]` method (which
+is just an alias for `Maybe#maybe`):
+
+    numbers = [10, 20, 30]
+
+    numbers.maybe(0) { |value| value * 10 }.or(1) # => 100
+    numbers.maybe(3) { |value| value * 10 }.or(1) # => 1
+
+Calling `Maybe#maybe` also works without an argument, in which case the
+currently wrapped value is yielded to the block (if there is any value to
+yield):
+
+    numbers[0].maybe { |value| value.to_s }.or('1') # => '10'
+
+For more examples, see the documentation (and source code) of
+[lib/maybe/maybe.rb](lib/maybe/maybe.rb).
+
+## What is this magic?
+
+The way this Monad works is that any non `nil` value is yielded to a supplied
+block or returned as a new Maybe instance. The moment you call `Maybe#or` this
+method will verify the currently wrapped value and decide what to return.
+
+If the wrapped value is not nil it's simply returned. If the value is nil and a
+block is given then said block is yielded. If the value is nil and _no_ block is
+given the method will simply return its argument (`nil` by default).
+
+Some examples (using `Object#maybe` for better readability):
+
+    10.maybe.or(20)    # => 10
+    10.maybe.or { 20 } # => 10
+    10.maybe.or        # => 10
+
+    nil.maybe.or(20)    # => 20
+    nil.maybe.or { 20 } # => 20
+    nil.maybe.or        # => nil, since the default return value is nil
+
+## Requirements
+
+* Ruby
+
+## License
+
+All source code in this repository is licensed under the MIT license unless
+specified otherwise. A copy of this license can be found in the file "LICENSE"
+in the root directory of this repository.

data/doc/DCO.md

@@ -0,0 +1,25 @@
+# Developer's Certificate of Origin 1.0
+
+By making a contribution to this project, I certify that:
+
+1. The contribution was created in whole or in part by me and I
+   have the right to submit it under the open source license
+   indicated in the file LICENSE; or
+
+2. The contribution is based upon previous work that, to the best
+   of my knowledge, is covered under an appropriate open source
+   license and I have the right under that license to submit that
+   work with modifications, whether created in whole or in part
+   by me, under the same open source license (unless I am
+   permitted to submit under a different license), as indicated
+   in the file LICENSE; or
+
+3. The contribution was provided directly to me by some other
+   person who certified (1), (2) or (3) and I have not modified
+   it.
+
+4. I understand and agree that this project and the contribution
+   are public and that a record of the contribution (including all
+   personal information I submit with it, including my sign-off) is
+   maintained indefinitely and may be redistributed consistent with
+   this project or the open source license(s) involved.

data/doc/css/common.css

@@ -0,0 +1,77 @@
+body
+{
+    font-size:   14px;
+    line-height: 1.6;
+    margin:      0 auto;
+    max-width:   960px;
+}
+
+p code, dd code, li code
+{
+    background: #f9f2f4;
+    color: #c7254e;
+    border-radius: 4px;
+    padding: 2px 4px;
+}
+
+pre.code
+{
+    font-size:   13px;
+    line-height: 1.4;
+    overflow:    auto;
+}
+
+blockquote
+{
+    border-left: 5px solid #eee;
+    margin: 0px;
+    padding-left: 15px;
+}
+
+/**
+ * YARD uses generic table styles, using a special class means those tables
+ * don't get messed up.
+ */
+.table
+{
+    border:          1px solid #ccc;
+    border-right:    none;
+    border-collapse: separate;
+    border-spacing:  0;
+    text-align:      left;
+}
+
+.table.full
+{
+    width: 100%;
+}
+
+    .table .field_name
+    {
+        min-width: 160px;
+    }
+
+    .table thead tr th.no_sort:first-child
+    {
+        width: 25px;
+    }
+
+    .table thead tr th, .table tbody tr td
+    {
+        border-bottom:  1px solid #ccc;
+        border-right:   1px solid #ccc;
+        min-width:      20px;
+        padding:        8px 5px;
+        text-align:     left;
+        vertical-align: top;
+    }
+
+    .table tbody tr:last-child td
+    {
+        border-bottom: none;
+    }
+
+    .table tr:nth-child(odd) td
+    {
+        background: #f9f9f9;
+    }

data/lib/maybe/maybe.rb

@@ -0,0 +1,155 @@
+##
+# The Maybe class is a very simple implemention of the maybe monad/option type
+# often found in functional programming languages. To explain the use of this
+# class, lets take at the following code:
+#
+#     pairs = [{:a => 10}]
+#
+#     number = pairs[0][:a]
+#
+# While this code is very simple, there are already a few problems that can
+# arise:
+#
+# 1. If the pairs Array is empty we'll get an "undefined method [] for nil"
+#    error as pairs[0] in this case returns nil.
+# 2. If the :a key is not set we'll again end up with a nil value, which might
+#    break code later on.
+#
+# So lets add some code to take care of this, ensuring we _always_ have a
+# number:
+#
+#     pairs = [{:a => 10}]
+#
+#     number = pairs[0] ? pairs[0][:a] || 0 : 0
+#
+# Alternatively:
+#
+#     pairs = [{:a => 10}]
+#
+#     number = (pairs[0] ? pairs[0][:a] : nil) || 0
+#
+# Both cases are quite messy. Using the Maybe class we can write this as
+# following instead:
+#
+#     pairs = [{:a => 10}]
+#
+#     numbers = Maybe.new(pairs[0]).maybe(:a).or(0)
+#
+# If we use the patch for Object (adding `Object#maybe`) we can write this as
+# following:
+#
+#     pairs = [{:a => 10}]
+#
+#     numbers = pairs[0].maybe(:a).or(0)
+#
+# Or even better:
+#
+#     pairs = [{:a => 10}]
+#
+#     numbers = pairs.maybe[0][:a].or(0)
+#
+# Boom, we no longer need to rely on ternaries or the `||` operator to ensure we
+# always have a default value.
+#
+class Maybe
+  ##
+  # @param [Mixed] wrapped
+  #
+  def initialize(wrapped)
+    @wrapped = wrapped
+  end
+
+  ##
+  # @return [Mixed]
+  #
+  def unwrap
+    return @wrapped
+  end
+
+  ##
+  # Retrieves a value from the wrapped object. This method can be used in two
+  # ways:
+  #
+  # 1. Using a member (e.g. Array index or Hash key) in case the underlying
+  #    object defines a "[]" method.
+  #
+  # 2. Using a block which takes the wrapped value as its argument.
+  #
+  # For example, to get index 0 from an Array and return it as a Maybe:
+  #
+  #     Maybe.new([10, 20, 30]).maybe(0) # => #<Maybe:0x0...>
+  #
+  # To get a Hash key:
+  #
+  #     Maybe.new({:a => 10}).maybe(:a) # => #<Maybe:0x00...>
+  #
+  # Using a block:
+  #
+  #     Maybe.new([10, 20, 30]).maybe { |array| array[0] }
+  #
+  # The block is only evaluated if the current Maybe wraps a non-nil value. The
+  # return value of the block is wrapped in a new Maybe instance.
+  #
+  # This method is aliased as `[]` allowing usage such as the following:
+  #
+  #     maybe = Maybe.new([{'foo' => 10}])
+  #
+  #     maybe[0]['foo'].or(20)
+  #
+  # @param [Array] args
+  #
+  # @yieldparam [Mixed] wrapped The wrapped value
+  #
+  # @return [Maybe]
+  #
+  def maybe(*args)
+    if !args.empty?
+      value = brackets? ? @wrapped[*args] : nil
+    elsif @wrapped
+      value = yield @wrapped
+    end
+
+    if value.nil? and @wrapped.nil?
+      # No point in allocating a new Maybe for this.
+      return self
+    else
+      return Maybe.new(value)
+    end
+  end
+
+  alias_method :[], :maybe
+
+  ##
+  # Returns the wrapped value or returns a default value, specified as either an
+  # argument to this method or in the provided block.
+  #
+  # A simple example:
+  #
+  #     Maybe.new([10, 20]).maybe(0).or(9000)
+  #
+  # And using a block:
+  #
+  #     Maybe.new([10, 20]).maybe(0).or { 9000 }
+  #
+  # @param [Mixed] default
+  # @return [Mixed]
+  #
+  def or(default = nil)
+    return @wrapped unless @wrapped.nil?
+
+    if block_given?
+      return yield
+    else
+      return default
+    end
+  end
+
+  private
+
+  ##
+  # @return [TrueClass|FalseClass]
+  #
+  def brackets?
+    return @wrapped.respond_to?(:[])
+  end
+end # Maybe

data/lib/maybe/pollute.rb

@@ -0,0 +1,23 @@
+class Object
+  ##
+  # Wraps the current object in a Maybe instance, optionally calling {Maybe#get}
+  # if an argument or block is given.
+  #
+  # @example
+  #  [10, 20, 30].maybe(0).or(50)               # => 10
+  #  [10, 20, 30].maybe { |arr| arr[3] }.or(50) # => 50
+  #
+  # @see [Maybe#get]
+  #
+  def maybe(*args)
+    retval = Maybe.new(self)
+
+    if !args.empty?
+      retval = retval.maybe(*args)
+    elsif block_given?
+      retval = retval.maybe(&Proc.new)
+    end
+
+    return retval
+  end
+end # Object

data/lib/maybe/version.rb

@@ -0,0 +1,3 @@
+class Maybe
+  VERSION = '1.0.0'
+end # Maybe

data/lib/maybe.rb

@@ -0,0 +1,2 @@
+require_relative 'maybe/version'
+require_relative 'maybe/maybe'

data/maybe.rb.gemspec

@@ -0,0 +1,30 @@
+require File.expand_path('../lib/maybe/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name        = 'maybe.rb'
+  gem.version     = Maybe::VERSION
+  gem.authors     = ['Olery B.V.']
+  gem.email       = 'development@olery.com'
+  gem.summary     = 'A basic maybe monad in Ruby'
+  gem.homepage    = 'https://github.com/olery/maybe/'
+  gem.description = gem.summary
+  gem.license     = 'MIT'
+
+  gem.files = Dir.glob([
+    'doc/**/*',
+    'lib/**/*.rb',
+    'README.md',
+    'LICENSE',
+    'maybe.rb.gemspec',
+    '.yardopts'
+  ]).select { |file| File.file?(file) }
+
+  gem.has_rdoc              = 'yard'
+  gem.required_ruby_version = '>= 1.9.3'
+
+  gem.add_development_dependency 'yard'
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'kramdown'
+  gem.add_development_dependency 'simplecov'
+end

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification
+name: maybe.rb
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Olery B.V.
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-03-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A basic maybe monad in Ruby
+email: development@olery.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- LICENSE
+- README.md
+- doc/DCO.md
+- doc/css/common.css
+- lib/maybe.rb
+- lib/maybe/maybe.rb
+- lib/maybe/pollute.rb
+- lib/maybe/version.rb
+- maybe.rb.gemspec
+homepage: https://github.com/olery/maybe/
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: A basic maybe monad in Ruby
+test_files: []
+has_rdoc: yard