pipe-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: aecb3bc0a365cf5620fc131aefc6a66c0eda8943
+  data.tar.gz: 934bb442c5fa9212d3ae49ea83aed0a98b1e9b91
+SHA512:
+  metadata.gz: 62b208dfa76ff39c8a88a3912888079029670406a401473cc1a354ef9b14c68273ed0e3f307da1729b09ede5e1c98a7d88951e2bb2424d8da658a16725ab58de
+  data.tar.gz: c3d9f27acc430b85f06e2fe43ae1844458a87ca73e39a76182e05bcbdad3d18799fb3e83438968ecdfe349f97167553583fe5f5d44e0801d81ee1e0467b4efb6

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 TeamSnap
+
+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,176 @@
+# Pipe
+
+`pipe-ruby` is an implementation of the UNIX pipe command. It exposes two
+instance methods, `pipe` and `pipe_each`.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pipe-ruby'
+```
+
+After bundling, include the `Pipe` module in your class(es)
+
+```ruby
+class MyClass
+  include Pipe
+
+  # ...
+end
+```
+
+## Default Usage
+
+### #pipe
+
+```ruby
+pipe(subject, :through => [
+  :method1, :method2#, ...
+])
+```
+
+Just as with the UNIX pipe, `subject` will be passed as the first argument to
+`method1`. The results of `method1` will be passed to `method2` and on and
+on. The result of the last method called will be returned from the pipe.
+
+### #pipe_each
+
+```ruby
+pipe_each([subj1, subj2], :through => [
+  :method1, :method2#, ...
+])
+```
+
+`pipe_each` calls `pipe`, passing each individual subject. It will return a
+mapped array of the responses.
+
+## Configurable Options
+
+After implementing the `pipe` method in a few different places, we found that a
+slightly different version was needed for each use case. `Pipe::Config` allows
+for this customization per call or per class implementation. There are four
+configurable options. Here they are with their defaults:
+
+```ruby
+Pipe::Config.new(
+  :error_handlers => [],   # an array of procs to be called when an error occurs
+  :raise_on_error => true, # tells Pipe to re-raise errors which occur
+  :skip_on => false,       # a truthy value or proc which tells pipe to skip the
+                           # next method in the `through` array
+  :stop_on => false        # a truthy value or proc which tells pipe to stop
+                           # processing and return the current value
+)
+```
+
+A `Pipe::Config` object can be passed to the pipe method one of three ways.
+
+NOTE: The options below are in priority order, meaning an override of the
+`pipe_config` method will take precedence over an override of the `@pipe_config`
+instance variable.
+
+You can pass it to pipe when called:
+
+```ruby
+class MyClass
+  include Pipe
+
+  def my_method
+    config = Pipe::Config.new(:raise_on_error => false)
+    subject = Object.new
+
+    pipe(subject, :config => config, :through => [
+      # ...
+    ])
+  end
+
+  # ...
+end
+```
+
+Or override the `pipe_config` method:
+
+```ruby
+class MyClass
+  include Pipe
+
+  def pipe_config
+    Pipe::Config.new(:raise_on_error => false)
+  end
+
+  # ...
+end
+```
+
+Or you can assign it to the `@pipe_config` instance variable:
+
+```ruby
+class MyClass
+  include Pipe
+
+  def initialize
+    @pipe_config = Pipe::Config.new(:raise_on_error => false)
+  end
+
+  # ...
+end
+```
+
+## Error Handling
+
+As we implemented different versions of `pipe` across our infrastructure, we
+came across several different error handling needs.
+
+- logging errors that occur in methods called by pipe without raising them
+- catching and re-raising errors with additional information so we can still
+  see the real backtrace while also gaining insight into which subject and
+  method combination triggered the error
+- easily seeing which area of the pipe stack we were in when an error occurred
+
+The first layer of error handling is the `error_handlers` attribute in
+`Pipe::Config`. Each proc in this array will be called with two arguments,
+the actual error object and a context hash containing the method and subject
+when the error occurred. If an error occurs within one of these handlers it
+will be re-raised inside the `Pipe::HandlerError` namespace, meaning a
+`NameError` becomes a `Pipe::HandlerError::NameError`. We also postpend the
+current method, current subject and original error class to the message.
+
+NOTE: `Pipe::Config#error_handler` takes a block and adds it to the existing
+error handlers.
+
+We have two other namespaces, `Pipe::ReducerError`, which is used when an error
+occurs inside during `pipe` execution and `Pipe::IteratorError` for errors which
+occur inside of `pipe_each` execution.
+
+Whenever an error occurs in execution (but not in error handler processing), the
+response of `Pipe::Config#raise_on_error?` is checked. If this method returns
+`true`, the error will be re-raised inside of the appropriate namespace. If it
+returns `false`, the current value of `subject` will be returned and execution
+stopped.
+
+## Skipping / Stopping Execution
+
+Prior to the execution of each method in the `through` array,
+`Pipe::Config#break?` is called with the current value of `subject`. If it
+returns truthy, execution will be stopped and the current value of subject
+will be returned. A falsey response will allow the execution to move forward.
+
+If the break test allows us to move forward, `Pipe::Config#skip?` will be called
+with the current value of `subject`. Truthy responses from this method will
+cause the existing value of subject to be carried to the next method without
+executing the current specified method. Falsey responses will allow normal
+execution of the currently specified method.
+
+## Testing
+
+I'll be adding tests in in the very near future. In the meantime, use at your
+own risk :)
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/pipe-ruby/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/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/lib/pipe/config.rb

@@ -0,0 +1,47 @@
+module Pipe
+  class Config
+    attr_accessor :raise_on_error
+    attr_reader :error_handlers, :skip_on, :stop_on
+
+    def initialize(
+      error_handlers: [],
+      raise_on_error: true,
+      skip_on: false,
+      stop_on: false
+    )
+      @error_handlers = error_handlers
+      @raise_on_error = raise_on_error
+      self.skip_on = skip_on
+      self.stop_on = stop_on
+    end
+
+    def error_handler(&block)
+      error_handlers << block if block_given?
+    end
+
+    def break?(subj)
+      stop_on.call(subj)
+    rescue ArgumentError
+      stop_on.call
+    end
+
+    def raise_on_error?
+      raise_on_error ? true : false
+    end
+
+    def skip?(subj)
+      skip_on.call(subj)
+    rescue ArgumentError
+      skip_on.call
+    end
+
+    def skip_on=(val)
+      @skip_on = (val.respond_to?(:call) ? val : lambda { |obj| val })
+    end
+
+    def stop_on=(val)
+      @stop_on = (val.respond_to?(:call) ? val : lambda { |obj| val })
+    end
+  end
+end
+

data/lib/pipe/error.rb

@@ -0,0 +1,38 @@
+module Pipe
+  HandlerError = Module.new
+  IterationError = Module.new
+  ReducerError = Module.new
+
+  class Error
+    def self.process(data: {}, error:, namespace:)
+      new(error).rewrite_as(:namespace => namespace, :data => data)
+    end
+
+    def initialize(e)
+      @e = e
+    end
+
+    def rewrite_as(data: {}, namespace:)
+      subclass = find_or_create_subclass(namespace)
+      raise subclass, "#{e} [#{data}, #{e.class}]", e.backtrace
+    end
+
+    private
+
+    attr_reader :e
+
+    def find_or_create_subclass(namespace)
+      part = e.class.name.split("::").last
+      subclass_name = "#{namespace.name}::#{part}"
+
+      begin
+        subclass_name.constantize
+      rescue NameError
+        eval "#{subclass_name} = Class.new(StandardError)"
+      end
+
+      subclass_name.constantize
+    end
+  end
+end
+

data/lib/pipe/ext/inflection.rb

@@ -0,0 +1,38 @@
+module Pipe
+  module Ext
+    module Inflection
+      # ripped from ActiveSupport#Inflections
+      # https://github.com/rails/rails/blob/861b70e92f4a1fc0e465ffcf2ee62680519c8f6f/activesupport/lib/active_support/inflector/methods.rb#L249
+      def self.constantize(camel_cased_word)
+        names = camel_cased_word.split('::')
+
+        # Trigger a built-in NameError exception including the ill-formed constant in the message.
+        Object.const_get(camel_cased_word) if names.empty?
+
+        # Remove the first blank element in case of '::ClassName' notation.
+        names.shift if names.size > 1 && names.first.empty?
+
+        names.inject(Object) do |constant, name|
+          if constant == Object
+            constant.const_get(name)
+          else
+            candidate = constant.const_get(name)
+            next candidate if constant.const_defined?(name, false)
+            next candidate unless Object.const_defined?(name)
+
+            # Go down the ancestors to check if it is owned directly. The check
+            # stops when we reach Object or the end of ancestors tree.
+            constant = constant.ancestors.inject do |const, ancestor|
+              break const    if ancestor == Object
+              break ancestor if ancestor.const_defined?(name, false)
+              const
+            end
+
+            # owner is in Object, so raise
+            constant.const_get(name, false)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pipe/ext/string.rb

@@ -0,0 +1,17 @@
+require "pipe/ext/inflection"
+
+module Pipe
+  module Ext
+    module String
+      unless "".respond_to? :constantize
+        def constantize
+          Inflection.constantize(self)
+        end
+      end
+    end
+  end
+end
+
+class String
+  include Pipe::Ext::String
+end

data/lib/pipe/iterator.rb

@@ -0,0 +1,41 @@
+module Pipe
+  class Iterator
+    def initialize(config:, context:, subjects:, through:)
+      self.config = config
+      self.context = context
+      self.subjects = subjects
+      self.through = through
+    end
+
+    def iterate
+      subjects.map { |subject|
+        begin
+          Reducer.new(
+            config: config,
+            context: context,
+            subject: subject,
+            through: through
+          ).reduce
+        rescue => e
+          handle_error(:error => e, :subject => subject)
+          subject
+        end
+      }
+    end
+
+    private
+
+    attr_accessor :config, :context, :subjects, :through
+
+    def handle_error(error:, subject:)
+      if config.raise_on_error?
+        Error.process(
+          :data => { :subject => subject },
+          :error => e,
+          :namespace => IterationError,
+        )
+      end
+    end
+  end
+end
+

data/lib/pipe/reducer.rb

@@ -0,0 +1,66 @@
+module Pipe
+  class Reducer
+    def initialize(config:, context:, subject:, through:)
+      self.config = config
+      self.context = context
+      self.subject = subject
+      self.through = through
+    end
+
+    def reduce
+      through.reduce(subject) { |subj, method|
+        begin
+          break subj if config.break?(subj)
+
+          process(subj, method)
+        rescue => e
+          handle_error(:error => e, :method => method, :subject => subj)
+          break subj
+        end
+      }
+    end
+
+    private
+
+    attr_accessor :config, :context, :subject, :through
+
+    def handle_error(error:, method:, subject:)
+      process_error_handlers(
+        :error => error,
+        :method => method,
+        :subject => subject
+      )
+
+      if config.raise_on_error?
+        Error.process(
+          :data => { :method => method, :subject => subject },
+          :error => error,
+          :namespace => ReducerError,
+        )
+      end
+    end
+
+    def process(subj, method)
+      if config.skip?(subj)
+        subj
+      else
+        context.send(method, subj)
+      end
+    end
+
+    def process_error_handlers(error:, method:, subject:)
+      data = { method: method, subject: subject }
+
+      begin
+        config.error_handlers.each { |handler| handler.call(e, data) }
+      rescue => e
+        Error.process(
+          :data => data,
+          :error => e,
+          :namespace => HandlerError,
+        )
+      end
+    end
+  end
+end
+

data/lib/pipe/ruby/version.rb

@@ -0,0 +1,5 @@
+module Pipe
+  module Ruby
+    VERSION = "0.1.0"
+  end
+end

data/lib/pipe.rb

@@ -0,0 +1,33 @@
+require "pipe/ext/string"
+require "pipe/config"
+require "pipe/error"
+require "pipe/iterator"
+require "pipe/reducer"
+
+module Pipe
+  def pipe(subject, config: pipe_config, through: [])
+    ::Pipe::Reducer.new(
+      :config => config,
+      :context => self,
+      :subject => subject,
+      :through => through
+    ).reduce
+  end
+
+  def pipe_each(subjects, config: pipe_config, through: [])
+    ::Pipe::Iterator.new(
+      :config => config,
+      :context => self,
+      :subjects => subjects,
+      :through => through
+    ).iterate
+  end
+
+  private
+
+  def pipe_config
+    @pipe_config || Pipe::Config.new
+  end
+end
+
+

data/pipe-ruby.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'pipe/ruby/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "pipe-ruby"
+  spec.version       = Pipe::Ruby::VERSION
+  spec.authors       = ["Dan Matthews"]
+  spec.email         = ["oss@teamsnap.com"]
+  spec.summary       = %q{Ruby implementation of the UNIX pipe}
+  spec.description   = %q{}
+  spec.homepage      = ""
+  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.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: pipe-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dan Matthews
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !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'
+description: ''
+email:
+- oss@teamsnap.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/pipe.rb
+- lib/pipe/config.rb
+- lib/pipe/error.rb
+- lib/pipe/ext/inflection.rb
+- lib/pipe/ext/string.rb
+- lib/pipe/iterator.rb
+- lib/pipe/reducer.rb
+- lib/pipe/ruby/version.rb
+- pipe-ruby.gemspec
+homepage: ''
+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: Ruby implementation of the UNIX pipe
+test_files: []