surrounded 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 004d807c4309fea2abc8847f5c23aba8994f6829
-  data.tar.gz: 3a42c0a074f5b1e3f179eb3763ab21a36afbcc19
+  metadata.gz: 3e6e141d7aa5fdf78d69d250369fa15f2f6b5f6d
+  data.tar.gz: 5251f5c762065460afa6da69f0da2bf2f68529dc
 SHA512:
-  metadata.gz: 59292a0a8d86b9703e2364df3416613af3ab18695ee6afa064b4597f57c3c0489e0c551bebe00edc6d19b8d9c618f541d78aec23dbc42cc9d81e9f9b9e448755
-  data.tar.gz: f4eb083c7d739c79967aef23e57436770eaadc16ea6a1b30b19cd5a0e8eb59c1a521c7d3733cec411b77b97363426409990b012a5c8b9afd4abe1c194af8208d
+  metadata.gz: 7188a2fadebd4d332f402c8fba1cabb77968623a698a02a083ef59266a1ee8b4223216f5aa70d9c5886ddc8af1fef9058686a67ce512ab94e4571cc42e23da39
+  data.tar.gz: 0ca5c9b9ead86e6d87d0209c5fa0e59cb4b67ac957c0d0425f85704270f1879702cade79de3af98323df85ff1dc9fe2a3a22a7a19e789adf58bcdda534ea89d9

data/README.md

@@ -71,7 +71,7 @@ If you're going to be doing this a lot, it's painful. Here's what `Surrounded` d
 class MyEnvironment
   extend Surrounded::Context
 
-  setup(:employee, :boss)
+  initialize(:employee, :boss)
 
   module Employee
     # extra behavior here...
@@ -97,7 +97,7 @@ With that, all instances of `User` have implicit access to their surroundings.
 
 _Yeah... How?_
 
-Via `method_missing` those `User` instances can access a `context` object stored in `Thread.current`. I didn't mention how the context is set, however.
+Via `method_missing` those `User` instances can access a `context` object it stores in a `@__surroundings__` collection. I didn't mention how the context is set, however.
 
 Your environment will have methods of it's own that will trigger actions on the objects inside, but we need those trigger methods to set the environment instance as the current context so that the objects it contains can access them.
 
@@ -192,7 +192,7 @@ class ActiviatingAccount
   apply_roles_on(:trigger) # this is the default
   # apply_roles_on(:initialize) # set this to apply behavior from the start
 
-  setup(:activator, :account)
+  initialize(:activator, :account)
 
   module Activator
     def some_behavior; end
