surrounded 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: eec57f6f3717bca03404f2acde19afb3cb2a08d4
-  data.tar.gz: 7c6fef1028b60551bcc1cafdb5e7e9099d1ab7ef
+  metadata.gz: 0ffb676825adabf9eeb3f049b5bee0db872d4647
+  data.tar.gz: 77088aade1c2e9079b07546681e8e1997b7aab1c
 SHA512:
-  metadata.gz: 2fe9113c6aaed6c7a09c687045cb54ba792bc59521b8917b09fdbc43a7d17c065cb54eac1a437a1fabcd9d4f094e78e9d67bf75333553ffef6cc63b7d000524e
-  data.tar.gz: 6472c2aef734c56f55d9dc2a0f9992b7e4f693f2ff677685586a3fee3a872cb9bf2602f6cb05e9b68b82a040fc0bf2be32b6aec0c3d4f7ef849df02874a95f65
+  metadata.gz: 2a890fa34e1b6ebd9c1f6646f2fb5d0ea2ea6992e7b8d9a63d84d023267eb2ea1e9898e808ec98ece3995cea8e801a5bfc9da3f4da108cbb3445b336c40b1eb2
+  data.tar.gz: 439627c4612ddfade5819fe832a1799127d179a50ca92fa386efadf60ea51f31a2c9fcbd487581182831eda7ddbee4a8f57cdcb367a3c4cb667cdd44e92e35c0

data/README.md

@@ -3,6 +3,7 @@
 [![Build Status](https://travis-ci.org/saturnflyer/surrounded.png?branch=master)](https://travis-ci.org/saturnflyer/surrounded)
 [![Code Climate](https://codeclimate.com/github/saturnflyer/surrounded.png)](https://codeclimate.com/github/saturnflyer/surrounded)
 [![Coverage Status](https://coveralls.io/repos/saturnflyer/surrounded/badge.png)](https://coveralls.io/r/saturnflyer/surrounded)
+[![Gem Version](https://badge.fury.io/rb/surrounded.png)](http://badge.fury.io/rb/surrounded)
 
 ## Create encapsulated environments for your objects.
 
@@ -45,7 +46,7 @@ class MyEnvironment
   attr_reader :employee, :boss
   private :employee, :boss
   def initialize(employee, boss)
-    @employee = employee.extend(Exmployee)
+    @employee = employee.extend(Employee)
     @boss = boss
   end
 
@@ -107,9 +108,9 @@ class MyEnvironment
   # other stuff from above is still here...
 
   def shove_it
-    Thread.current[:context] = self
+    employee.store_context(self)
     employee.quit
-    Thread.current[:context] = nil
+    employee.remove_context
   end
 
   module Employee
@@ -141,7 +142,7 @@ _OK. I think I understand. So I can change business logic just by changing the p
 
 Damn right.
 
-But you don't want to continually set those `Thread` variables, do you?
+But you don't want to continually set those context details, do you?
 
 _No. That's annoying._
 
@@ -158,7 +159,7 @@ class MyEnvironment
 end
 ```
 
-By using this `trigger` keyword, our block is the code we care about, but internally the method is written to set the `Thread` variables.
+By using this `trigger` keyword, our block is the code we care about, but internally the method is written to set the `@__surroundings__` collection.
 
 _Hmm. I don't like having to do that._
 
@@ -172,21 +173,74 @@ context.triggers #=> [:shove_it]
 
 You might find that useful for dynamically defining user interfaces.
 
+## Policies for the application of role methods
+
+There are 2 approaches to applying new behavior to your objects.
+
+By default your context will add methods to an object before a trigger is run
+and behaviors will be removed after the trigger is run.
+
+Alternatively you may set the behaviors to be added during the initialize method
+of your context.
+
+Here's how it works:
+
+```ruby
+class ActiviatingAccount
+  extend Surrounded::Context
+
+  apply_roles_on(:trigger) # this is the default
+  # apply_roles_on(:initialize) # set this to apply behavior from the start
+
+  setup(:activator, :account)
+
+  module Activator
+    def some_behavior; end
+  end
+
+  def non_trigger_method
+    activator.some_behavior # not available unless you apply roles on initialize
+  end
+
+  trigger :some_trigger_method do
+    activator.some_behavior # always available
+  end
+end
+```
+
+_Why are those options there?_
+
+When you initialize a context and apply behavior at the same time, you'll need
+to remove that behavior. For example, if you are using Casting AND you apply roles on initialize:
+
+```ruby
+context = ActiviatingAccount.new(current_user, Account.find(123))
+context.do_something
+current_user.some_behavior # this method is still available
+current_user.uncast # you'll have to manually cleanup
+```
+
+But if you go with the default and apply behaviors on trigger, your roles will be cleaned up automatically:
+
+```ruby
+context = ActiviatingAccount.new(current_user, Account.find(123))
+context.do_something
+current_user.some_behavior # NoMethodError
+```
+
 ## Dependencies
 
 The dependencies are minimal. The plan is to keep it that way but allow you to configure things as you need.
 
 If you're using [Casting](http://github.com/saturnflyer/casting), for example, Surrounded will attempt to use that before extending an object, but it will still work without it.
 
-## To Do
-
-Casting provides a way to remove features outside of a block. For now, the code doesn't attempt to `uncast` an object. It will in the future though.
-
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'surrounded'
+```ruby
+gem 'surrounded'
+```
 
 And then execute:
 

data/examples/rails.rb

@@ -18,13 +18,13 @@ end
 class SomeUseCase
   extend Surrounded::Context
 
-  setup(:user, :other_user, :listener)
+  setup(:admin, :other_user, :listener)
 
   trigger :do_something do
-    user.something
+    admin.something
   end
 
-  module User
+  module Admin
     def something
       puts "Hello, #{other_user}"
       listener.redirect_to('/')
@@ -33,33 +33,7 @@ class SomeUseCase
 end
 
 class SomethingController < ApplicationController
-  use_case = :SomeUseCase
   def create
-    use_case = :SomeOverrideUseCase
-    trigger :do_something, current_user, User.last
-  end
-
-  def trigger(meth, *args)
-    use_case.new(*(args << self)).send(meth)
-  end
-
-  def self.use_case=(name)
-    @_default_use_case_name = name
-  end
-
-  def self.use_case
-    @_default_use_case_name.to_s.constantize
-  end
-
-  def use_case=(name)
-    @_use_case_name = name
-  end
-
-  def use_case
-    if defined?(@_use_case_name)
-      @_use_case_name.to_s.constantize
-    else
-      self.class.use_case
-    end
+    SomeUseCase.new(current_user, User.last, self).do_something
   end
 end

data/examples/wrappers.rb

@@ -0,0 +1,39 @@
+# If you want to use wrappers, here's how you could
+
+require 'surrounded/context'
+require 'delegate'
+class WrapperContext
+  extend Surrounded::Context
+
+  apply_roles_on(:trigger)
+  setup(:admin, :task)
+
+  class Admin < SimpleDelegator
+    def some_admin_method
+      puts 'hello from the admin wrapper!'
+    end
+  end
+
+  trigger :do_something do
+    admin.some_admin_method
+  end
+
+  private
+
+  def add_role_methods(obj, wrapper)
+    assign_role(role_name(wrapper), wrapper.new(obj))
+  end
+
+  def remove_role_methods(obj, wrapper)
+    # in this case, the obj is already wrapped
+    core_object = self.send(role_name(wrapper)).__getobj__
+    assign_role(role_name(wrapper), core_object)
+  end
+
+  def role_name(klass)
+    klass.name.split("::").last.gsub(/([A-Z])/){ "_#{$1.downcase}" }.sub(/^_/,'')
+  end
+end
+
+context = WrapperContext.new(Object.new, Object.new)
+context.do_something

data/lib/surrounded.rb

@@ -1,8 +1,51 @@
 require "surrounded/version"
 
 module Surrounded
+  def self.included(klass)
+    klass.class_eval {
+      extend Surrounded::Contextual
+    }
+    unless klass.is_a?(Class)
+      def klass.extended(object)
+        Surrounded.create_surroundings(object)
+      end
+    end
+  end
+
+  def self.extended(object)
+    Surrounded.create_surroundings(object)
+  end
+
+  module Contextual
+    def new(*args)
+      instance = super
+      Surrounded.create_surroundings(instance)
+      instance
+    end
+  end
+
+  def store_context(ctxt)
+    surroundings.unshift(ctxt)
+  end
+
+  def remove_context
+    surroundings.shift
+  end
+
   private
 
+  def self.create_surroundings(obj)
+    obj.instance_variable_set(:@__surroundings__, [])
+  end
+
+  def surroundings
+    @__surroundings__
+  end
+
+  def context
+    surroundings.first || NullContext.new
+  end
+
   def method_missing(meth, *args, &block)
     context.role?(meth){} || super
   end
@@ -11,11 +54,6 @@ module Surrounded
     !!context.role?(meth){} || super
   end
 
-  def context
-    Thread.current[:context] ||= []
-    Thread.current[:context].first || NullContext.new
-  end
-
   class NullContext < BasicObject
     def role?(*args)
       nil

data/lib/surrounded/context.rb

@@ -1,36 +1,50 @@
 require 'set'
+require 'surrounded/context/role_map'
 module Surrounded
   module Context
     def self.extended(base)
       base.send(:include, InstanceMethods)
+      base.singleton_class.send(:alias_method, :setup, :initialize)
     end
 
     def triggers
       @triggers.dup
     end
 
+    def policy
+      @policy ||= :trigger
+    end
+
     private
 
-    def setup(*setup_args)
-      attr_reader(*setup_args)
-      private(*setup_args)
+    def apply_roles_on(which)
+      @policy = which
+    end
 
-      define_method(:initialize){ |*args|
-        Hash[setup_args.zip(args)].each{ |role, object|
+    def initialize(*setup_args)
+      private_attr_reader(*setup_args)
 
-          role_module_name = Context.classify_string(role)
-          klass = self.class
+      # I want this to work so I can set the arity on initialize:
+      # class_eval %Q<
+      #   def initialize(#{*setup_args})
+      #     arguments = parameters.map{|arg| eval(arg[1].to_s) }
+      #     map_roles(setup_args.zip(arguments))
+      #     apply_roles if policy == :initialize
+      #   end
+      # >
 
-          if mod = klass.const_defined?(role_module_name) && !mod.is_a?(Class)
-            object = Context.modify(object, klass.const_get(role_module_name))
-          end
+      define_method(:initialize){ |*args|
+        map_roles(setup_args.zip(args))
 
-          roles[role.to_s] = object
-          instance_variable_set("@#{role}", object)
-        }
+        apply_roles if policy == :initialize
       }
     end
 
+    def private_attr_reader(*method_names)
+      attr_reader(*method_names)
+      private(*method_names)
+    end
+
     def trigger(name, *args, &block)
       store_trigger(name)
 
@@ -40,10 +54,12 @@ module Surrounded
 
       define_method(name, *args){
         begin
-          (Thread.current[:context] ||= []).unshift(self)
+          apply_roles if policy == :trigger
+
           self.send("trigger_#{name}", *args)
+
         ensure
-          (Thread.current[:context] ||= []).shift
+          remove_roles if policy == :trigger
         end
       }
     end
@@ -53,23 +69,11 @@ module Surrounded
       @triggers << name
     end
 
-    def self.classify_string(string)
-      string.to_s.gsub(/(?:^|_)([a-z])/) { $1.upcase }
-    end
-
-    def self.modify(obj, mod)
-      return obj if mod.is_a?(Class)
-      if obj.respond_to?(:cast_as)
-        obj.cast_as(mod)
-      else
-        obj.extend(mod)
-      end
-    end
-
     module InstanceMethods
       def role?(name, &block)
+        return false unless role_map.role?(name)
         accessor = eval('self', block.binding)
-        roles.values.include?(accessor) && roles[name.to_s]
+        role_map.role_player?(accessor) && role_map.assigned_player(name)
       end
 
       def triggers
@@ -78,8 +82,99 @@ module Surrounded
 
       private
 
-      def roles
-        @roles ||= {}
+      def role_map
+        @role_map ||= RoleMap.new
+      end
+
+      def map_roles(role_object_array)
+        role_object_array.each do |role, object|
+          map_role(role, role_behavior_name(role), object)
+        end
+      end
+
+      def map_role(role, mod_name, object)
+        instance_variable_set("@#{role}", object)
+        role_map.update(role, mod_name, object)
+      end
+
+      def policy
+        @policy ||= self.class.policy
+      end
+
+      def add_interface(role, behavior, object)
+        applicator = behavior.is_a?(Class) ? method(:add_class_interface) : method(:add_module_interface)
+
+        role_player = applicator.call(object, behavior)
+        map_role(role, role_module_basename(behavior), role_player)
+        role_player.store_context(self)
+        role_player
+      end
+
+      def add_module_interface(obj, mod)
+        adder_name = module_extension_methods.find{|meth| obj.respond_to?(meth) }
+        return obj if !adder_name
+
+        obj.method(adder_name).call(mod)
+        obj
+      end
+
+      def add_class_interface(obj, klass)
+        wrapper_name = wrap_methods.find{|meth| klass.respond_to?(meth) }
+        return obj if !wrapper_name
+
+        klass.method(wrapper_name).call(obj)
+      end
+
+      def remove_interface(role, behavior, object)
+        remover_name = (module_removal_methods + unwrap_methods).find{|meth| object.respond_to?(meth) }
+        return object if !remover_name
+
+        object.remove_context
+        role_player = object.method(remover_name).call
+
+        map_role(role, role_module_basename(behavior), role_player)
+
+        role_player
+      end
+
+      def apply_roles
+        traverse_map method(:add_interface)
+      end
+
+      def remove_roles
+        traverse_map method(:remove_interface)
+      end
+
+      def traverse_map(applicator)
+        role_map.each do |role, mod_name, object|
+          if self.class.const_defined?(mod_name)
+            applicator.call(role, self.class.const_get(mod_name), object)
+          end
+        end
+      end
+
+      def module_extension_methods
+        [:cast_as, :extend]
+      end
+
+      def wrap_methods
+        [:new]
+      end
+
+      def module_removal_methods
+        [:uncast]
+      end
+
+      def unwrap_methods
+        [:__getobj__]
+      end
+
+      def role_behavior_name(role)
+        role.to_s.gsub(/(?:^|_)([a-z])/) { $1.upcase }.sub(/_\d+/,'')
+      end
+
+      def role_module_basename(mod)
+        mod.to_s.split('::').last
       end
     end
   end

data/lib/surrounded/context/role_map.rb

@@ -0,0 +1,21 @@
+require 'triad'
+require 'surrounded/context_errors'
+module Surrounded
+  module Context
+    class RoleMap < Triad
+      def role?(role)
+        keys.include?(role)
+      end
+
+      def role_player?(object)
+        !values(object).empty?
+      rescue ::Triad::ValueNotPresent
+        false
+      end
+
+      def assigned_player(role)
+        values(role).first
+      end
+    end
+  end
+end

data/lib/surrounded/context_errors.rb

@@ -0,0 +1,6 @@
+require 'triad'
+module Surrounded
+  module Context
+    class InvalidRole < ::Triad::KeyNotPresent; end
+  end
+end

data/lib/surrounded/version.rb

@@ -1,3 +1,3 @@
 module Surrounded
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/surrounded.gemspec

@@ -18,6 +18,8 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
+  spec.add_dependency "triad", "~> 0.1.2"
+
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
 end

data/test/example_threaded_test.rb

@@ -0,0 +1,70 @@
+require 'test_helper'
+
+class ThreadedContext
+  extend Surrounded::Context
+
+  def initialize(leader, members)
+    role_names = [:leader, :members]
+    role_players = [leader, members]
+
+    role_names.concat(members.map{|member| :"member_#{member.object_id}" })
+    role_players.concat(members)
+
+    map_roles(role_names.zip(role_players))
+
+  end
+  private_attr_reader :leader, :members
+
+  trigger :meet do
+    result = []
+    result << leader.greet
+    result << members.concurrent_map do |member|
+      result << member.greet
+    end
+    result.flatten.join(' ')
+  end
+
+  module Leader
+    def greet
+      "Hello everyone. I am #{name}"
+    end
+  end
+
+  module Member
+    def greet
+      "Hello #{leader.name}, I am #{name}"
+    end
+  end
+
+  module Members
+    include Surrounded
+
+    def concurrent_map
+      map do |member|
+        Thread.new do
+          yield member
+        end
+      end.each(&:join)
+    end
+  end
+end
+
+describe ThreadedContext do
+  let(:jim){ User.new('Jim') }
+  let(:amy){ User.new('Amy') }
+  let(:guille){ User.new('Guille') }
+  let(:jason){ User.new('Jason') }
+  let(:dave){ User.new('Dave') }
+
+  let(:greeter){ jim }
+  let(:members){ [amy, guille, jason, dave] }
+
+  it 'works in multi-threaded environments' do
+    meeting = ThreadedContext.new(jim, members)
+
+    result = meeting.meet
+
+    assert_includes result, 'Hello everyone. I am Jim'
+    assert_includes result, 'Hello Jim, I am Amy'
+  end
+end

data/test/example_wrapper_test.rb

@@ -0,0 +1,30 @@
+require 'test_helper'
+
+# If you want to use wrappers, here's how you could
+require 'delegate'
+class WrapperContext
+  extend Surrounded::Context
+
+  apply_roles_on(:trigger)
+  setup(:admin, :task)
+
+  class Admin < SimpleDelegator
+    include Surrounded
+    def some_admin_method
+      'hello from the admin wrapper!'
+    end
+  end
+
+  trigger :do_something do
+    admin.some_admin_method
+  end
+end
+
+describe WrapperContext do
+  let(:context){
+    WrapperContext.new(Object.new, Object.new)
+  }
+  it 'wraps objects and allows them to respond to new methods' do
+    assert_equal 'hello from the admin wrapper!', context.do_something
+  end
+end

data/test/surrounded_context_test.rb

@@ -83,8 +83,7 @@ describe Surrounded::Context, '#role?' do
 end
 
 require 'casting'
-CastingUser = Struct.new(:name)
-class CastingUser
+class CastingUser < User
   include Casting::Client
   delegate_missing_methods
 end
@@ -92,7 +91,7 @@ end
 class RoleAssignmentContext
   extend Surrounded::Context
 
-  setup(:user, :other_user)
+  initialize(:user, :other_user)
 
   trigger :user_ancestors do
     user.singleton_class.ancestors
@@ -118,7 +117,15 @@ class RoleAssignmentContext
   end
 end
 
+describe Surrounded::Context, '.setup' do
+  it 'defines an initialize method accepting the same arguments' do
+    skip "not yet implemented. may not be possible"
+    assert_equal 2, RoleAssignmentContext.instance_method(:initialize).arity
+  end
+end
+
 describe Surrounded::Context, 'assigning roles' do
+  include Surrounded
   let(:user){ CastingUser.new("Jim") }
   let(:other_user){ User.new("Guille") }
   let(:context){ RoleAssignmentContext.new(user, other_user) }
@@ -136,17 +143,19 @@ describe Surrounded::Context, 'assigning roles' do
     assert context.check_other_user_response
   end
 
-  it 'will not use classes as roles' do
+  it 'will use classes as roles' do
     ClassRoleAssignmentContext = Class.new do
       extend Surrounded::Context
 
-      setup(:thing, :the_test)
+      initialize(:thing, :the_test)
 
       trigger :check_user_response do
-        the_test.refute thing.respond_to?(:method_from_class), 'did respond to :method_from_class'
+        the_test.assert_respond_to thing, :method_from_class
       end
 
       class Thing
+        include Surrounded
+        def initialize(obj); end
         def method_from_class; end
       end
 

data/test/surrounded_test.rb

@@ -5,7 +5,6 @@ describe "Surrounded", 'without context' do
   let(:jim){ User.new("Jim") }
 
   it "never has context roles" do
-    Thread.current[:context] = []
     assert_nil jim.send(:context).role?('anything')
   end
 
@@ -21,16 +20,18 @@ describe "Surrounded" do
   }
 
   before do
-    Thread.current[:context] = [context]
+    jim.store_context(context)
+    guille.store_context(context)
   end
 
   it "has access to objects in the context" do
     assert_equal jim.other_user, guille
   end
+
   it "responds to messages for roles on the context" do
     assert jim.respond_to?(:other_user)
 
-    Thread.current[:context] = []
+    jim.remove_context
 
     refute jim.respond_to?(:other_user)
   end
@@ -40,4 +41,33 @@ describe "Surrounded" do
       external_user.user
     }
   end
+end
+
+describe "Surrounded", "added to an existing object" do
+  it "allows the object to store its context" do
+    object = Object.new
+    assert_raises(NoMethodError){
+      object.store_context(self)
+    }
+    object.extend(Surrounded)
+    assert object.store_context(self)
+    assert object.remove_context
+  end
+end
+
+module SpecialSurrounding
+  include Surrounded
+end
+
+describe "Surrounded", "added to an object through another module" do
+  it "allows the object to store its context" do
+    object = Array.new
+    assert_raises(NoMethodError){
+      object.store_context(self)
+    }
+    object.extend(SpecialSurrounding)
+    assert object.store_context(self)
+    assert object.remove_context
+    assert object.send(:context)
+  end
 end

data/test/test_helper.rb

@@ -9,9 +9,12 @@ end
 require 'surrounded'
 require 'surrounded/context'
 
-User = Struct.new(:name)
 class User
   include Surrounded
+  def initialize(name)
+    @name = name
+  end
+  attr_reader :name
 end
 
 class TestContext

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: surrounded
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - '''Jim Gay'''
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-12 00:00:00.000000000 Z
+date: 2013-07-10 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: triad
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.1.2
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -53,10 +67,15 @@ files:
 - README.md
 - Rakefile
 - examples/rails.rb
+- examples/wrappers.rb
 - lib/surrounded.rb
 - lib/surrounded/context.rb
+- lib/surrounded/context/role_map.rb
+- lib/surrounded/context_errors.rb
 - lib/surrounded/version.rb
 - surrounded.gemspec
+- test/example_threaded_test.rb
+- test/example_wrapper_test.rb
 - test/surrounded_context_test.rb
 - test/surrounded_test.rb
 - test/test_helper.rb
@@ -85,6 +104,9 @@ signing_key:
 specification_version: 4
 summary: Create encapsulated environments for your objects.
 test_files:
+- test/example_threaded_test.rb
+- test/example_wrapper_test.rb
 - test/surrounded_context_test.rb
 - test/surrounded_test.rb
 - test/test_helper.rb
+has_rdoc: