yopt 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: da7d8098ce8b1dcc66d5e8f6ba3baf208daf805d
+  data.tar.gz: 6ae68982bb5ff8a3dc09cba07961c04e51b46fa3
+SHA512:
+  metadata.gz: 57fa46f4d6f766ac6fcd87a4b261fd049e8e3757c5578efa2851235b096f1086eb5cb1c801d0ca2dfa0266d6f5d593564677f4a170be22636cbcf3708517ddd9
+  data.tar.gz: 577ab29f9bdb5283d93941f24995c5d8b4cb02a7847faa2ff66e5018b8c7308f582adac0439ea1ff5c1dd7039fa68d32f8defed983b61dfd34122ddd0f043b0f

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/vendor
+/yopt-0.1.0.gem

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.0
+before_install: gem install bundler -v 1.10.6

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+gem 'pry', '~> 0.10.3'
+gem 'rb-readline', '~> 0.5.3'
+# Specify your gem's dependencies in yopt.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 lorenzo.barasti
+
+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,206 @@
+# Yopt
+
+A [Scala](http://www.scala-lang.org/api/current/index.html#scala.Option) inspired gem that introduces `Option`s to Ruby while aiming for an idiomatic API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'yopt'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install yopt
+
+## Basic usage
+
+The Option type models the possible absence of a value. It lets us deal with the uncertainty related to such a value being there without having to resort to errors or conditional blocks.
+
+Instances of Option are either an instance of `Yopt::Some` - meaning the option contains a value - or the object `Yopt::None` - meaning the option is *empty*.
+
+```ruby
+require 'yopt'
+
+some = Yopt::Some.new(42)
+none = Yopt::None
+```
+
+We can access and manipulate the optional value by passing a block to `Option#map`.
+
+```ruby
+some.map {|value| value + 2} # returns Some(44)
+none.map {|value| value + 2} # returns None
+```
+
+When we are not interested in the result of a computation on the optional value, it is a good practice to use `Option#each` rather than `Option#map`. That will make our intention clearer.
+
+```ruby
+some.each {|value| puts value} # prints 42
+none.each {|value| puts value} # does not print anything
+```
+
+We can safely retrieve the optional value by passing a default value to `Option#get_or_else`
+
+```ruby
+some.get_or_else 0 # returns 42
+none.get_or_else 0 # returns 0
+```
+
+We can also filter the optional value depending on how it evaluates against a block via `Option#select`
+
+```ruby
+some.select {|value| value < 0} # returns None
+none.select {|value| value < 0} # returns None
+some.select {|value| value > 0} # returns Some(42)
+```
+
+We can easily turn any object into an Option by means of `Option.call` - aliased to `Option.[]` for convenience.
+For instance, this is useful when dealing with functions that might return `nil` to express the absence of a result.
+
+```ruby
+Yopt::Option[nil] # returns None
+Yopt::Option[42] # returns Some(42)
+```
+
+
+A combination of the few methods just introduced already allows us to implement some pretty interesting logic. Checkout `basics.rb` in the docs folder to get some inspiration.
+
+## Why opt?
+
+Using `Option`s reduces the amount of branching in our code and lets us deal with exceptional cases in a seamless way. No more check-for-nil, no more `rescue` blocks, just plain and simple data transformation.
+
+It also makes our code safer by treating *the absence of something* like a fully fledged object, and enables us to use the Null Object Pattern everywhere we want without the overhead of having to write specialized Null-type classes for different classes.
+
+## Advanced Usage
+### #reduce
+Given an Option `opt`, a value `c` and a lambda `f`,
+```
+opt.reduce(c, &f)
+```
+returns `c` if `opt` is `None`, and `f.(c, opt)` otherwise.
+
+This is a shortcut to
+```
+opt.map{|v| f.(c,v)}.get_or_else(c)`
+```
+
+
+### #flatten and #flat_map
+When working with functions returning `Option`, we might end up dealing with nested options...
+```ruby
+maybe_sqrt = lambda {|x| Yopt::Option[x >= 0 ? Math.sqrt(x) : nil]}
+maybe_increment = lambda {|x| Yopt::Option[x > 1  ? x + 1 : nil]}
+
+maybe_sqrt.(4).map {|v| maybe_increment.(v)} # Some(Some(3.0))
+maybe_sqrt.(1).map {|v| maybe_increment.(v)} # Some(None)
+```
+
+Usually, this is not what we want, so we call `Option#flatten` on the result
+```ruby
+maybe_sqrt.(4).map {|v| maybe_increment.(v)}.flatten # Some(3.0)
+maybe_sqrt.(1).map {|v| maybe_increment.(v)}.flatten # None
+```
+
+`Option#flat_map` combines the two calls into one
+
+```ruby
+maybe_sqrt.(4).flat_map {|v| maybe_increment.(v)} # Some(3.0)
+maybe_sqrt.(1).flat_map {|v| maybe_increment.(v)} # None
+```
+
+A difference to keep in mind is that `#flatten` will raise an error if the wrapped value does not respond to `#to_ary`
+```ruby
+Yopt.Option[42].flatten # raises TypeError: Argument must be an array-like object. Found Fixnum
+```
+whereas #flat_map behaves like #map when the passed block does not return an array-like value
+```ruby
+Yopt.Option[42].flat_map{|v| v} # returns Some(42)
+```
+
+
+### #zip
+When dealing with a set of `Option` instances, we might want to ensure that they are all defined - i.e. not __empty__ - before continuing a computation...
+```ruby
+email_opt.each(&send_pass_recovery) unless (email_opt.empty? or captcha_opt.empty?)
+```
+
+We can avoid `empty?` checks by using `Option#zip`
+```ruby
+email_opt.zip(captcha_opt).each{|(email,_)| send_pass_recovery(email)}
+```
+
+`Option#zip` returns `None` if any of the arguments is `None` or if the caller is `None`
+```ruby
+Yopt::None.zip Option.[42] # None
+Option.[42].zip Yopt::None # None
+Option.[42].zip Option.[0], Yopt::None, Option.[-1] # None
+```
+
+When both the caller and all the arguments are defined then `zip` collects all the values in an Array wrapped in a `Yopt::Some`
+
+```ruby
+Option.[42].zip Option.[0], Option.["str"] # Some([42, 0, "str"])
+```
+
+
+### #grep
+We often find ourselves filtering data before applying a transformation...
+
+```ruby
+opt.filter {|v| (1...10).include? v}.map {|v| v + 1}
+```
+
+In this scenario, `Option#grep` can sometimes make the code more concise
+
+```ruby
+opt.grep(1...10) {|v| v + 1}
+```
+
+`Option#grep` supports lambdas as well
+
+```ruby
+is_positive = lambda {|x| x > 0}
+
+opt.grep(is_positive) {|v| Math.log(v)}
+# is equivalent to
+opt.filter(&is_positive).map {|v| Math.log(v)}
+```
+
+
+## Haskell Data.Maybe cheat sheet
+
+Some (None?) might enjoy a comparison with Haskell's [Maybe](https://hackage.haskell.org/package/base/docs/Data-Maybe.html). Here is how the Data.Maybe API translate to Yopt.
+```ruby
+maybe default f opt     -> opt.map(&f).get_or_else(default)
+isJust opt              -> not opt.empty?
+isNothing opt           -> opt.empty?
+fromJust opt            -> opt.get
+fromMaybe default opt   -> opt.get_or_else default
+listToMaybe list        -> Option.ary_to_type list
+maybeToList opt         -> opt.to_a
+catMaybes listOfOptions -> listOfOptions.flatten
+mapMaybe f list         -> list.flat_map &f
+```
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/lbarasti/yopt. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,39 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :docs do
+  partial_keyword = '<<<<<'
+  ignore_keyword = "# IGNORE\n"
+  comment_keyword = "# COMMENT\n"
+  src = './docs/README.template.md'
+  target = './README.md'
+  content = File.readlines(src).flat_map {|line|
+    if line.lstrip.start_with?(partial_keyword)
+      partial_file = line.lstrip[partial_keyword.size...-1]
+      sh 'ruby', partial_file
+      File.readlines partial_file
+    else
+      line
+    end
+  }
+  File.open(target, 'w') {|f|
+    content.reject{|line|
+      line.end_with?(ignore_keyword)
+    }.each_cons(2){|line1,line2|
+      next if line1.end_with?(comment_keyword)
+      if line2.end_with?(comment_keyword)
+        f.puts "#{line1.chomp} # #{line2.match(/'(.*)'/)[1]}\n"
+      else
+        f.puts line1
+      end
+    }
+  }
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "yopt"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "pry"
+Pry.start
+

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/docs/README.template.md

@@ -0,0 +1,207 @@
+# Yopt
+
+A [Scala](http://www.scala-lang.org/api/current/index.html#scala.Option) inspired gem that introduces `Option`s to Ruby while aiming for an idiomatic API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'yopt'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install yopt
+
+## Basic usage
+
+The Option type models the possible absence of a value. It lets us deal with the uncertainty related to such a value being there without having to resort to errors or conditional blocks.
+
+Instances of Option are either an instance of `Yopt::Some` - meaning the option contains a value - or the object `Yopt::None` - meaning the option is *empty*.
+
+```ruby
+require 'yopt'
+
+some = Yopt::Some.new(42)
+none = Yopt::None
+```
+
+We can access and manipulate the optional value by passing a block to `Option#map`.
+
+```ruby
+some.map {|value| value + 2} # returns Some(44)
+none.map {|value| value + 2} # returns None
+```
+
+When we are not interested in the result of a computation on the optional value, it is a good practice to use `Option#each` rather than `Option#map`. That will make our intention clearer.
+
+```ruby
+some.each {|value| puts value} # prints 42
+none.each {|value| puts value} # does not print anything
+```
+
+We can safely retrieve the optional value by passing a default value to `Option#get_or_else`
+
+```ruby
+some.get_or_else 0 # returns 42
+none.get_or_else 0 # returns 0
+```
+
+We can also filter the optional value depending on how it evaluates against a block via `Option#select`
+
+```ruby
+some.select {|value| value < 0} # returns None
+none.select {|value| value < 0} # returns None
+some.select {|value| value > 0} # returns Some(42)
+```
+
+We can easily turn any object into an Option by means of `Option.call` - aliased to `Option.[]` for convenience.
+For instance, this is useful when dealing with functions that might return `nil` to express the absence of a result.
+
+```ruby
+Yopt::Option[nil] # returns None
+Yopt::Option[42] # returns Some(42)
+```
+
+
+A combination of the few methods just introduced already allows us to implement some pretty interesting logic. Checkout `basics.rb` in the docs folder to get some inspiration.
+
+## Why opt?
+
+Using `Option`s reduces the amount of branching in our code and lets us deal with exceptional cases in a seamless way. No more check-for-nil, no more `rescue` blocks, just plain and simple data transformation.
+
+It also makes our code safer by treating *the absence of something* like a fully fledged object, and enables us to use the Null Object Pattern everywhere we want without the overhead of having to write specialized Null-type classes for different classes.
+
+## Advanced Usage
+### #reduce
+Given an Option `opt`, a value `c` and a lambda `f`,
+```
+opt.reduce(c, &f)
+```
+returns `c` if `opt` is `None`, and `f.(c, opt)` otherwise.
+
+This is a shortcut to
+```
+opt.map{|v| f.(c,v)}.get_or_else(c)`
+```
+
+
+### #flatten and #flat_map
+When working with functions returning `Option`, we might end up dealing with nested options...
+```ruby
+maybe_sqrt = lambda {|x| Yopt::Option[x >= 0 ? Math.sqrt(x) : nil]}
+maybe_increment = lambda {|x| Yopt::Option[x > 1  ? x + 1 : nil]}
+
+maybe_sqrt.(4).map {|v| maybe_increment.(v)} # Some(Some(3.0))
+maybe_sqrt.(1).map {|v| maybe_increment.(v)} # Some(None)
+```
+
+Usually, this is not what we want, so we call `Option#flatten` on the result
+```ruby
+maybe_sqrt.(4).map {|v| maybe_increment.(v)}.flatten # Some(3.0)
+maybe_sqrt.(1).map {|v| maybe_increment.(v)}.flatten # None
+```
+
+`Option#flat_map` combines the two calls into one
+
+```ruby
+maybe_sqrt.(4).flat_map {|v| maybe_increment.(v)} # Some(3.0)
+maybe_sqrt.(1).flat_map {|v| maybe_increment.(v)} # None
+```
+
+A difference to keep in mind is that `#flatten` will raise an error if the wrapped value does not respond to `#to_ary`
+```ruby
+Yopt.Option[42].flatten # raises TypeError: Argument must be an array-like object. Found Fixnum
+```
+whereas #flat_map behaves like #map when the passed block does not return an array-like value
+```ruby
+Yopt.Option[42].flat_map{|v| v} # returns Some(42)
+```
+
+
+### #zip
+When dealing with a set of `Option` instances, we might want to ensure that they are all defined - i.e. not __empty__ - before continuing a computation...
+```ruby
+email_opt.each(&send_pass_recovery) unless (email_opt.empty? or captcha_opt.empty?)
+```
+
+We can avoid `empty?` checks by using `Option#zip`
+```ruby
+email_opt.zip(captcha_opt).each{|(email,_)| send_pass_recovery(email)}
+```
+
+`Option#zip` returns `None` if any of the arguments is `None` or if the caller is `None`
+```ruby
+Yopt::None.zip Option.[42] # None
+Option.[42].zip Yopt::None # None
+Option.[42].zip Option.[0], Yopt::None, Option.[-1] # None
+```
+
+When both the caller and all the arguments are defined then `zip` collects all the values in an Array wrapped in a `Yopt::Some`
+
+```ruby
+Option.[42].zip Option.[0], Option.["str"] # Some([42, 0, "str"])
+```
+
+
+### #grep
+We often find ourselves filtering data before applying a transformation...
+
+```ruby
+opt.filter {|v| (1...10).include? v}.map {|v| v + 1}
+```
+
+In this scenario, `Option#grep` can sometimes make the code more concise
+
+```ruby
+opt.grep(1...10) {|v| v + 1}
+```
+
+`Option#grep` supports lambdas as well
+
+```ruby
+is_positive = lambda {|x| x > 0}
+
+opt.grep(is_positive) {|v| Math.log(v)}
+# is equivalent to
+opt.filter(&is_positive).map {|v| Math.log(v)}
+```
+
+
+## Haskell Data.Maybe cheat sheet
+
+Some (None?) might enjoy a comparison with Haskell's [Maybe](https://hackage.haskell.org/package/base/docs/Data-Maybe.html). Here is how the Data.Maybe API translate to Yopt.
+```ruby
+maybe default f opt     -> opt.map(&f).get_or_else(default)
+isJust opt              -> not opt.empty?
+isNothing opt           -> opt.empty?
+fromJust opt            -> opt.get
+fromMaybe default opt   -> opt.get_or_else default
+listToMaybe list        -> Option.ary_to_type list
+maybeToList opt         -> opt.to_a
+catMaybes listOfOptions -> listOfOptions.flatten
+mapMaybe f list         -> list.flat_map &f
+```
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/lbarasti/yopt. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/docs/basics.rb

@@ -0,0 +1,37 @@
+require_relative '../test/test_helper' # IGNORE
+# IGNORE
+require 'test/unit' # IGNORE
+include Test::Unit::Assertions # IGNORE
+# IGNORE
+class Cache < Hash
+  def maybe_get key
+    Yopt::Option[self[key]]
+  end
+
+  def store_if_some key, opt_value
+    opt_value.each {|value| self.store(key, value)}
+  end
+end
+
+def maybe_sqrt value
+  opt = Yopt::Option[value]
+  opt.select {|value| value >= 0}
+    .map {|value| Math.sqrt(value)}
+end
+
+def get_info cache, key
+  cache.maybe_get(key)
+    .map {|value| "found value %.2f for key %s" % [value, key]}
+    .get_or_else "value not found for key #{key}"
+end
+
+cache = Cache.new
+
+cache.store_if_some 42, maybe_sqrt(42)
+
+key = 42 + rand(2) # could be either 42 or 43
+
+puts get_info(cache, key)
+# IGNORE
+same_string(cache.maybe_get(key)).(Yopt::Some.new(Math.sqrt(42)).to_s) if key == 42 # IGNORE
+same_string(cache.maybe_get(key)).(Yopt::None.to_s) if key != 42 # IGNORE

data/docs/enumerable_methods.md

@@ -0,0 +1,21 @@
+## About Enumerable methods
+By including `Enumerable`, `Option` gives access to a set of methods which are either redundant or not really meaningful for a `Some` or a `None` object
+
+```ruby
+:slice_after :slice_before :slice_when :take :take_while :drop :drop_while :chunk :sort_by :each_entry :each_slice :group_by :minmax_by :sort :each_with_index :partition :find_all :max_by :min_by :reverse_each :each_cons :min :max :minmax
+```
+
+On the other hand, all the methods returning a boolean work as expected
+```ruby
+:all? :any? :include? :none? :one? :member?
+```
+
+The following methods work in a predictable way out-of-the-box
+```ruby
+:reduce :inject :each_with_object :cycle :to_set :find_index :find :detect :first :count :to_a :entries :to_h
+```
+
+While the following methods have custom definition to always return an `Option` rather than an `Array`
+```ruby
+:collect :map :flat_map :collect_concat :reject :select :zip :grep
+```

data/docs/full_example_snippet.rb

@@ -0,0 +1,51 @@
+require_relative '../test/test_helper' # IGNORE
+# IGNORE
+require 'test/unit' # IGNORE
+include Test::Unit::Assertions # IGNORE
+
+name2phone = [[:a, "+1 310-000-001"],
+              [:b, "+1 323-000-002"],
+              [:d, "+1 310-000-003"],
+              [:e, "+1 213-000-004"],
+              [:f, "+1 323-000-005"],
+              [:h, "+1 213-000-006"],
+              [:k, "+1 213-000-007"],
+              [:s, "+1 310-000-009"],
+              [:w, "+1 800-000-010"]]
+
+phone2postcode = [["+1 310-000-001", "CA 90210"],
+                  ["+1 310-000-003", "CA 90210"],
+                  ["+1 323-000-005", "CA 90028"],
+                  ["+1 213-000-006", "CA 90027"],
+                  ["+1 213-000-007", "CA 90027"],
+                  ["+1 800-000-010", "CA 91608"]]
+
+postcode2income = [["CA 90210", "$80000"],
+                  ["CA 91608", "$65000"]]
+
+
+lookup = -> (table, key) {
+  row_or_nil = table.find { |row| row.first == key }
+  Yopt::Option[row_or_nil] | :last
+}
+
+same_string( # IGNORE
+lookup.(name2phone, :s)
+).('Some(+1 310-000-009)') # COMMENT
+
+same_string( # IGNORE
+lookup.(name2phone, :x)
+).('None') # COMMENT
+
+same_string( # IGNORE
+same_string( # IGNORE
+same_string( # IGNORE
+lookup.(name2phone, :a)
+).('Some(+1 310-000-001)') # COMMENT
+  .flat_map {|phone| lookup.(phone2postcode, phone)}
+).('Some(CA 90210)') # COMMENT
+  .flat_map {|postcode| lookup.(postcode2income, postcode)}
+).('Some($80000)') # COMMENT
+
+# or if you want to go crazy-functional
+lookup.(name2phone, :a) | lookup.curry[phone2postcode] | lookup.curry[postcode2income]

data/docs/including yopt.md

@@ -0,0 +1,8 @@
+Some might find that having to specify the scope every time we want to use `Some` or `None` a bit too verbose. If that is the case, please consider that module scoping is a good receipe to avoid hideous naming clashes.
+
+If you understand the risk then you can either `include Yopt` or cherry-pick the tools you need from the module like so:
+
+```ruby
+Some = Yopt::Some
+None = Yopt::None
+```

data/docs/usage_reduce.rb

@@ -0,0 +1,12 @@
+require 'yopt'
+
+compute_increase = Yopt.lift {|user| 10000 if ['Bob', 'Joe', 'Eve'].member?(user)}
+
+base_salary = 20000
+user = ['Noel', 'Eve'].sample
+salary_increase_opt = compute_increase.(user) # None | Some(10000)
+
+salary_increase_opt.reduce(base_salary, &:+) # 20000 | 30000
+# is equivalent to
+salary_increase_opt.map{|increase| base_salary + increase} # None | Some(30000)
+                   .get_or_else(base_salary) # 20000 | 30000

data/docs/usage_snippet.rb

@@ -0,0 +1,77 @@
+require_relative '../test/test_helper' # IGNORE
+# IGNORE
+require 'test/unit' # IGNORE
+include Test::Unit::Assertions # IGNORE
+
+# You can create an option from any object `obj`
+# In general, any object gets wrapped into a `Some` instance
+some = Yopt::Option[42] # Some(42)
+# The only exception being `nil`, which turns into `None`
+none = Yopt::Option[nil] # None
+
+# since Some and None have the same API, let's choose one of the two
+# randomly, and record the intermediate result of each computation
+# for both None and Some(42) following the convention <result_if_none> | <result_if_some>
+opt = [none, some].sample
+
+opt                  # None | Some(42)
+  .select{|x| x > 0} # None | Some(42)
+  .map(&:succ)       # None | Some(43)
+  .get_or_else(1)    # 1    | 43
+
+# Calling select/reject on a Some instance can return None
+# Whereas a None can never be transformed into a Some
+                        # None | Some(42)
+opt.select{ |x| x < 0 } # None | None
+
+# One of the perks of working with options is that it allow us to stay
+# away from `nil` and `if` statements. You can still revert to using them if you need to though
+# There always is a better way to go though.
+opt.or_nil # nil | 42
+# Even better, if the option is None we can return a default value straight away
+opt.get_or_else 31 # 31 | 42
+
+# If we intend to stay in the Option domain for some more time we can swap None with an other Option
+opt.or_else(Yopt::Option[61]) # Some(61) | Some(42)
+   .reject(&:even?)           # Some(61) | None
+   .get_or_else 0             # 61       | 0
+
+# Once in the Option domain, it's nice to avoid accessing
+# the content of an option explicitly as far as possible.
+# You might eventually need to extract the value wrapped by
+# Option.
+begin     # None                  | Some(42)
+  opt.get # raises a RuntimeError | 42
+rescue RuntimeError
+  puts "cannot call #get on #{opt}"
+end
+
+# This does not look safe. Luckily we can check if the option
+# is None by calling `empty?` on it
+opt.empty? # true | false
+
+
+# v = s2.reduce(2){|default, opt_val| opt_val - default} # 47
+# n = Yopt::Some.new(v) # Some(47)
+#   .collect{|x| if x % 2 == 1 then x + 1 end} # None
+#   .map{|x| x ** 2} # None
+
+# if s1.reduce(s2.get, &:-) < 0 && s1.include?(42) # true
+#   s2.collect{ n.empty? && n } # Some(None)
+#     .flatten # None
+#     .or_nil # nil
+# end
+# head_opt = Util.lift &:first
+# old_school_validate = -> email {if email.end_with?('my-domain.com') then email else nil end}
+# valid = 'user@my-domain.com'
+# invalid = '@gmail.com'
+# old_school_validate.(invalid).must_equal nil
+# old_school_validate.(valid).wont_be_nil
+# old_school_validate.(valid).must_equal valid
+
+# brand_new_validate = Util.lift &old_school_validate
+# brand_new_validate.(invalid).must_equal None
+# brand_new_validate.(valid).must_equal Some.new(valid)
+
+# user = brand_new_validate.(valid) | Util.lift{|email| email.split('@')[0]} | :upcase
+# user.get.must_equal "USER"

data/docs/usage_zip.rb

@@ -0,0 +1,30 @@
+require_relative '../test/test_helper' # IGNORE
+# IGNORE
+require 'test/unit' # IGNORE
+include Test::Unit::Assertions # IGNORE
+
+validate_email = Yopt.lift {|x| x if x.end_with? "@domain.com"}
+validate_password = Yopt.lift {|x| x if x.size > 8}
+hash_f = lambda {|str| str.each_char.map(&:ord).reduce(:+)}
+
+# returns Yopt::Some(Fixnum) if email and password are both valid
+# returns Yopt::None otherwise
+hash_credentials = -> (email, password) do
+    maybe_email    = validate_email.(email)
+    maybe_password = validate_password.(password)
+
+    maybe_email.zip(maybe_password)
+               .map {|(valid_email, valid_pass)| hash_f.(valid_email + valid_pass)}
+end
+
+same_string( # IGNORE
+hash_credentials.('invalid_mail', 'valid_pass')
+).('None') # COMMENT
+# IGNORE
+same_string( # IGNORE
+hash_credentials.('valid@domain.com', 'invalid')
+).('None') # COMMENT
+# IGNORE
+same_string( # IGNORE
+hash_credentials.('valid@domain.com', 'valid_pass')
+).('Some(2651)') # COMMENT

data/lib/yopt.rb

@@ -0,0 +1,88 @@
+require 'yopt/version'
+
+module Yopt
+  def self.lift &block
+    block or raise ArgumentError, 'missing block'
+    -> (*args, &other_block) {Option.(block.call *args, &other_block)}
+  end
+  module Option
+    include Enumerable
+    def self.ary_to_type value
+      raise Option.invalid_argument('an array-like object', value) unless value.respond_to? :to_ary
+      return value if value.is_a? Option
+      if value.to_ary.empty? then None else Some.new(value.to_ary.first) end
+    end
+    def self.call(value)
+      if value.nil? then None else Some.new(value) end
+    end
+    singleton_class.send(:alias_method, :[], :call)
+    def each &block
+      to_ary.each &block
+    end
+    %i(map flat_map select reject collect collect_concat).each do |method|
+      define_method method, ->(&block) {
+        block or return enum_for(method)
+        Option.ary_to_type super(&block)
+      }
+    end
+    def grep(pattern, &block)
+      Option.ary_to_type super
+    end
+    def flatten
+      return self if empty?
+      Option.ary_to_type self.get
+    end
+    def zip *others
+      return None if self.empty? || others.any?(&:empty?)
+      collection = others.reduce(self.to_a, &:concat)
+      Some.new collection
+    end
+    def | lambda
+      self.flat_map &lambda # slow but easy to read + supports symbols out of the box
+    end
+    def ^ lambda
+      self | Yopt.lift(&lambda)
+    end
+    def or_else other
+      raise Option.invalid_argument('an Option', other) unless other.is_a? Option
+      if empty? then other else self end
+    end
+    def get_or_else default
+      if empty? then default else self.get end
+    end
+    def or_nil
+      get_or_else nil
+    end
+    def inspect() to_s end
+    private
+    def self.invalid_argument type_str, arg
+      TypeError.new "Argument must be #{type_str}. Found #{arg.class}"
+    end
+  end
+  class Some
+    include Option
+    def initialize value
+      @value = value.freeze
+    end
+    def get() @value end
+    def empty?() false end
+    def to_s() "Some(#{get})" end
+    def to_ary() [get] end
+    def == other
+      other.is_a?(Some) && self.get == other.get
+    end
+    def === other
+      other.is_a?(Some) && self.get === other.get
+    end
+  end
+
+  class NoneClass
+    include Option
+    def get() raise "Cannot call ##{__method__} on #{self}" end
+    def empty?() true end
+    def to_s() 'None' end
+    def to_ary() [] end
+  end
+
+  None = NoneClass.new
+end

data/lib/yopt/version.rb

@@ -0,0 +1,3 @@
+module Yopt
+  VERSION = "0.1.0"
+end

data/yopt.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'yopt/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "yopt"
+  spec.version       = Yopt::VERSION
+  spec.authors       = ["lorenzo.barasti"]
+
+  spec.summary       = %q{Scala-inspired Options for the idiomatic Rubyist.}
+  spec.description   = %q{This gem makes it possible to adopt the Option pattern in Ruby. It's meant to make conditional flow in our software clearer and more linear.}
+  spec.homepage      = "https://github.com/lbarasti/yopt"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest"
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: yopt
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- lorenzo.barasti
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-01-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  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: This gem makes it possible to adopt the Option pattern in Ruby. It's
+  meant to make conditional flow in our software clearer and more linear.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- docs/README.template.md
+- docs/basics.rb
+- docs/enumerable_methods.md
+- docs/full_example_snippet.rb
+- docs/including yopt.md
+- docs/usage_reduce.rb
+- docs/usage_snippet.rb
+- docs/usage_zip.rb
+- lib/yopt.rb
+- lib/yopt/version.rb
+- yopt.gemspec
+homepage: https://github.com/lbarasti/yopt
+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: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Scala-inspired Options for the idiomatic Rubyist.
+test_files: []
+has_rdoc: