closure_forwardable 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 03d368bdd7202ed2a0baa6c274fd6c3e71dd3cab
+  data.tar.gz: ecab750d0c1349c2c4ec78bee71b8efa5785ee63
+SHA512:
+  metadata.gz: 80c789834c633f08a852ba36d6aac3f9d2558b9279131519c3234148983dc46f8c9bb1e8ac17a566e36a8544ba8f61b4cdf16baa1252349d97d00614f3a2975c
+  data.tar.gz: abe4820384c00b091cad011ed38c8496133191b6d3845059ee334fb3787f66f07240a34cfe649aca7a3a86e685afcf911bff9ee437bf2477a92867ec593d5ee3

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,14 @@
+# We rescue from Exception on purpose in order to filter the backtrace
+# We re-raise the exception in any case
+Lint/RescueException:
+  Exclude:
+    - 'lib/closure_forwardable.rb'
+
+Metrics/MethodLength:
+  Max: 15
+
+# We don't want to document the top-level modules multiple times
+# And we don't want to use namespace modules as they can break with unusual
+# load-order. Thus, we simply disable this check.
+Style/Documentation:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,22 @@
+language: ruby
+sudo: false
+cache: bundler
+
+matrix:
+  include:
+    - rvm: 2.0
+      env: COMMAND=rspec
+    - rvm: 2.1
+      env: COMMAND=rspec
+    - rvm: 2.2
+      env: COMMAND=rspec
+    - rvm: jruby
+      env: COMMAND=rspec
+    - rvm: 2.2
+      env: COMMAND=rubocop
+  allow_failures:
+    - rvm: 2.2
+      env: COMMAND=rubocop
+
+before_install: gem install bundler -v 1.10.6
+script: bundle exec $COMMAND

data/.yardopts

