wrapped 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 873be12f072d8e7e8a013579ab7e24abbfca1df4
-  data.tar.gz: 00b05e0b222ebe45887f5ed05ce3d2fa19d17edf
+  metadata.gz: ef031daae3bfd8056b4b709aa3a500ac7197e541
+  data.tar.gz: 70978101ccd2d40c521e4dffd6d9f6420a9edb71
 SHA512:
-  metadata.gz: 16409b545b1897b69f748e239f432509aa95a13a927713a7c86d6219b6411afcf96406b973cc38c4e6941a322da01d23a42728ecc3730ee26aafd1536c229d74
-  data.tar.gz: 303cd24a0f03dc9ba83d94c7725a2990c8598b797e3ab1ca9341f45e852a078c2c98f8a3a596459d37407382423f9937187f5033d2caa18ae1cf3c9ca3d4312e
+  metadata.gz: d601312592eedffda77e3fa31e8efebfdf226ae06bd4a428213b6acda443cabc414e1af1d7fe4cd239d8abbbd7336d91c25079c0c62fdd83b7eb33b3a11a5c79
+  data.tar.gz: 1a8d7a800f1c17a4a1fb0f546864cace441c86c8dbb04e6ab315e9afcf38e02884831487841d8f8c7e415322e8f0ce5b9554cf5b2108820a1cecfde93b3f39c5

data/README.md

@@ -6,6 +6,13 @@ your code to find bugs earlier and faster. It works like this: any time you
 write a method that could produce nil, you instead write a method that produces
 a wrapped value.
 
+Warning: Experimental
+---------------------
+
+This library is in an early, experimental phase and may change suddenly and
+drastically. Backwards-compatibility should not be expected between releases,
+and the project may be cancelled at any time.
+
 Example
 -------
 
@@ -14,33 +21,39 @@ Here's an example along with how it can help with errors:
 Say you have a collection of users along with a method for accessing the first
 user:
 
-    class UserCollection
-      def initialize(users)
-        @users = users
-      end
-  
-      def first_user
-        @users.first
-      end
-    end
+```ruby
+class UserCollection
+  def initialize(users)
+    @users = users
+  end
+
+  def first_user
+    @users.first
+  end
+end
+```
 
 Now your friend uses your awesome UserCollection code:
 
-    class FriendGroups
-      def initialize(user_collections)
-        @user_collections = user_collections
-      end
+```ruby
+class FriendGroups
+  def initialize(user_collections)
+    @user_collections = user_collections
+  end
 
-      def first_names
-        @user_collections.map do |user_collection|
-          user_collection.first_user.first_name
-        end
-      end
+  def first_names
+    @user_collections.map do |user_collection|
+      user_collection.first_user.first_name
     end
+  end
+end
+```
 
 And then she tries it:
 
-    FriendGroups.new([UserCollection.new([])]).first_names
+```ruby
+FriendGroups.new([UserCollection.new([])]).first_names
+```
 
 ... and it promptly blows up:
 
@@ -59,15 +72,17 @@ Right.
 Instead what you want to do is wrap it. Wrap that nil. Make the user know that
 they have to consider the result.
 
-    class UserCollection
-      def initialize(users)
-        @users = users
-      end
-  
-      def first_user
-        @users.first.wrapped
-      end
-    end
+```ruby
+class UserCollection
+  def initialize(users)
+    @users = users
+  end
+
+  def first_user
+    @users.first.wrapped
+  end
+end
+```
 
 Now in your documentation you explain that it produces a wrapped value. And
 people who skip documentation and instead read source code will see that it is
@@ -76,17 +91,19 @@ wrapped.
 So they unwrap it, because they must. They can't even get a happy path without
 unwrapping it.
 
-    class FriendGroups
-      def initialize(user_collections)
-        @user_collections = user_collections
-      end
+```ruby
+class FriendGroups
+  def initialize(user_collections)
+    @user_collections = user_collections
+  end
 
-      def first_names
-        @user_collections.map do |user_collection|
-          user_collection.first_user.unwrap_or('') {|user| user.first_name }
-        end
-      end
+  def first_names
+    @user_collections.map do |user_collection|
+      user_collection.first_user.unwrap_or('') {|user| user.first_name }
     end
+  end
+end
+```
 
 Cool Stuff
 ----------
@@ -99,15 +116,19 @@ wrapped value. By wrapping it you've just made it more powerful!
 
 For example:
 
-    irb(main):054:0> 1.wrapped.inject(0) {|_, n| n+1}
-    => 2
-    irb(main):055:0> nil.wrapped.inject(0) {|_, n| n+1}
-    => 0
+```ruby
+irb(main):054:0> 1.wrapped.inject(0) {|_, n| n+1}
+=> 2
+irb(main):055:0> nil.wrapped.inject(0) {|_, n| n+1}
+=> 0
+```
 
 And then we have `flat_map`, which you can use to produce another wrapped object:
 
-    irb> 1.wrapped.flat_map {|n| (n + 1).wrapped}.flat_map {|n| (n*2).wrapped}.unwrap
-    => 4
+```ruby
+irb> 1.wrapped.flat_map {|n| (n + 1).wrapped}.flat_map {|n| (n*2).wrapped}.unwrap
+=> 4
+```
 
 Those same people who will exclaim things about functors will, at this point,
 get giddy about monads. I mean, they're right, but they can relax. It's just a
@@ -116,44 +137,51 @@ monad.
 Those people ("what do you mean, 'those people'?!") may prefer the `fmap`
 method:
 
-    irb> 1.wrapped.fmap {|n| n+1}.unwrap_or(0) {|n| n+4}
-    => 6
+```ruby
+irb> 1.wrapped.fmap {|n| n+1}.unwrap_or(0) {|n| n+4}
+=> 6
+```
 
 Other Methods
 -------------
 
 Then we added some convenience methods to all of this. Here's a tour:
 
-    irb> require 'wrapped'
-    => true
-    irb> 1.wrapped.unwrap_or(-1)
-    => 1
-    irb> nil.wrapped.unwrap_or(-1)
-    => -1
-    irb> 1.wrapped.present {|n| p n }.blank { puts "nothing!" }
-    1
-    => #<Present:0x7fc570aed0e8 @value=1>
-    irb> nil.wrapped.present {|n| p n }.blank { puts "nothing!" }
-    nothing!
-    => #<Blank:0x7fc570ae21c0>
-    irb> 1.wrapped.unwrap
-    => 1
-    irb> nil.wrapped.unwrap
-    IndexError: Blank has no value
-    	from /home/mike/wrapped/lib/wrapped/types.rb:43:in `unwrap'
-    	from (irb):7
-    irb> 1.wrapped.present?
-    => true
-    irb> nil.wrapped.present?
-    => false
-    irb> nil.wrapped.blank?
-    => true
-    irb> 1.wrapped.blank?
-    => false
-    irb> 1.wrapped.unwrap_or(0) {|n| n * 100}
-    => 100
-    irb> nil.wrapped.unwrap_or(0) {|n| n * 100}
-    => 0
+```ruby
+irb> require 'wrapped'
+=> true
+irb> 1.wrapped.unwrap_or(-1)
+=> 1
+irb> nil.wrapped.unwrap_or(-1)
+=> -1
+irb> 1.wrapped.present {|n| p n }.blank { puts "nothing!" }
+1
+=> #<Present:0x7fc570aed0e8 @value=1>
+irb> nil.wrapped.present {|n| p n }.blank { puts "nothing!" }
+nothing!
+=> #<Blank:0x7fc570ae21c0>
+irb> 1.wrapped.unwrap
+=> 1
+irb> nil.wrapped.unwrap
+IndexError: Blank has no value
+	from /home/mike/wrapped/lib/wrapped/types.rb:43:in `unwrap'
+	from (irb):7
+```
+
+```ruby
+irb> 1.wrapped.present?
+=> true
+irb> nil.wrapped.present?
+=> false
+irb> nil.wrapped.blank?
+=> true
+irb> 1.wrapped.blank?
+=> false
+irb> 1.wrapped.unwrap_or(0) {|n| n * 100}
+=> 100
+irb> nil.wrapped.unwrap_or(0) {|n| n * 100}
+=> 0
+```
 
 Inspiration
 -----------
@@ -166,4 +194,4 @@ functor or the option class for more.
 
 Copyright
 ---------
-Copyright 2011 - 2014 Mike Burns, Joe Ferris
+Copyright 2011 Mike Burns. Copyright 2014 thoughtbot.

data/lib/wrapped/blank.rb

@@ -10,8 +10,12 @@ class Blank
   # Produce the value that is passed in.
   #
   # > w.unwrap_or(0)
-  def unwrap_or(default)
-    default
+  def unwrap_or(default = nil)
+    if block_given?
+      yield
+    else
+      default
+    end
   end
 
   # Does nothing, returning itself. This is chainable. See blank for its
@@ -37,7 +41,24 @@ class Blank
   #
   # > w.each {|n| puts n }
   def each
-    []
+    self
+  end
+
+  # Produces itself.
+  def select
+    self
+  end
+
+  alias_method :find_all, :select
+
+  # Produces itself.
+  def reject
+    self
+  end
+
+  # Produces itself.
+  def grep(*)
+    self
   end
 
   # False; this is not an instance of a wrapped value.
@@ -64,12 +85,15 @@ class Blank
     self
   end
 
+  alias_method :collect, :fmap
+  alias_method :map, :fmap
+
   # Is this wrapped value equal to the given wrapped value? All blank values
   # are equal to each other.
   #
   # > nil.wrapped == nil.wrapped
   # > 1.wrapped == nil.wrapped
   def ==(other)
-    other.blank?
+    other.is_a?(Blank)
   end
 end

data/lib/wrapped/present.rb

@@ -14,12 +14,8 @@ class Present
   #
   # > w.unwrap_or(0)
   # > w.unwrap_or("hello") {|s| "Hi, #{s}" }
-  def unwrap_or(_)
-    if block_given?
-      yield unwrap
-    else
-      unwrap
-    end
+  def unwrap_or(_default = nil)
+    unwrap
   end
 
   # Invoke the block on the value, unwrapped. This method produces the wrapped
@@ -39,7 +35,7 @@ class Present
     self
   end
 
-  # Produce the singleton list with the unwrapped value as its only member.
+  # Produces itself.
   #
   # If a block is passed, it is run against the unwrapped value.
   #
@@ -48,7 +44,27 @@ class Present
   # > w.each {|n| puts "Found #{n}" }
   def each
     yield unwrap if block_given?
-    [unwrap]
+    self
+  end
+
+  # Produces itself if the block evaluates to true. Produces Blank if the block
+  # evaluates to false.
+  def select
+    super.first.wrapped
+  end
+
+  alias_method :find_all, :select
+
+  # Produces itself if the block evaluates to false. Produces Blank if the block
+  # evaluates to true.
+  def reject
+    super.first.wrapped
+  end
+
+  # Produces itself if the unwrapped value matches the given expression.
+  # Produces Blank otherwise.
+  def grep(*)
+    super.first.wrapped
   end
 
   # The raw value. I doubt you need this method.
@@ -84,14 +100,17 @@ class Present
   #
   # This makes it a functor.
   def fmap
-    (yield unwrap).wrapped
+    Present.new(yield unwrap)
   end
 
+  alias_method :collect, :fmap
+  alias_method :map, :fmap
+
   # Is this wrapped value equal to the given wrapped value?
   #
   # > 1.wrapped == 1.wrapped
   # > nil.wrapped == 2.wrapped
   def ==(other)
-    unwrap == other.unwrap_or(nil)
+    other.is_a?(Present) && unwrap == other.unwrap_or(nil)
   end
 end

data/lib/wrapped/version.rb

@@ -1,3 +1,3 @@
 module Wrapped
-  VERSION = "0.0.3"
+  VERSION = "0.1.0"
 end

data/spec/spec_helper.rb

@@ -1 +1,9 @@
 require 'wrapped'
+
+RSpec::Matchers.define :be_alias_of do |source_method|
+  match do |target_method|
+    block = lambda { |n| n + 1 }
+
+    target_method.call(&block) == source_method.call(&block)
+  end
+end

data/spec/wrapped_spec.rb

@@ -8,16 +8,16 @@ describe Wrapped, 'conversion' do
   let(:delegator) { SimpleDelegator.new(value).wrapped }
 
   it "converts the value to a Present" do
-    just.should be_instance_of(Present)
+    expect(just).to be_instance_of(Present)
   end
 
   it "converts the nil to a Blank" do
-    nothing.should be_instance_of(Blank)
+    expect(nothing).to be_instance_of(Blank)
   end
 
   it "converts a simple delegator to a Present" do
-    delegator.should be_instance_of(Present)
-    delegator.unwrap.should be_instance_of(SimpleDelegator)
+    expect(delegator).to be_instance_of(Present)
+    expect(delegator.unwrap).to be_instance_of(SimpleDelegator)
   end
 end
 
@@ -27,7 +27,7 @@ describe Wrapped, 'accessing' do
   let(:nothing) { nil.wrapped }
 
   it 'produces the value of the wrapped object' do
-    just.unwrap.should == value
+    expect(just.unwrap).to eq(value)
   end
 
   it 'raises an exception when called on the wrapped nil' do
@@ -43,44 +43,41 @@ describe Wrapped, 'callbacks' do
   it 'calls the proper callback for a wrapped value' do
     result = false
     just.present {|v| result = v}
-    result.should be_true
+    expect(result).to be_truthy
   end
 
   it 'calls the proper callback for a wrapped nil' do
     result = false
     nothing.blank {result = true}
-    result.should be_true
+    expect(result).to be_truthy
   end
 
   it 'ignores the other callback for a wrapped value' do
     result = true
     just.blank { result = false }
-    result.should be_true
+    expect(result).to be_truthy
   end
 
 
   it 'ignores the other callback for a wrapped nil' do
     result = true
     nothing.present { result = false }
-    result.should be_true
+    expect(result).to be_truthy
   end
 
   it 'chains for wrapped values' do
     result = false
     just.present { result = true }.blank { result = false }
-    result.should be_true
+    expect(result).to be_truthy
   end
 
   it 'chains for wrapped nils' do
     result = false
     nothing.present { result = false }.blank { result = true }
-    result.should be_true
+    expect(result).to be_truthy
   end
 end
 
-# This behavior is different from Haskell and Scala.
-# It is done this way for consistency with Ruby.
-# See the functor description later for `fmap'.
 describe Wrapped, 'enumerable' do
   let(:value)   { 1 }
   let(:just)    { 1.wrapped }
@@ -89,29 +86,75 @@ describe Wrapped, 'enumerable' do
   it 'acts over the value for #each on a wrapped value' do
     result = -1
     just.each {|v| result = v }
-    result.should == value
+    expect(result).to eq(value)
   end
 
-  it 'produces a singleton array of the value for a wrapped value on #each' do
-    just.each.should == [value]
+  it 'produces itself for #each' do
+    expect(just.each).to eq(just)
   end
 
   it 'skips the block for #each on a wrapped nil' do
     result = -1
     nothing.each {|v| result = v }
-    result.should == -1
+    expect(result).to eq(-1)
   end
 
-  it 'produces the empty array for a wrapped nil on #each' do
-    nothing.each.should be_empty
+  it 'produces blank for a wrapped nil on #each' do
+    expect(nothing.each).to eq(nothing)
   end
 
   it 'maps over the value for a wrapped value' do
-    just.map {|n| n + 1}.should == [value+1]
+    expect(just.map {|n| n + 1}).to eq((value+1).wrapped)
   end
 
-  it 'map produces the empty list for a wrapped nil' do
-    nothing.map {|n| n + 1}.should == []
+  it 'map produces blank' do
+    expect(nothing.map {|n| n + 1}).to be_instance_of(Blank)
+  end
+
+  it 'aliases map to collect' do
+    expect(just.method(:collect)).to be_alias_of(just.method(:map))
+    expect(nothing.method(:collect)).to be_alias_of(nothing.method(:map))
+  end
+
+  it 'select produces present for a value matching the block' do
+    expect(just.select { |n| n == value }).to eq(just)
+  end
+
+  it 'select produces blank for a value that does not match the block' do
+    expect(just.select { |n| n != value }).to be_instance_of(Blank)
+  end
+
+  it 'select products blank for a blank' do
+    expect(nothing.select { true }).to be_instance_of(Blank)
+  end
+
+  it 'aliases select to find_all' do
+    expect(just.method(:find_all)).to be_alias_of(just.method(:select))
+    expect(nothing.method(:find_all)).to be_alias_of(nothing.method(:select))
+  end
+
+  it 'reject produces present for a value matching the block' do
+    expect(just.reject { |n| n != value }).to eq(just)
+  end
+
+  it 'reject produces blank for a value that does not match the block' do
+    expect(just.reject { |n| n == value }).to be_instance_of(Blank)
+  end
+
+  it 'reject products blank for a blank' do
+    expect(nothing.reject { true }).to be_instance_of(Blank)
+  end
+
+  it 'grep produces present for a value matching the pattern' do
+    expect("hello".wrapped.grep(/ello$/)).to eq("hello".wrapped)
+  end
+
+  it 'grep produces blank for a value that does not match the pattern' do
+    expect("hello".wrapped.grep(/^ello/)).to be_instance_of(Blank)
+  end
+
+  it 'grep products blank for a blank' do
+    expect(nothing.grep(/.*/)).to be_instance_of(Blank)
   end
 end
 
@@ -121,13 +164,13 @@ describe Wrapped, 'queries' do
   let(:nothing) { nil.wrapped }
 
   it 'knows whether it is present' do
-    just.should be_present
-    nothing.should_not be_present
+    expect(just).to be_present
+    expect(nothing).not_to be_present
   end
 
   it 'knows whether it is blank' do
-    just.should_not be_blank
-    nothing.should be_blank
+    expect(just).not_to be_blank
+    expect(nothing).to be_blank
   end
 end
 
@@ -136,20 +179,20 @@ describe Wrapped, 'unwrap_or' do
   let(:just)    { 1.wrapped }
   let(:nothing) { nil.wrapped }
 
-  it 'produces the value for a wrapped value' do
-    just.unwrap_or(-1).should == value
+  it 'produces the value for a wrapped value with an argument' do
+    expect(just.unwrap_or(-1)).to eq(value)
   end
 
-  it 'produces the default for a wrapped nil' do
-    nothing.unwrap_or(-1).should == -1
+  it 'produces the argument for a wrapped nil with an argument' do
+    expect(nothing.unwrap_or(-1)).to eq(-1)
   end
 
-  it 'produces the value of the block for a wrapped object' do
-    just.unwrap_or(-1) {|n| n+1}.should == value + 1
+  it 'produces the value for a wrapped value with a block' do
+    expect(just.unwrap_or { value + 1 }).to eq(value)
   end
 
-  it 'produces the default for a wrapped nil even with a block' do
-    nothing.unwrap_or(-1) {2}.should == -1
+  it 'produces the block result for a wrapped nil with a block' do
+    expect(nothing.unwrap_or { 2 }).to eq(2)
   end
 end
 
@@ -159,11 +202,11 @@ describe Wrapped, 'monadic' do
   let(:nothing) { nil.wrapped }
 
   it 'produces the value from #flat_map for a wrapped value' do
-    just.flat_map {|n| (n+1).wrapped }.unwrap.should == value+1
+    expect(just.flat_map {|n| (n+1).wrapped }.unwrap).to eq(value+1)
   end
 
   it 'produces blank from #flat_map for a wrapped nil' do
-    nothing.flat_map {|n| (n+1).wrapped}.should be_blank
+    expect(nothing.flat_map {|n| (n+1).wrapped}).to be_blank
   end
 end
 
@@ -173,32 +216,69 @@ describe Wrapped, 'functor' do
   let(:nothing) { nil.wrapped }
 
   it 'unwraps, applies the block, then re-wraps for a wrapped value' do
-    just.fmap {|n| n+1}.unwrap.should == value+1
+    expect(just.fmap {|n| n+1}.unwrap).to eq(value+1)
   end
 
   it 'produces the blank for a wrapped nil' do
-    nothing.fmap {|n| n+1}.should be_blank
+    expect(nothing.fmap {|n| n+1}).to be_blank
+  end
+
+  it 'obeys the functor law: fmap id  ==  id' do
+    expect(fmap(id).(just)).to eq(id.(just))
+  end
+
+  it 'obeys the functor law: fmap (f . g)  ==  fmap f . fmap g' do
+    expect(fmap(compose(null, const(nil))).(just)).
+      to eq(compose(fmap(null), fmap(const(nil))).(just))
+  end
+
+  def fmap(f)
+    lambda { |x| x.fmap(&f) }
+  end
+
+  def const(x)
+    lambda { |_| x }
+  end
+
+  def id
+    lambda { |x| x }
+  end
+
+  def compose(f, g)
+    lambda { |x| f.call(g.call(x)) }
+  end
+
+  def null
+    lambda {|x| x.nil? }
   end
 end
 
 describe Wrapped, 'equality' do
   it 'is equal with the same wrapped value' do
-    1.wrapped.should == 1.wrapped
+    expect(1.wrapped).to eq(1.wrapped)
   end
 
   it 'is not equal with a different wrapped value' do
-    1.wrapped.should_not == 2.wrapped
+    expect(1.wrapped).not_to eq(2.wrapped)
   end
 
   it 'is equal with two wrapped nils' do
-    nil.wrapped.should == nil.wrapped
+    expect(nil.wrapped).to eq(nil.wrapped)
   end
 
   it 'is not equal with a wrapped nil and a wrapped value' do
-    nil.wrapped.should_not == 1.wrapped
+    expect(nil.wrapped).not_to eq(1.wrapped)
   end
 
   it 'is not equal with a wrapped value and a wrapped nil' do
-    1.wrapped.should_not == nil.wrapped
+    expect(1.wrapped).not_to eq(nil.wrapped)
+  end
+
+  it 'is not equal with a present value and un unwrapped value' do
+    expect(1.wrapped).not_to eq(1)
+  end
+
+  it 'is not equal with a blank value and an unwrapped value' do
+    expect(nil.wrapped).not_to eq(1)
   end
 end

data/wrapped.gemspec

@@ -16,6 +16,6 @@ Gem::Specification.new do |s|
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.require_paths = ["lib"]
 
-  s.add_development_dependency('rspec', '~> 2.3')
-  s.add_development_dependency('rake')
+  s.add_development_dependency("rspec", "~> 3.1.0")
+  s.add_development_dependency("rake")
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wrapped
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
 platform: ruby
 authors:
 - Mike Burns
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-29 00:00:00.000000000 Z
+date: 2014-11-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.3'
+        version: 3.1.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.3'
+        version: 3.1.0
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -83,8 +83,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.2
 signing_key: 
 specification_version: 4
 summary: The maybe functor for Ruby
-test_files: []
+test_files:
+- spec/spec_helper.rb
+- spec/wrapped_spec.rb