@@ -228,6 +228,38 @@ context.do_something
 current_user.some_behavior # NoMethodError
 ```
 
+## How's the performance?
+
+I haven't really tested yet, but there are several ways you can add behavior to your objects.
+
+There are a few defaults built in.
+
+1. If you define modules for the added behavior, the code will run `object.extend(RoleInterface)`
+2. If you are using [casting](http://github.com/saturnflyer/casting), the code will run `object.cast_as(RoleInterface)`
+3. If you would rather use wrappers you can define classes and the code will run `RoleInterface.new(object)` and assumes that the `new` method takes 1 argument. You'll need to remember to `include Surrounded` in your classes, however.
+4. If you want to use wrappers but would rather not muck about with including modules and whatnot, you can define them like this:
+
+```
+class SomeContext
+  extend Surrounded::Context
+
+  initialize(:admin, :user)
+
+  wrap :admin do
+    # special methods defined here
+  end
+```
+
+The `wrap` method will create a class of the given name (`Admin` in this case) and will inherit from `SimpleDelegator` from the Ruby standard library _and_ will `include Surrounded`.
+
+Lastly, there's a 5th option if you're using Ruby 2.x: `interface`.
+
+The `interface` method acts similarly to the `wrap` method in that it returns an object that is not actually the object you want. But an `interface` is different in that it will apply methods from a module instead of using methods defined in a SimpleDelegator subclass. How is that important? Well you are free to use things like instance variables in your methods because they will be executed in the context of the object. This is unlike methods in a SimpleDelegator where the wrapper maintains its own instance variables.
+
+_Which should I use?_
+
+Start with the default and see how it goes, then try another approach and measure the changes.
+
 ## Dependencies
 
 The dependencies are minimal. The plan is to keep it that way but allow you to configure things as you need.

data/lib/surrounded/context.rb

@@ -1,5 +1,7 @@
 require 'set'
 require 'surrounded/context/role_map'
+require 'redcard'
+
 module Surrounded
   module Context
     def self.extended(base)
@@ -7,12 +9,14 @@ module Surrounded
       base.singleton_class.send(:alias_method, :setup, :initialize)
     end
 
-    def triggers
-      @triggers.dup
+    def new(*)
+      instance = super
+      instance.instance_variable_set('@__apply_role_policy', __apply_role_policy)
+      instance
     end
 
-    def policy
-      @policy ||= :trigger
+    def triggers
+      @triggers.dup
     end
 
     private
@@ -24,8 +28,26 @@ module Surrounded
       klass.send(:include, Surrounded)
     end
 
+    if RedCard.check '2.0'
+      def interface(name, &block)
+        class_basename = name.to_s.gsub(/(?:^|_)([a-z])/){ $1.upcase }
+        interface_name = class_basename + 'Interface'
+
+        behavior = const_set(interface_name, Module.new(&block))
+
+        require 'surrounded/context/negotiator'
+        define_method(name) do
+          instance_variable_set("@#{name}", Negotiator.new(role_map.assigned_player(name), behavior))
+        end
+      end
+    end
+
     def apply_roles_on(which)
-      @policy = which
+      @__apply_role_policy = which
+    end
+
+    def __apply_role_policy
+      @__apply_role_policy ||= :trigger
     end
 
     def initialize(*setup_args)
@@ -33,9 +55,10 @@ module Surrounded
 
       class_eval "
         def initialize(#{setup_args.join(',')})
+          @__apply_role_policy = :#{__apply_role_policy}
           arguments = method(__method__).parameters.map{|arg| eval(arg[1].to_s) }
           map_roles(#{setup_args}.zip(arguments))
-          apply_roles if policy == :initialize
+          apply_roles if __apply_role_policy == :initialize
         end
       "
     end
@@ -54,12 +77,12 @@ module Surrounded
 
       define_method(name, *args){
         begin
-          apply_roles if policy == :trigger
+          apply_roles if __apply_role_policy == :trigger
 
           self.send("trigger_#{name}", *args)
 
         ensure
-          remove_roles if policy == :trigger
+          remove_roles if __apply_role_policy == :trigger
         end
       }
     end
@@ -97,8 +120,8 @@ module Surrounded
         role_map.update(role, mod_name, object)
       end
 
-      def policy
-        @policy ||= self.class.policy
+      def __apply_role_policy
+        @__apply_role_policy
       end
 
       def add_interface(role, behavior, object)

data/lib/surrounded/context/negotiator.rb

@@ -0,0 +1,28 @@
+module Surrounded
+  module Context
+    class Negotiator
+      identity = "__send__|object_id"
+
+      instance_methods.each do |meth|
+        unless meth.to_s =~ /#{identity}/
+          undef_method meth
+        end
+      end
+
+      private
+
+      def initialize(object, behavior)
+        @object, @behavior = object, behavior
+      end
+
+      def method_missing(meth, *args, &block)
+        if @behavior.instance_methods.include?(meth)
+          the_method = @behavior.instance_method(meth)
+          the_method.bind(@object).call(*args, &block)
+        else
+          @object.send(meth, *args, &block)
+        end
+      end
+    end
+  end
+end

data/lib/surrounded/version.rb

@@ -1,3 +1,3 @@
 module Surrounded
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/surrounded.gemspec

@@ -18,7 +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_dependency "triad",  "~> 0.1.2"
+  spec.add_dependency "redcard","~> 1.1.0"
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"

data/test/example_proxy_test.rb

@@ -0,0 +1,55 @@
+require 'test_helper'
+
+if RedCard.check '2.0'
+
+# If you want to use wrappers, here's how you could
+class ProxyContext
+  extend Surrounded::Context
+
+  apply_roles_on(:trigger)
+  initialize(:admin, :task)
+
+  interface :admin do
+    def some_admin_method
+      "hello from #{name}, the admin interface!"
+    end
+  end
+
+  trigger :do_something do
+    admin.some_admin_method
+  end
+
+  trigger :admin_name do
+    admin.name
+  end
+
+  trigger :admin_missing_method do
+    admin.method_that_does_not_exist
+  end
+end
+
+ProxyUser = Struct.new(:name)
+
+describe ProxyContext do
+  let(:user){
+    ProxyUser.new('Jim')
+  }
+  let(:context){
+    ProxyContext.new(user, Object.new)
+  }
+  it 'proxys methods between objects and its interface' do
+    assert_equal 'hello from Jim, the admin interface!', context.do_something
+  end
+
+  it 'forwards methods that the object responds to' do
+    assert_equal 'Jim', context.admin_name
+  end
+
+  it 'passes missing methods up the ancestry of the object' do
+    err = ->{ context.admin_missing_method }.must_raise(NoMethodError)
+
+    assert_match 'ProxyUser name="Jim"', err.message
+  end
+end
+
+end # RedCard.check '2.0'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: surrounded
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - '''Jim Gay'''
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-10 00:00:00.000000000 Z
+date: 2013-07-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: triad
@@ -24,6 +24,20 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 0.1.2
+- !ruby/object:Gem::Dependency
+  name: redcard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.1.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -70,10 +84,12 @@ files:
 - examples/wrappers.rb
 - lib/surrounded.rb
 - lib/surrounded/context.rb
+- lib/surrounded/context/negotiator.rb
 - lib/surrounded/context/role_map.rb
 - lib/surrounded/context_errors.rb
 - lib/surrounded/version.rb
 - surrounded.gemspec
+- test/example_proxy_test.rb
 - test/example_threaded_test.rb
 - test/example_wrapper_test.rb
 - test/surrounded_context_test.rb
@@ -104,6 +120,7 @@ signing_key:
 specification_version: 4
 summary: Create encapsulated environments for your objects.
 test_files:
+- test/example_proxy_test.rb
 - test/example_threaded_test.rb
 - test/example_wrapper_test.rb
 - test/surrounded_context_test.rb