@@ -0,0 +1,8 @@
+--protected
+--no-private
+--markup markdown
+-
+README.md
+CHANGELOG.md
+CODE_OF_CONDUCT.md
+LICENSE.txt

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+# 0.1.0 / Unreleased
+
+* Initial release

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,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in closure_forwardable.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Holger Just
+
+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,107 @@
+# ClosureForwardable
+
+[![Gem Version](https://badge.fury.io/rb/closure_forwardable.svg)](https://rubygems.org/gems/closure_forwardable)
+[![Build Status](https://travis-ci.org/meineerde/closure_forwardable.svg?branch=master)](http://travis-ci.org/meineerde/closure_forwardable)
+
+The `ClosureForwardable` module provides delegation of specified methods to a designated object, using the methods `delegate`, `def_delegator`, and `def_delegators`. It allows to define methods in a class or module which will be forwarded to any arbitrary object. This allows the user of this module to build meta-objects which provide a unified access to other objects which can be of great help when trying to adhere to the [Law of Demeter](https://en.wikipedia.org/wiki/Law_of_Demeter).
+
+This module is intended to be used very similar to the [`Forwardable`](http://ruby-doc.org/stdlib-2.2.2/libdoc/forwardable/rdoc/Forwardable.html) module in the Ruby standard library. In fact, it provides almost the same interface and can be used in its place.
+
+Generally, you should use the simple `Forwardable` module if possible as method calls will be slightly faster while providing the same functionality.
+
+Use `ClosureForwardable` if you need to forward methods to a receiver that is not available by the including module itself. Using `ClosureForwardable`, you can forward methods to arbitrary objects.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'closure_forwardable'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install closure_forwardable
+
+## Usage
+
+The `closure_forwardable` gem provides a single module called `ClosureForwardable`. You can use it to delegate methods on to arbitrary other objects.
+
+In the following example, we are going to define two classes, `Consumer` and `Producer` whose instances share a single queue object.
+
+```ruby
+class Consumer
+  extend ClosureForwardable
+
+  def consume!
+    return unless any?
+    element = get_element
+    puts element.inspect
+    element
+  end
+end
+
+class Producer
+  extend ClosureForwardable
+end
+
+queue = []
+# Add the methods any? to the Consumer class which simply calls any on our
+# single queue object.
+Consumer.def_delegator queue, :any?
+# We also add a get_element method to the Consumer which in turn calls shift
+# on the queue.
+Consumer.def_delegator queue, :shift, :get_element
+
+# Finally, we add the queue! method to the Producer class which calls the
+# push method of the queue array.
+Producer.def_delegator queue, :push, :queue!
+
+producer = Producer.new
+producer.queue! :job1
+producer.queue! :job2
+
+queue
+# => [:job1, job2]
+
+consumer = Consumer.new
+consumer.consume!
+# => job1
+consumer.consume!
+# => job2
+consumer.consume!
+# => nil
+
+queue
+# => []
+```
+
+Note that all instances of the classes share the same single `queue` object. Also note that the queue is not added in any way to the classes. There are no instance variables or accessors being defined on the classes. The queue is just made available to the delegation methods and is effectively invisible to the rest of the class.
+
+This is the main difference to the `Forwardable` module of the Ruby standard library: for Forwardable to be able to delegate the methods, it needs to be able to ge access to the delegation object from
+the class instance. Typically, this is achieved using accessors or instance variables. When using `ClosureForwardable`, this is no longer necessary as we can delegate methods to any arbitrary object.
+
+## Why does this work?
+
+The delegated object is in fact made available to the generated method. However, it is only visible though a block closure. With this mechanism which is provided by the block implementation of Ruby, when a block is executed, it can access all local variables which where available at the time the block was defined. This allows us to "hide" the delegation object inside a block's closure which forms the body of the method we define on our class.
+
+Note that because of this, Ruby's garbage collector is intelligent enough to not destroy the object we delegate to as long as it is part of any block's closure. That means, when using `ClosureForwardable`, we strongly tie the forwarded object to the class. The delegation object will continue to be live as long as the class which delegates to it exists (thus typically forever).
+
+## 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/meineerde/closure_forwardable. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](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,7 @@
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task test: :spec
+task default: :spec

data/bin/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'closure_forwardable'
+
+require 'irb'
+IRB.start

data/bin/setup

@@ -0,0 +1,5 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install

data/closure_forwardable.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'closure_forwardable/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'closure_forwardable'
+  spec.version       = ClosureForwardable::VERSION
+  spec.authors       = ['Holger Just']
+  spec.email         = ['hello@holgerjust.de']
+
+  spec.summary       = <<-EOF.gsub(/^\s+/, '').gsub(/\s*\n/, ' ').strip
+    A variant of the Forwardable module in the Ruby Standards Library. Instead
+    of requiring the delegation object to be available on the class, it can
+    be any object.
+  EOF
+  spec.homepage      = 'https://github.com/meineerde/closure_forwardable'
+  spec.license       = 'MIT'
+
+  files = `git ls-files -z`.split("\x0")
+  spec.files = files.reject { |f| f.match(%r{^(test|spec|feature)/}) }
+  spec.bindir = 'exe'
+  spec.executables = files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.10' # license: MIT
+  spec.add_development_dependency 'rake', '~> 10.0' # license: MIT
+  spec.add_development_dependency 'rspec', '~> 3.2' # license: MIT
+  spec.add_development_dependency 'rubocop', '~> 0.32' # license: MIT
+  spec.add_development_dependency 'yard', '~> 0.8.6' # license: MIT
+end

data/lib/closure_forwardable/version.rb

@@ -0,0 +1,33 @@
+module ClosureForwardable
+  # Version information about ClosureForwardable.
+  # We follow semantic versioning
+  module Version
+    # MAJOR version. It is incremented after incompatible API changes
+    MAJOR = 0
+    # MINOR version. It is incremented after adding functionality in a
+    # backwards-compatible manner
+    MINOR = 1
+    # PATCH version. It is incremented when making backwards-compatible
+    # bug-fixes.
+    PATCH  = 0
+
+    # A standard string representation of the version parts
+    STRING = [MAJOR, MINOR, PATCH].compact.join('.').freeze
+
+    # @return [Gem::Version] the version of the currently loaded
+    #   ClosureForwardable as a `Gem::Version`
+    def self.gem_version
+      Gem::Version.new to_s
+    end
+
+    # @return [String] the ClosureForwardable version as a semver-compliant
+    #   string
+    def self.to_s
+      STRING
+    end
+  end
+
+  # The ClosureForwardable version as a semver-compliant string
+  # @see Version::STRING
+  VERSION = Version::STRING
+end

data/lib/closure_forwardable.rb

@@ -0,0 +1,116 @@
+require 'closure_forwardable/version'
+
+require 'English'
+
+# The {ClosureForwardable} module provides delegation of specified methods to a
+# designated object, using the methods {#def_delegator} and {#def_delegators}.
+#
+# This module is intended to be used very similar to the `Forwardable` module in
+# the Ruby standard library. For basic usage guidelines, see there. Generally,
+# you should use the simple `Forwardable` module if possible as method calls
+# will be slightly faster while providing the same functionality.
+#
+# Use {ClosureForwardable} if you need to forward methods to a receiver that
+# is not available by the including module itself. Using {ClosureForwardable},
+# you can forward methods to arbitrary objects.
+module ClosureForwardable
+  # A regular expression matching the current file so that we can filter
+  # backtraces
+  FILE_REGEXP = Regexp.new(Regexp.escape(__FILE__))
+
+  @debug = nil
+  class << self
+    # If true, `__FILE__` will remain in the backtrace in the event an exception
+    # is raised.
+    attr_accessor :debug
+  end
+
+  # Takes a hash as its argument. The key is a symbol or an array of symbols.
+  # These symbols correspond to method names. The value is the receiver to which
+  # the methods will be delegated.
+  #
+  # @param [Hash<Symbol,String,Array<Symbol, String> => Object>] hash
+  # @return [void]
+  def closure_delegate(hash)
+    hash.each do |methods, receiver|
+      methods = [methods] unless methods.respond_to?(:each)
+      methods.each do |method|
+        def_closure_delegator(receiver, method)
+      end
+    end
+  end
+
+  # Shortcut for defining multiple delegator methods, but with no provision for
+  # using a different name.
+  #
+  # @example
+  #     # This definition
+  #     def_delegators records, :size, :<<, :map
+  #
+  #     # is exactly the same as this:
+  #     def_delegator records, :size
+  #     def_delegator records, :<<
+  #     def_delegator records, :map
+  #
+  # @param [Object] receiver the object which will be the receiver of all
+  #   delegated methods calls
+  # @param [Array<Symbol, String>] methods Any number of methods to delegate
+  # @return [void]
+  def def_closure_delegators(receiver, *methods)
+    excluded_methods = ['__send__'.freeze, '__id__'.freeze]
+    methods.each do |method|
+      next if excluded_methods.include?(method.to_s)
+      def_closure_delegator(receiver, method)
+    end
+  end
+
+  # Define `method` as delegator instance method with an optional alias name
+  # `ali`. Method calls to `ali` will be delegated to `receiver.method`.
+  #
+  # @example
+  #     class MyQueue
+  #       extend InheritedSettings::ClosureForwardable
+  #
+  #       attr_reader :internal
+  #       def initialize
+  #         @internal = []
+  #       end
+  #     end
+  #
+  #     external = []
+  #     MyQueue.def_delegator external, :push, :<<
+  #     queue = MyQueue.new
+  #
+  #     queue << 42
+  #     external              #=> [42]
+  #
+  #     queue.internal << 23
+  #     queue.internal        #=> [23]
+  #     external              #=> [42]
+  #
+  # @param [Object] receiver the object which will be the receiver of all
+  #   delegated methods calls
+  # @param [Symbol, String] method the name of the method on the `receiver`
+  # @param [Symbol, String] method_alias The method name created in the
+  #   current module, by default, we use the same name as the method name on the
+  #   `receiver`
+  # @return [void]
+  def def_closure_delegator(receiver, method, method_alias = method)
+    define_method(method_alias) do |*args, &block|
+      begin
+        receiver.__send__(method, *args, &block)
+      rescue Exception
+        unless ::ClosureForwardable.debug
+          $ERROR_POSITION.delete_if do |error_line|
+            ::ClosureForwardable::FILE_REGEXP =~ error_line
+          end
+        end
+        ::Kernel.raise
+      end
+    end
+  end
+
+  alias_method :delegate, :closure_delegate
+  alias_method :def_delegators, :def_closure_delegators
+  alias_method :def_delegator, :def_closure_delegator
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: closure_forwardable
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Holger Just
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-08-07 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: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.32'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.32'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.6
+description: 
+email:
+- hello@holgerjust.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .rubocop.yml
+- .travis.yml
+- .yardopts
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- closure_forwardable.gemspec
+- lib/closure_forwardable.rb
+- lib/closure_forwardable/version.rb
+homepage: https://github.com/meineerde/closure_forwardable
+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: A variant of the Forwardable module in the Ruby Standards Library. Instead
+  of requiring the delegation object to be available on the class, it can be any object.
+test_files: []
+has_rdoc: