waterslide 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 301ba4b66544ec9a3c9291e2f0ca8b993881a009
+  data.tar.gz: 3267b0740f98719e6f791dccbc5b177eb0862813
+SHA512:
+  metadata.gz: 2529d565230da7c62d34593935581180b2e1c0499ee851660ac1fe66461e33d5b1fc3fd91a136131a85d617307fcaf9939934160159bddbdcadb5c42225e2a4e
+  data.tar.gz: c2c0a1baad887e297c0d8ba90680e016e0fa116209b559d760cef3a99167d7a9f6e8f47f68b39c170359b7154e6d670eea6c647ecb903deb5966406c4abc1c5a

data/.gitignore

@@ -0,0 +1,35 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Ben Christel
+
+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,170 @@
+# waterslide
+
+Unix-style pipes for Ruby programs
+
+## TL;DR
+
+```ruby
+class FacebookFriendsController < ApplicationController
+  def index
+    render json:
+        FacebookFriends.new(current_user) >>
+        DeserializeFacebookUsers >>
+        MergeWithAttributesFromDatabase >>
+        RemoveRecordsNotInDatabase >>
+        Serialize
+  end
+end
+```
+
+## Wat
+
+A common problem in programming is the need to perform a series of transformations on data. Ruby enumerables have lots of nice functional-style methods (`map`, `reduce`) to make this easy, but in some cases this approach breaks down.
+
+Let's say you're building a social app where users log in with Facebook. You want to have a page where users can see which of their Facebook friends are using your site.
+
+Doing this requires calling the Facebook API to get the current user's friends, merging the data from Facebook with the user data in your own database, filtering out the Facebook users who don't have accounts on your site, and serializing the remaining users to HTML or JSON so you can render them on your page.
+
+The usual solution might look something like this:
+
+```ruby
+Facebook.friends_of(current_user)
+  .map { |friend_datum| FacebookUserDeserializer.deserialize(friend_datum) }
+  .map { |user| user.merge_attributes User.find_by_facebook_id(user.facebook_id) }
+  .reject { |user| user.id.nil? }
+  .map { |user| UserSerializer.serialize(user) }
+```
+
+Later, you find that the page takes a long time to load for users with many facebook friends, and you isolate the problem to the O(n) `User.find_by_facebook_id` calls, most of which don't actually find a user. Fortunately, that's not hard to fix.
+
+```ruby
+facebook_friends = Facebook.friends_of(current_user).map do |friend_datum|
+  FacebookUserDeserializer.deserialize(friend_datum)
+end
+facebook_ids = facebook_friends.map(&:facebook_id)
+facebook_friends_from_database = User.where(facebook_id: facebook_ids)
+facebook_friends.map! do |friend|
+  db_record = facebook_friends_from_database.find do |db_record|
+    db_record.facebook_id == friend.facebook_id
+  end
+  friend.merge_attributes db_record
+end
+facebook_friends.map do |user|
+  UserSerializer.serialize(user)
+end
+```
+
+In making the code more efficient, its elegance has been destroyed. Now one of the `map` blocks is dependent on an invariant - the users pulled from the database - and that dependency makes the code harder to read and harder to refactor.
+
+With Waterslide, the various data transformations can easily be broken into their own classes.
+
+```ruby
+class FacebookFriends
+  include Waterslide::Pipe
+
+  def initialize(current_user)
+    @current_user = current_user
+  end
+
+  def each(&block)
+    @friends ||= Facebook.friends_of(@current_user)
+    @friends.each(&block)
+  end
+end
+
+class DeserializeFacebookUsers
+  include Waterslide::Pipe
+
+  def pipe_one(user_json)
+    yield User.new#( ... )
+  end
+end
+
+class MergeWithAttributesFromDatabase
+  include Waterslide::Pipe
+
+  def pipe_one(user)
+    record = database_records.find do |record|
+      record.facebook_id == user.facebook_id
+    end
+
+    yield user.merge_attributes record
+  end
+
+  def database_records
+    @records ||= User.where(facebook_id: incoming.map(&:facebook_id)).to_a
+  end
+end
+
+class RemoveRecordsNotInDatabase
+  include Waterslide::Pipe
+
+  def pipe_one(record)
+    yield record if record.id
+  end
+end
+
+class Serialize
+  include Waterslide::Pipe
+
+  def as_json
+    map(&:as_json)
+  end
+end
+
+# ...
+
+FacebookFriends.new(current_user) >>
+  DeserializeFacebookUsers >>
+  MergeWithAttributesFromDatabase >>
+  RemoveRecordsNotInDatabase >>
+  SerializeUsers
+```
+
+There's obviously a lot more lines of code in the new version, but the sequence of transformations reads naturally, and, perhaps more importantly, every step can now be unit-tested individually.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'waterslide'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install waterslide
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Serving Suggestions
+
+If you like syntactic sugar on your cerealizables, you may want to monkey-patch Array with the Waterslide right-shift operator override. That will let you do stuff like this:
+
+```ruby
+[1, 2, 3] >> MultiplyByTwo # => [2, 4, 6]
+```
+
+Here's how to do the monkey-patch:
+
+```ruby
+class Array
+  include Waterslide::RightShiftOverride
+end
+```
+
+You should probably only do this if everyone on your team is on board with Waterslide and knows how to use it; otherwise, they'll have a hell of time deciphering your code.
+
+## Contributing
+
+1. Fork it ( https://github.com/benchristel/waterslide/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/lib/waterslide.rb

@@ -0,0 +1,65 @@
+module Waterslide
+  module RightShiftOverride
+    def >> (pipe)
+      instantiated(pipe).receive_from(self)
+    end
+
+    private
+    def instantiated(pipe)
+      pipe.is_a?(Class) ? pipe.new : pipe
+    end
+  end
+
+  module Pipe
+    def self.included(base)
+      base.class_eval do
+        include Enumerable
+        include RightShiftOverride
+      end
+    end
+
+    def self.[] (things)
+      things = [things] unless things.respond_to? :each
+      NoOp.new.receive_from(things)
+    end
+
+    def receive_from(enumerable)
+      @incoming = enumerable
+      self
+    end
+
+    def each
+      incoming.each do |one|
+        pipe_one(one) { |out| yield out }
+      end
+    end
+
+    def take
+      each { |one| return one }
+      return nil # if nothing was yielded
+    end
+
+    def all
+      all = []
+      each { |one| all << one }
+      all
+    end
+
+    private
+
+    def incoming
+      # including classes may override this to do processing on the incoming
+      # enumerable as as whole - for instance, to sort it.
+      @incoming
+    end
+
+    def pipe_one(thing)
+      # identity function by default; including classes should override this
+      yield thing
+    end
+  end
+
+  class NoOp
+    include Pipe
+  end
+end

data/test.rb

@@ -0,0 +1,178 @@
+gem 'minitest'
+require 'minitest/autorun'
+require_relative 'lib/waterslide'
+
+include Waterslide
+
+class AddOne
+  include Pipe
+
+  def pipe_one(thing)
+    yield thing + 1
+  end
+end
+
+class Add
+  include Pipe
+
+  def initialize(n)
+    @increment = n
+  end
+
+  def pipe_one(thing)
+    yield thing + @increment
+  end
+end
+
+def Add(*args)
+  Add.new(*args)
+end
+
+class TestWaterslide < MiniTest::Test
+  def test_piping_a_scalar_through_no_op
+    assert_equal 1, (Pipe[1] >> NoOp).first
+  end
+
+  def test_piping_a_scalar_through_multiple_no_ops
+    assert_equal 1, (Pipe[1] >> NoOp >> NoOp).first
+  end
+
+  def test_piping_a_scalar_through_add_one
+    assert_equal 2, (Pipe[1] >> AddOne).first
+  end
+
+  def test_piping_a_scalar_through_multiple_add_ones
+    assert_equal 3, (Pipe[1] >> AddOne >> AddOne).first
+  end
+
+  def test_piping_an_array_through_no_op
+    assert_equal [1,2,3], (Pipe[[1,2,3]] >> NoOp).all
+  end
+
+  def test_piping_an_array_through_add_one
+    assert_equal [2,3,4], (Pipe[[1,2,3]] >> AddOne).all
+  end
+
+  def test_piping_an_array_through_multiple_add_ones
+    assert_equal [3,4,5], (Pipe[[1,2,3]] >> AddOne >> AddOne).all
+  end
+
+  def test_piping_an_array_through_add
+    assert_equal [4,5,6], (Pipe[[1,2,3]] >> Add(3)).all
+  end
+
+  def test_that_pipes_are_enumerables
+    assert (Pipe[[1,2,3]] >> Add(3)).include? 4
+    assert_equal 3, (Pipe[[1,2,3]] >> Add(3)).count
+  end
+
+
+
+  class Duplicate
+    include Pipe
+
+    def pipe_one(thing)
+      yield thing
+      yield thing
+    end
+  end
+
+  def test_duplicate
+    assert_equal [1,1,2,2,3,3], (Pipe[[1,2,3]] >> Duplicate).all
+  end
+
+
+
+  class OnlyEvens
+    include Pipe
+
+    def pipe_one(n)
+      yield n if n % 2 == 0
+    end
+  end
+
+  def test_piping_an_array_through_a_filter
+    assert_equal [2,4,6], (Pipe[[1,2,3,4,5,6]] >> OnlyEvens).all
+  end
+
+
+
+  class Sort
+    include Pipe
+
+    def incoming
+      super.sort
+    end
+  end
+
+  def test_sorting_with_overridden_incoming
+    assert_equal [1,2,3,4,5], (Pipe[[4,1,5,3,2]] >> Sort).all
+  end
+
+
+
+  class Sort::Descending < Sort
+    def incoming
+      super.reverse
+    end
+  end
+
+  def test_subclasses_of_pipes
+    assert_equal [5,4,3,2,1], (Pipe[[4,1,5,3,2]] >> Sort::Descending).all
+  end
+
+
+
+  class AboveAverage
+    include Pipe
+
+    def pipe_one(thing)
+      yield thing if thing > average
+    end
+
+    def average
+      @average ||= incoming.reduce(:+) / incoming.count
+    end
+  end
+
+  def test_incoming_with_above_average
+    assert_equal [4,5], (Pipe[[1,2,3,4,5]] >> AboveAverage).all
+  end
+
+
+
+  class InfiniteJest
+    include Pipe
+
+    def each
+      n = 0
+      while(n < 6)
+        yield 'ha'
+        n += 1
+      end
+      raise 'oh no you are dead'
+    end
+  end
+
+  def test_that_enumeration_is_lazy_when_possible
+    haha = (InfiniteJest.new >> NoOp).first(5)
+    assert_equal ["ha"]*5, haha
+  end
+
+  def test_that_enumeration_is_not_lazy_when_impossible
+    haha = (InfiniteJest.new >> Sort).first(5) rescue 'got to infinity'
+    assert_equal 'got to infinity', haha
+  end
+
+
+
+  class MagicArray < Array
+    include Waterslide::RightShiftOverride
+  end
+
+  def test_right_shift_operator_override
+    array = MagicArray.new
+    array << 1 << 2 << 3
+    assert (array >> Add(2)).map(&:to_i) == [3, 4, 5]
+  end
+end

data/waterslide.gemspec

@@ -0,0 +1,18 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+Gem::Specification.new do |s|
+  version = "0.1.0"
+
+  s.name          = "waterslide"
+  s.version       = version
+  s.platform      = Gem::Platform::RUBY
+  s.license       = "MIT"
+  s.authors       = ["Ben Christel"]
+  s.homepage      = "http://github.com/benchristel/waterslide"
+  s.summary       = "waterslide-#{version}"
+  s.description   = "Unix-style pipes in Ruby"
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = s.files.grep(/^test/)
+  s.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: waterslide
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ben Christel
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-04-19 00:00:00.000000000 Z
+dependencies: []
+description: Unix-style pipes in Ruby
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- LICENSE
+- README.md
+- lib/waterslide.rb
+- test.rb
+- waterslide.gemspec
+homepage: http://github.com/benchristel/waterslide
+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.6
+signing_key: 
+specification_version: 4
+summary: waterslide-0.1.0
+test_files:
+- test.rb