street_fighter 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5a8abf322ddc7f9c321a74ea7697ffa0c0c3840f
+  data.tar.gz: a2324b2325d2011fa8bddb87fd0ebc25bb794818
+SHA512:
+  metadata.gz: 655589510bd1f2775a15ea1520ae2b98510da2bb43283727fc4f6e94bc81de9cc146165d49c7232ab22a4dc6e1df4ed6d4407dc57ead3dd8531f417b4a739907
+  data.tar.gz: 5ea862dca8f4d1c533c4075d56abac0876faf091e50a6730c75070d91be6b11af95e495f980d52e3f7d6c3128bb7583d382424839f827c4b5d7e3b5e08529fe8

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in ruby_ukanren.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Stack Builders Inc.
+
+MIT License
+
+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,105 @@
+# StreetFighter - better error handling for Ruby
+
+This library helps to avoid the code smell of "cascading conditionals" (otherwise known as the StreetFighter anti-pattern) by using providing an "Either" data type and interface to your program.
+
+![The StreetFighter anti-pattern as seen in PHP](images/streetfighter.jpg)
+
+_Image from [Paul Dragoonis](https://twitter.com/dr4goonis/status/476617165463105536)._
+
+## Example
+
+In the game Street Fighter, the hero, Ryu, must defeat 10 opponents. We'll just list three for demonstration:
+
+* Retsu (Japan), who has powers including the flying kick and sweep
+* Geki (Japan), who throws ninja stars and is able to teleport
+* Joe (USA), who can do a power kick and low kick
+
+_Player info from [Strategy Wiki](http://strategywiki.org/wiki/Street_Fighter/Opponents)._
+
+Let's say that Ryu must fight the three opponents above in sequence. He continues battling until he is defeated or he defeats all three opponents. As the game programmer, you must either return a structure representing Ryu, unscathed at the end of the fights, or you must return the opponent who defeated Ryu.
+
+A first attempt at modeling this problem may look as follows. We assume there is a function called `battle` that returns the winner of a particular fight. Note the "Street Fighter anti-pattern":
+
+```ruby
+def fight
+  if ryu == battle(ryu, retsu)
+    if ryu == battle(ryu, geki)
+      if ryu == battle(ryu, joe)
+        ryu
+      else
+        joe
+      end
+    else
+      geku
+    end
+  else
+    retsu
+  end
+end
+```
+
+It's hard to read, let alone verify that this logic is consistent with the game requirements. Let's try it using the StreetFighter gem. First, we'll create a structure to represent the tournamenters. For now, a simple Struct with a name and a boolean representing whether they're the hero or opponent will suffice:
+
+```ruby
+Player = Struct.new(:name, :hero)
+```
+
+Let's define the hero and three opponents:
+
+```ruby
+ryu   = Player.new(:ryu, true)    # The hero!
+
+# The bad guys.
+retsu = Player.new(:retsu, false)
+geki  = Player.new(:geki,  false)
+joe   = Player.new(:joe,   false)
+
+```
+
+And the fighting function:
+
+```ruby
+# Perform a random battle, giving the hero 3 chances to win to every
+# 1 chance for the opponent. We must return the winner wrapped in a `Left`
+# if the winner is the opponent, or a `Right` if the winner is our hero.
+def battle(opponent, hero)
+  winner = ([hero] * 3 << opponent).sample
+  winner.hero ? StreetFighter::Right.new(winner) :
+                StreetFighter::Left.new(winner)
+end
+```
+
+Finally we define the rounds of the game. We're going to use [currying](http://en.wikipedia.org/wiki/Currying) here
+so that we can apply an opponent to each battle, and wind up with a partially-applied function. Essentially, each partially-applied function can be thought of as an opponent angrily waiting until he has the opportunity to try to do serious damage to our hero, Ryu.
+
+```ruby
+fight = method(:battle).to_proc.curry
+```
+
+I hope you're ready - the fight is about to begin!
+
+```ruby
+winner = StreetFighter.tournament(ryu, fight[retsu], fight[geki], fight[joe])
+```
+
+All that's left is to see the results. Having the result of the computation wrapped in an `EitherValue` (`Right` or `Left`) facilitates using a simple case statement on the return value:
+
+```ruby
+case winner
+when StreetFighter::Left
+  puts "Our hero has been defeated, and #{winner.value.name} is the new champion."
+when StreetFighter::Right
+  puts "Ryu has defeated his opponents!"
+end
+```
+
+Fortunately, the output is:
+
+    Ryu has defeated his opponents!
+
+Not only has Ryu won this round, but we've completely defeated the cascading conditionals by applying some easy-to-use functional patterns. If you'd like to tournament around with the game and see if Ryu keeps up his winning streak, [it's a part of the test suite for this library](spec/street_fighter/street_fighter_game_spec.rb).
+
+## Credits
+
+Thanks to [Paul Dragoonis](https://twitter.com/dr4goonis) for [identifying
+this anti-pattern and giving us a great graphical illustration of the beast in the wild](https://twitter.com/dr4goonis/status/476617165463105536).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << "spec"
+  t.test_files = FileList['spec/**/*_spec.rb']
+end
+
+task :default => :test

data/lib/street_fighter.rb

@@ -0,0 +1,13 @@
+require 'street_fighter/version'
+
+require 'street_fighter/either_value'
+require 'street_fighter/right'
+require 'street_fighter/left'
+require 'street_fighter/either'
+require 'street_fighter/either_check'
+
+module StreetFighter
+  def self.tournament(hero, *opponents)
+    Right.new(hero).tournament(*opponents)
+  end
+end

data/lib/street_fighter/either.rb

@@ -0,0 +1,10 @@
+module StreetFighter
+  class Either
+    attr_reader :left, :right
+
+    def initialize left_value, right_value
+      @left  = Left.new(left_value)
+      @right = Right.new(right_value)
+    end
+  end
+end

data/lib/street_fighter/either_check.rb

@@ -0,0 +1,6 @@
+module StreetFighter
+  class EitherCheck < Struct.new(:klass)
+    def run! ; raise ArgumentError unless klass.is_a?(EitherValue) ; end
+  end
+end
+

data/lib/street_fighter/either_value.rb

@@ -0,0 +1,25 @@
+module StreetFighter
+  class EitherValue
+    attr_reader :value
+
+    def initialize value
+      @value = value
+    end
+
+    def match # (>>) in Haskell
+      raise NotImplementedError, "Follows not implemented here."
+    end
+
+    def bind # (>>=) in Haskell
+      raise NotImplementedError, "Bind not implemented here."
+    end
+
+    def failable # `fmap` in Haskell, but restricted to EitherValues
+      raise NotImplementedError, "Bind not implemented here."
+    end
+
+    def ==(other)
+      self.value == other.value
+    end
+  end
+end

data/lib/street_fighter/left.rb

@@ -0,0 +1,17 @@
+module StreetFighter
+  class Left < EitherValue
+    def match other # >> (then)
+      EitherCheck.new(other).run!
+      self
+    end
+
+    def tournament *fns
+      self
+    end
+
+    def bind func
+      self
+    end
+  end
+end
+

data/lib/street_fighter/right.rb

@@ -0,0 +1,20 @@
+module StreetFighter
+  class Right < EitherValue
+    def match other
+      EitherCheck.new(other).run!
+      other
+    end
+
+    def tournament *fns
+      return self if fns.empty?
+
+      bind(fns.first).tap do |result|
+        EitherCheck.new(result).run!
+      end.tournament(*fns[1..-1])
+    end
+
+    def bind func
+      func.call(value)
+    end
+  end
+end

data/lib/street_fighter/version.rb

@@ -0,0 +1,3 @@
+module StreetFighter
+  VERSION = "0.0.1"
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+require 'minitest/autorun'
+
+require "#{File.dirname(__FILE__)}/../lib/street_fighter"
+
+include StreetFighter

data/spec/street_fighter/failable_spec.rb

@@ -0,0 +1,56 @@
+require 'spec_helper'
+
+module StreetFighter
+  describe "#match" do
+    it "returns the first Left after a sequence of Right values" do
+      Left.new("first").match(Right.new("second")).
+        must_equal Left.new("first")
+    end
+
+    it "returns a Right if all values in the sequence are Right" do
+      Right.new("first").match(Right.new("second")).
+        must_equal Right.new("second")
+    end
+  end
+
+  describe "binding and mapping over failable tests" do
+
+    # The basic data structure we'll be testing is a Person.
+    Person = Struct.new(:name, :age)
+
+    # A helper method that returns a value wrapped in an Either based on the
+    # boolean test.
+    def failable_test person, bool, msg
+      bool ? Right.new(person) : Left.new(msg)
+    end
+
+    def bob? person
+      failable_test person, person.name == 'Bob', 'The name should have been Bob!'
+    end
+
+    def old_enough? person
+      failable_test person, person.age >= 21, 'Person is not old enough!'
+    end
+
+    describe "#bind" do
+      it "returns the Right value if the function is successful" do
+        bob = Person.new("Bob", 22)
+        valid_age  = method(:old_enough?)
+
+        bob?(bob).bind(valid_age).must_equal(Right.new(bob))
+      end
+
+      it "returns the first Left value encountered in a sequence" do
+        bob = Person.new("Tom", 22)
+        valid_age  = method(:old_enough?)
+
+        bob?(bob).bind(valid_age).
+          must_equal(Left.new("The name should have been Bob!"))
+      end
+    end
+
+  end
+
+end
+
+

data/spec/street_fighter/street_fighter_game_spec.rb

@@ -0,0 +1,38 @@
+require 'spec_helper'
+
+describe "tournamenting a game of street fighter" do
+
+  Player = Struct.new(:name, :hero)
+
+  # Perform a random battle, giving the hero 3 chances to win to every
+  # 1 chance for the opponent. We must return the winner wrapped in a `Left`
+  # if the winner is the opponent, or a `Right` if the winner is our hero.
+  def battle(opponent, hero)
+    winner = ([hero] * 3 << opponent).sample
+    winner.hero ? StreetFighter::Right.new(winner) :
+                  StreetFighter::Left.new(winner)
+  end
+
+
+  it "always returns a Left or a Right value" do
+    ryu   = Player.new(:ryu, true)    # The hero!
+
+    # The bad guys.
+    retsu = Player.new(:retsu, false)
+    geki  = Player.new(:geki,  false)
+    joe   = Player.new(:joe,   false)
+
+    fight = method(:battle).to_proc.curry
+
+    winner = StreetFighter.tournament(ryu, fight[retsu], fight[geki], fight[joe])
+
+    # case winner
+    # when StreetFighter::Left
+    #   puts "Our hero has been defeated, and #{winner.value.name} is the new champion."
+    # when StreetFighter::Right
+    #   puts "Ryu has defeated his opponents!"
+    # end
+
+    winner.must_be_kind_of StreetFighter::EitherValue
+  end
+end

data/spec/street_fighter_spec.rb

@@ -0,0 +1,23 @@
+require 'spec_helper'
+
+describe StreetFighter do
+  it "returns the final Right value if sequence only results in Rights" do
+    fight1 = Proc.new{|_| Right.new("hey") }
+    fight2 = Proc.new{|_| Right.new("hey") }
+
+    StreetFighter.tournament(Object.new, fight1, fight2).
+      must_equal Right.new("hey")
+  end
+
+  it "returns the first Left value if a computation fails in the sequence" do
+    fight1 = Proc.new{|_| Right.new("hey") }
+    fight2 = Proc.new{|_| Left.new("fail!") }
+
+    StreetFighter.tournament(Object.new, fight1, fight2).must_equal Left.new("fail!")
+  end
+
+  it "raises an ArgumentError if the function doesn't return an EitherValue" do
+    proc { StreetFighter.tournament(Object.new, Proc.new{ Object.new }) }.
+      must_raise ArgumentError
+  end
+end

data/street_fighter.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'street_fighter/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "street_fighter"
+  spec.version       = StreetFighter::VERSION
+  spec.authors       = ["Justin Leitgeb"]
+  spec.email         = ["support@stackbuilders.com"]
+  spec.summary       = %q{An implementation of an Either monad in Ruby}
+  spec.description   = %q{Implements an Either monad in Ruby for cleaner error handling.}
+  spec.homepage      = "http://github.com/stackbuilders/street_fighter"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake", "~> 10"
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: street_fighter
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Justin Leitgeb
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-04-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10'
+description: Implements an Either monad in Ruby for cleaner error handling.
+email:
+- support@stackbuilders.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- images/streetfighter.jpg
+- lib/street_fighter.rb
+- lib/street_fighter/either.rb
+- lib/street_fighter/either_check.rb
+- lib/street_fighter/either_value.rb
+- lib/street_fighter/left.rb
+- lib/street_fighter/right.rb
+- lib/street_fighter/version.rb
+- spec/spec_helper.rb
+- spec/street_fighter/failable_spec.rb
+- spec/street_fighter/street_fighter_game_spec.rb
+- spec/street_fighter_spec.rb
+- street_fighter.gemspec
+homepage: http://github.com/stackbuilders/street_fighter
+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.2.2
+signing_key: 
+specification_version: 4
+summary: An implementation of an Either monad in Ruby
+test_files:
+- spec/spec_helper.rb
+- spec/street_fighter/failable_spec.rb
+- spec/street_fighter/street_fighter_game_spec.rb
+- spec/street_fighter_spec.rb
+has_rdoc: