casting 0.6.7 → 0.6.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4ffec94418d01d7ecc13e0f30923c57c2bcf9eeb
-  data.tar.gz: 448fba5864860e5e8c06f21fe9bc11e31ba9f8d6
+  metadata.gz: 02fe7c29c8da27adba6036307ab658548bf6a20a
+  data.tar.gz: 1b674c20260d1e89830e088f0db5fe2dbee43639
 SHA512:
-  metadata.gz: 6cd3187516eb76ff46c0a31759d961ae835d65b85ffd504620fdc9bd132d55328f2f63c1ab8b925559044509a36d7a4426634fdb21fe3f8d63e48fb841c30b2c
-  data.tar.gz: 2f93492b5429e9549fc011057cd79568624d710bf3eef66a768fe6ea2540c01a2cec2a0e5e99bb8b3a4ad821630c445560dc41f4c76da8ca1668151a242ae8d1
+  metadata.gz: c86a535a9ae96e3e6b1034488cda5b487c76e51a028b7fce0f907ce96b580adb46d748f0b1a8231fc287b9a164f3d71171184d80776c7bba571dca60e0b59c36
+  data.tar.gz: 031bfc7f0989891cb12c48097e5990bbae8d95cb2e348e8b652fa4b84f652bca2b0cfab07ea34ec49c5506cc0ac45d96e6891ace776b52cf4f35feac1593797c

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012-2014 Jim Gay
+
+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,331 @@
+# Casting
+
+[![Build Status](https://travis-ci.org/saturnflyer/casting.png?branch=master)](https://travis-ci.org/saturnflyer/casting)
+[![Code Climate](https://codeclimate.com/github/saturnflyer/casting.png)](https://codeclimate.com/github/saturnflyer/casting)
+[![Coverage Status](https://coveralls.io/repos/saturnflyer/casting/badge.png)](https://coveralls.io/r/saturnflyer/casting)
+[![Gem Version](https://badge.fury.io/rb/casting.png)](http://badge.fury.io/rb/casting)
+
+## Add behavior to your objects without using extend
+Do it for the life of the object or only for the life of a block of code.
+
+Casting gives you real delegation that flattens your object structure compared to libraries
+like Delegate or Forwardable. With casting, you can implement your own decorators that
+will be so much simpler than using wrappers.
+
+Here's a quick example that you might try in a Rails project:
+
+```ruby
+# implement a module that contains information for the request response
+# and apply it to an object in your system.
+def show
+  respond_with user.cast_as(UserRepresenter)
+end
+```
+
+To use proper delegation, your approach should preserve `self` as a reference
+to the original object receiving a method. When the object receiving the forwarded
+message has its own and separate notion of `self`, you're working with a wrapper (also called
+consultation) and not using delegation.
+
+The Ruby standard library includes a library called "delegate", but it is
+a consultation approach. With that "delegate", all messages are forwarded to
+another object, but the attendant object maintains its own identity.
+
+With Casting, your defined methods may reference `self` and during
+execution it will refer to the original client object.
+
+Casting was created while exploring ideas for [cleaning up ruby programs](http://clean-ruby.com).
+
+## Usage
+
+To use Casting, you must first extend an object as the delegation client:
+
+```ruby
+actor = Object.new
+actor.extend(Casting::Client)
+```
+
+Or you may include the module in a particular class:
+
+```ruby
+class Actor
+  include Casting::Client
+end
+actor = Actor.new
+```
+
+Your objects will have a few additional methods: `delegation`, `cast`, and if you do not *already* have it defined (from another library, for example): `delegate`. The `delegate` method is aliased to `cast`.
+
+Then you may delegate a method to an attendant object:
+
+```ruby
+actor.delegate(:hello_world, other_actor)
+```
+
+Or you may create an object to manage the delegation of methods to an attendant object:
+
+```ruby
+actor.delegation(:hello_world).to(other_actor).call
+```
+
+You may also delegate methods without an explicit attendant instance, but provide
+a module containing the behavior you need to use:
+
+```ruby
+actor.delegate(:hello_world, GreetingModule)
+# or
+actor.delegation(:hello_world).to(GreetingModule).call
+```
+
+Pass arguments to your delegated method:
+
+```ruby
+actor.delegate(:verbose_method, another_actor, arg1, arg2)
+
+actor.delegation(:verbose_method).to(another_actor).with(arg1, arg2).call
+
+actor.delegation(:verbose_method).to(another_actor).call(arg1, arg2)
+```
+
+_That's great, but why do I need to do these extra steps? I just want to run the method._
+
+Casting gives you the option to do what you want. You can run just a single method once, or alter your object to always delegate. Even better, you can alter your object to delegate temporarily...
+
+## Temporary Behavior
+
+Casting also provides an option to temporarily apply behaviors to an object.
+
+Once your class or object is a `Casting::Client` you may send the `delegate_missing_methods` message to it and your object will use `method_missing` to delegate methods to a stored attendant.
+
+```ruby
+actor.hello_world #=> NoMethodError
+
+Casting.delegating(actor => GreetingModule) do
+  actor.hello_world #=> output the value / perform the method
+end
+
+actor.hello_world #=> NoMethodError
+```
+
+The use of `method_missing` is opt-in. If you don't want that mucking up your method calls, just don't tell it to `delegate_missing_methods`.
+
+Before the block is run in `Casting.delegating`, a collection of delegate objects is set on the object to the provided attendant. Then the block yields, and an `ensure` block cleans up the stored attendant.
+
+This allows you to nest your `delegating` blocks as well:
+
+```ruby
+actor.hello_world #=> NoMethodError
+
+Casting.delegating(actor => GreetingModule) do
+  actor.hello_world #=> output the value / perform the method
+
+  Casting.delegating(actor => OtherModule) do
+    actor.hello_world #=> still works!
+    actor.other_method # values/operations from the OtherModule
+  end
+
+  actor.other_method #=> NoMethodError
+  actor.hello_world #=> still works!
+end
+
+actor.hello_world #=> NoMethodError
+```
+
+Currently, by using `delegate_missing_methods` you forever mark that object or class to use `method_missing`. This may change in the future.
+
+### Manual Delegate Management
+
+If you'd rather not wrap things in the `delegating` block, you can control the delegation yourself.
+For example, you can `cast_as` and `uncast` an object with a given module:
+
+```ruby
+actor.cast_as(GreetingModule)
+actor.hello_world # all subsequent calls to this method run from the module
+actor.uncast # manually cleanup the delegate
+actor.hello_world # => NoMethodError
+```
+
+These methods are only defined on your `Casting::Client` object when you tell it to `delegate_missing_methods`. Because these require `method_missing`, they do not exist until you opt-in.
+
+## I have a Rails app, how does this help me?
+
+Well, a common use for this behavior would be in using decorators.
+
+When using a wrapper, your forms can behave unexpectedly
+
+```ruby
+class UsersController
+  def edit
+    @user = UserDecorator.new(User.find(params[:id]))
+  end
+end
+
+<%= form_for(@user) do |f| %> #=> <form action="/user_decorators/1">
+```
+
+Ruby allows you to hack this by defining the `class` method:
+
+```ruby
+class UserDecorator
+  def class
+    User
+  end
+end
+```
+
+That would solve the problem, and it works! But having an object report that
+its class is something other than what it actually is can be confusing
+when you're debugging.
+
+Instead, you could cast the object as a module and your form will generate properly:
+
+```ruby
+class UsersController
+  def edit
+    @user = User.find(params[:id]).cast_as(UserDecorator) # as a module
+  end
+end
+
+<%= form_for(@user) do |f| %> #=> <form action="/users/1">
+```
+
+This keeps your code focused on the object you care about.
+
+## Oh, my! Could this be used to add behavior like refinements?
+
+You can apply methods from a delegate to all instances of a class.
+
+```ruby
+person.hello_world #=> NoMethodError
+
+Casting.delegating(Person => GreetingModule) do
+  person.hello_world #=> output the value / perform the method
+end
+
+person.hello_world #=> NoMethodError
+```
+
+By default, the `delegate_missing_methods` method will set delegates on instances so you'll need to opt-in for this.
+
+```ruby
+class Person
+  include Casting::Client
+  delegate_missing_methods :class
+end
+```
+
+_But what happens when you have method clashes or want a specific instance to behave differently?_
+
+You can have your objects look to their instance delegates, their class delegates, or in a particular order:
+
+```ruby
+class Person
+  include Casting::Client
+  # default delegation to instances
+  delegate_missing_methods
+
+  # delegate methods to those defined on the class
+  delegate_missing_methods :class
+
+  # delegate methods to those defined on the class, then those defined on the instance
+  delegate_missing_methods :class, :instance
+
+  # delegate methods to those defined on the instance, then those defined on the class
+  delegate_missing_methods :instance, :class
+end
+```
+
+## What's happening when I use this?
+
+Ruby allows you to access methods as objects and pass them around just like any other object.
+
+For example, if you want a method from a class you may do this:
+
+```ruby
+class Person
+  def hello
+    "hello"
+  end
+end
+Person.new.method(:hello).unbind #=> #<UnboundMethod: Person#hello>
+# or
+Person.instance_method(:hello) #=> #<UnboundMethod: Person#hello>
+```
+
+But if you attempt to use that `UnboundMethod` on an object that is not a `Person` you'll get
+an error about a type mismatch.
+
+Casting will bind an unbound method to a client object and execute the method as though it is
+defined on the client object. Any reference to `self` from the method block will refer to the
+client object.
+
+This behavior is different in Ruby 1.9 vs. 2.x.
+
+According to [http://rubyspec.org](http://rubyspec.org) the behavior in MRI in 1.9 that allows this to happen is incorrect. In MRI (and JRuby) 1.9 you may unbind methods from an object that has been extended with a module, and bind them to another object of the same type that has *not* been extended with that module.
+
+Casting uses this as a way to trick the interpreter into using the method where we want it and avoid forever extending the object of concern.
+
+This changed in Ruby 2.0 and does not work. What does work (and is so much better) in 2.0 is that you may take any method from a module and apply it to any object. This means that Casting doesn't have to perform any tricks to temporarily apply behavior to an object.
+
+For example, this fails in 1.9, but works in 2.0:
+
+```ruby
+GreetingModule.instance_method(:hello_world).bind(actor).call
+```
+
+Casting provides a convenience for doing this.
+
+## What if my modules create instance variables on the object? Can I clean them up?
+
+Yup.
+
+If you need to set some variables so that your module can access them, it's as easy as defining `cast_object` and `uncast_object` on your module. Here's an example:
+
+```ruby
+module Special
+  def self.cast_object(obj)
+    obj.instance_variable_set(:@special_value, 'this is special!')
+  end
+  
+  def self.uncast_object(obj)
+    obj.remove_instance_variable(:@special_value)
+  end
+  
+  def special_behavior
+    "#{self.name} thinks... #{@special_value}"
+  end
+end
+
+object.cast_as(Special)
+object.special_method
+object.uncast
+# object no longer has the @special_value instance variable
+```
+
+You'll be able to leave your objects as if they were never touched by the module where you defined your behavior.
+
+## Installation
+
+If you are using Bundler, add this line to your application's Gemfile:
+
+```ruby
+gem 'casting'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install casting
+
+## Contributing
+
+1. Fork it
+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 new Pull Request
+
+Built by Jim Gay at [Saturn Flyer](http://www.saturnflyer.com)

data/Rakefile

@@ -0,0 +1,12 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/*_test.rb']
+  t.ruby_opts = ["-w"]
+  t.verbose = true
+end
+
+task :default => :test

data/lib/casting/super_delegate.rb

@@ -0,0 +1,68 @@
+module Casting
+  module SuperDelegate
+    
+    # Call the method of the same name defined in the next delegate stored in your object
+    #
+    # Because Casting creates an alternative method lookup path using a collection of delegates,
+    # you may use `super_delegate` to work like `super`.
+    #
+    # If you use this feature, be sure that you have created a delegate collection which does
+    # have the method you need or you'll see a NoMethodError.
+    #
+    # Example:
+    #
+    # module Greeter
+    #   def greet
+    #     "Hello"
+    #   end
+    # end
+    #
+    # module FormalGreeter
+    #   include Casting::Super
+    #   
+    #   def greet
+    #     "#{super_delegate}, how do you do?"
+    #   end
+    # end
+    #
+    # some_object.cast_as(Greeter, FormalGreeter)
+    # some_object.greet #=> 'Hello, how do you do?'
+    #
+    def super_delegate(*args, &block)
+      method_name = name_of_calling_method(caller)
+      owner = args.first || method_delegate(method_name)
+      
+      super_delegate_method = unbound_method_from_next_delegate(method_name, owner)
+
+      if super_delegate_method.arity == 0
+        super_delegate_method.bind(self).call
+      else
+        super_delegate_method.bind(self).call(*args, &block)
+      end
+    rescue NameError
+      raise NoMethodError.new("super_delegate: no delegate method `#{method_name}' for #{self.inspect} from #{owner}")
+    end
+    
+    def unbound_method_from_next_delegate(method_name, *skipped)
+      method_delegate_skipping(method_name, *skipped).instance_method(method_name)
+    end
+    
+    def method_delegate_skipping(meth, skipped)
+      skipped_index = __delegates__.index(skipped)
+      __delegates__.find{|attendant|
+        attendant_methods(attendant).include?(meth) &&
+        skipped_index < __delegates__.index(attendant)
+      }
+    end
+    
+    def name_of_calling_method(call_stack)
+      call_stack.reject{|line| 
+        line.to_s =~ casting_library_matcher 
+      }.first.split('`').last.sub("'","").to_sym
+    end
+    
+    def casting_library_matcher
+      Regexp.new(Dir.pwd.to_s + '/lib')
+    end
+  end
+end

data/lib/casting/version.rb

@@ -1,3 +1,3 @@
 module Casting
-  VERSION = '0.6.7'
+  VERSION = '0.6.8'
 end

data/test/module_cleanup_test.rb

@@ -0,0 +1,43 @@
+require 'test_helper'
+
+module Cleaner
+  def self.uncast_object(object)
+    object.send(:remove_instance_variable, :@cleaner_message)
+  end
+  
+  def self.cast_object(object)
+    object.instance_variable_set(:@cleaner_message, "#{object.name} will be cleaned up")
+  end
+  
+  def cleaner_message
+    @cleaner_message
+  end
+end
+
+class CleanupPerson
+  include Casting::Client
+  delegate_missing_methods
+  attr_accessor :name
+end
+
+describe 'modules with setup tasks' do
+  it 'allows modules to setup an object when cast_as' do
+    jim = CleanupPerson.new
+    jim.name = 'Jim'
+    jim.cast_as(Cleaner)
+    assert_equal "Jim will be cleaned up", jim.cleaner_message
+    assert_equal "Jim will be cleaned up", jim.instance_variable_get(:@cleaner_message)
+  end
+end
+
+describe 'modules with cleanup tasks' do
+  it 'allows modules to cleanup their required attributes when uncast' do
+    jim = CleanupPerson.new
+    jim.name = 'Jim'
+    jim.cast_as(Cleaner)
+    assert_equal "Jim will be cleaned up", jim.cleaner_message
+    assert_equal "Jim will be cleaned up", jim.instance_variable_get(:@cleaner_message)
+    jim.uncast
+    refute jim.instance_variable_defined?(:@cleaner_message)
+  end
+end

data/test/super_test.rb

@@ -0,0 +1,32 @@
+require 'test_helper'
+
+module AnyWay
+  def which_way
+    "any way"
+  end
+end
+
+module ThisWay
+  include Casting::SuperDelegate
+  def which_way
+    "this way or #{super_delegate(ThisWay)}"
+  end
+end
+
+module ThatWay
+  include Casting::SuperDelegate
+  def which_way
+    "#{ super_delegate } and that way!"
+  end
+end
+
+describe Casting, 'modules using delegate_super' do
+  it 'call the method from the next delegate with the same arguments' do
+    skip 'extending objects not used in this version of Ruby' unless test_rebinding_methods?
+    client = TestPerson.new.extend(Casting::Client)
+    client.delegate_missing_methods
+    client.cast_as(AnyWay, ThisWay, ThatWay)
+
+    assert_equal 'this way or any way and that way!', client.which_way
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: casting
 version: !ruby/object:Gem::Version
-  version: 0.6.7
+  version: 0.6.8
 platform: ruby
 authors:
 - Jim Gay
@@ -27,7 +27,11 @@ files:
 - lib/casting/missing_method_client.rb
 - lib/casting/missing_method_client_class.rb
 - lib/casting/prepared_delegation.rb
+- lib/casting/super_delegate.rb
 - lib/casting/version.rb
+- LICENSE
+- Rakefile
+- README.md
 - test/test_helper.rb
 - test/casting_19_test.rb
 - test/casting_20_test.rb
@@ -37,6 +41,8 @@ files:
 - test/delegation_test.rb
 - test/method_consolidator_test.rb
 - test/missing_method_client_test.rb
+- test/module_cleanup_test.rb
+- test/super_test.rb
 homepage: http://github.com/saturnflyer/casting
 licenses:
 - MIT
@@ -71,3 +77,5 @@ test_files:
 - test/delegation_test.rb
 - test/method_consolidator_test.rb
 - test/missing_method_client_test.rb
+- test/module_cleanup_test.rb
+- test/super_test.rb