surrounded 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3e6e141d7aa5fdf78d69d250369fa15f2f6b5f6d
-  data.tar.gz: 5251f5c762065460afa6da69f0da2bf2f68529dc
+  metadata.gz: 06fdae60ee9aa6572db5ba8151e49bfba7257501
+  data.tar.gz: dbed795a64a2ed83a405725e4a0bbf826952cc32
 SHA512:
-  metadata.gz: 7188a2fadebd4d332f402c8fba1cabb77968623a698a02a083ef59266a1ee8b4223216f5aa70d9c5886ddc8af1fef9058686a67ce512ab94e4571cc42e23da39
-  data.tar.gz: 0ca5c9b9ead86e6d87d0209c5fa0e59cb4b67ac957c0d0425f85704270f1879702cade79de3af98323df85ff1dc9fe2a3a22a7a19e789adf58bcdda534ea89d9
+  metadata.gz: b930aaf822c3a9b77c8fb9390e8dd32d64077b3ede2f6cd8f347f429b07ad8b60c899585cf1453a0c7359d3eab48af0b73c64f19a33a10213d5ce6cb2b27fcfe
+  data.tar.gz: 00d58b00643d05d17f4ece1f7b1092104f4747535fe67368441fcfe57f0a52d2ebc31a4fba39569601d7d99d37a321cedc8f7be3fe713d88ee7d687d71b0d5ff

data/examples/rails.rb

@@ -34,6 +34,10 @@ end
 
 class SomethingController < ApplicationController
   def create
-    SomeUseCase.new(current_user, User.last, self).do_something
+    surround(current_user, User.last).do_something
+  end
+
+  def surround(admin, other)
+    SomeUseCase.new(admin, other, self)
   end
 end

data/lib/surrounded/README.md

@@ -0,0 +1,209 @@
+# Surrounded aims to make things simple and get out of your way.
+
+Most of what you care about is defining the behavior of objects. How they interact is important.
+The purpose of this library is to clear away the details of getting things setup.
+
+You should read the [main README](../../README.md) to get the gist of what's going on, if you haven't.
+
+When you get started, you'll probably be specifying things exactly how you want them. But you can easily make changes.
+
+```ruby
+class MoneyTransfer
+  extend Surrounded::Context
+
+  def initialize(source, destination, amount)
+    @source = source.extend(Source)
+    @destination = destination
+    @amount = amount
+  end
+
+  attr_reader :source, :destination, :amount
+  private :source, :destination, :amount
+
+  def execute
+    source.transfer
+  end
+
+  module Source
+    def transfer
+      self.balance -= amount
+      destination.balance += amount
+      self
+    end
+  end
+end
+```
+
+That's a lot of setup just to create the `execute` and `transfer` methods.
+
+Here's a shortened version:
+
+```ruby
+class MoneyTransfer
+  extend Surrounded::Context
+
+  initialize(:source, :destination, :amount)
+
+  trigger :execute do
+    source.transfer
+  end
+
+  module Source
+    def transfer
+      self.balance -= amount
+      destination.balance += amount
+      self
+    end
+  end
+end
+```
+
+Now it's cleaned up a bit and is much easier to see what's important.
+If you decide you want to try out wrappers, you can start making changes to use `SimpleDelegator` from the standard library, but you'll have to remember to 1) `include Surrounded` 2) to do the initialize yourself again and 3) return the correct object from your role method.
+
+Simply by changing your mind to use `SimpleDelegator`, here's what you'll need to do:
+
+```ruby
+class MoneyTransfer
+  extend Surrounded::Context
+
+  def initialize(source, destination, amount)
+    @source = Source.new(source)
+    @destination = destination
+    @amount = amount
+  end
+
+  attr_reader :source, :destination, :amount
+  private :source, :destination, :amount
+
+  def execute
+    source.transfer
+  end
+
+  class Source < SimpleDelegator
+    include Surrounded
+
+    def transfer
+      self.balance -= amount
+      destination.balance += amount
+      __getobj__
+    end
+  end
+end
+```
+Once again, it's big and ugly. But surrounded has your back; you can istead do this:
+
+```ruby
+class MoneyTransfer
+  extend Surrounded::Context
+
+  initialize(:source, :destination, :amount)
+
+  trigger :execute do
+    source.transfer
+  end
+
+  wrap :source do
+    def transfer
+      self.balance -= amount
+      destination.balance += amount
+      __getobj__
+    end
+  end
+end
+```
+
+That's not much different from the module and it takes care of using `SimpleDelegator` and including `Surrounded` for you. If you want to make changing your approach even easier, you can use the `role` method instead.
+
+```ruby
+class MoneyTransfer
+  extend Surrounded::Context
+
+  initialize(:source, :destination, :amount)
+
+  trigger :execute do
+    source.transfer
+  end
+
+  role :source, :wrap do
+    def transfer
+      self.balance -= amount
+      destination.balance += amount
+      __getobj__
+    end
+  end
+end
+```
+
+This way you can swap between implementations:
+
+```ruby
+
+  # this uses modules
+  role :source do
+    def transfer
+      self.balance -= amount
+      destination.balance += amount
+      self
+    end
+  end
+
+  # this uses SimpleDelegator and Surrounded
+  role :source do
+    def transfer
+      self.balance -= amount
+      destination.balance += amount
+      __getobj__
+    end
+  end
+
+  # this uses a special interface object which pulls
+  # methods from a module and applies them to your object.
+  role :source, :interface do
+    def transfer
+      self.balance -= amount
+      destination.balance += amount
+      self
+    end
+  end
+```
+
+The `:interface` option is a special object which has all of its methods removed (excepting `__send__` and `object_id`) so that other methods will be pulled from the ones that you define, or from the object it attempts to proxy.
+
+Notice that the `:interface` allows you to return `self` whereas the `:wrap` acts more like a wrapper and forces you to deal with that shortcoming by using it's wrapped-object-accessor method: `__getobj__`.
+
+If you'd like to choose one and use it all the time, you can set the default:
+
+```ruby
+class MoneyTransfer
+  extend Surrounded::Context
+
+  self.default_role_type = :interface # also :wrap, :wrapper, or :module
+
+  role :source do
+    def transfer
+      self.balance -= amount
+      destination.balance += amount
+      self
+    end
+  end
+end
+```
+
+Or, if you like, you can choose the default for your entire project:
+
+```ruby
+Surrounded::Context.default_role_type = :interface
+
+class MoneyTransfer
+  extend Surrounded::Context
+
+  role :source do
+    def transfer
+      self.balance -= amount
+      destination.balance += amount
+      self
+    end
+  end
+end
+```

data/lib/surrounded/context.rb

@@ -9,6 +9,14 @@ module Surrounded
       base.singleton_class.send(:alias_method, :setup, :initialize)
     end
 
+    def self.default_role_type
+      @default_role_type ||= :module
+    end
+
+    def self.default_role_type=(type)
+      @default_role_type = type
+    end
+
     def new(*)
       instance = super
       instance.instance_variable_set('@__apply_role_policy', __apply_role_policy)
@@ -21,10 +29,37 @@ module Surrounded
 
     private
 
+    def private_const_set(name, const)
+      const = const_set(name, const)
+      private_constant name
+      const
+    end
+
+    def default_role_type
+      @default_role_type ||= Surrounded::Context.default_role_type
+    end
+
+    def default_role_type=(type)
+      @default_role_type = type
+    end
+
+    def role(name, type=nil, &block)
+      role_type = type || default_role_type
+      case role_type
+      when :wrap, :wrapper then wrap(name, &block)
+      when :interface then interface(name, &block)
+      when :module then
+        mod_name = name.to_s.gsub(/(?:^|_)([a-z])/){ $1.upcase }
+        private_const_set(mod_name, Module.new(&block))
+      else
+        raise InvalidRoleType.new
+      end
+    end
+
     def wrap(name, &block)
       require 'delegate'
       wrapper_name = name.to_s.gsub(/(?:^|_)([a-z])/){ $1.upcase }
-      klass = const_set(wrapper_name, Class.new(SimpleDelegator, &block))
+      klass = private_const_set(wrapper_name, Class.new(SimpleDelegator, &block))
       klass.send(:include, Surrounded)
     end
 
@@ -33,7 +68,7 @@ module Surrounded
         class_basename = name.to_s.gsub(/(?:^|_)([a-z])/){ $1.upcase }
         interface_name = class_basename + 'Interface'
 
-        behavior = const_set(interface_name, Module.new(&block))
+        behavior = private_const_set(interface_name, Module.new(&block))
 
         require 'surrounded/context/negotiator'
         define_method(name) do
@@ -92,6 +127,12 @@ module Surrounded
       @triggers << name
     end
 
+    def role_const(name)
+      if const_defined?(name)
+        const_get(name)
+      end
+    end
+
     module InstanceMethods
       def role?(name, &block)
         return false unless role_map.role?(name)
@@ -128,7 +169,7 @@ module Surrounded
         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)
+        map_role(role, role_module_basename(behavior), role_player) if behavior
         role_player.store_context(self)
         role_player
       end
@@ -155,7 +196,7 @@ module Surrounded
         object.remove_context
         role_player = object.method(remover_name).call
 
-        map_role(role, role_module_basename(behavior), role_player)
+        map_role(role, role_module_basename(behavior), role_player) if behavior
 
         role_player
       end
@@ -170,8 +211,8 @@ module Surrounded
 
       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)
+          if role_const_defined?(mod_name)
+            applicator.call(role, role_const(mod_name), object)
           end
         end
       end
@@ -199,6 +240,14 @@ module Surrounded
       def role_module_basename(mod)
         mod.to_s.split('::').last
       end
+
+      def role_const(name)
+        self.class.send(:role_const, name)
+      end
+
+      def role_const_defined?(name)
+        self.class.const_defined?(name)
+      end
     end
   end
 end

data/lib/surrounded/context/negotiator.rb

@@ -11,13 +11,13 @@ module Surrounded
 
       private
 
-      def initialize(object, behavior)
-        @object, @behavior = object, behavior
+      def initialize(object, behaviors)
+        @object, @behaviors = object, behaviors
       end
 
       def method_missing(meth, *args, &block)
-        if @behavior.instance_methods.include?(meth)
-          the_method = @behavior.instance_method(meth)
+        if @behaviors.instance_methods.include?(meth)
+          the_method = @behaviors.instance_method(meth)
           the_method.bind(@object).call(*args, &block)
         else
           @object.send(meth, *args, &block)

data/lib/surrounded/context_errors.rb

@@ -2,5 +2,6 @@ require 'triad'
 module Surrounded
   module Context
     class InvalidRole < ::Triad::KeyNotPresent; end
+    class InvalidRoleType < StandardError; end
   end
 end

data/lib/surrounded/version.rb

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

data/test/role_context_method_test.rb

@@ -0,0 +1,143 @@
+require 'test_helper'
+
+
+describe Surrounded::Context, '.role' do
+  class RoleContextTester
+    extend Surrounded::Context
+
+    role :admin do
+    end
+  end
+
+  describe 'modules' do
+    it 'creates a module' do
+      role = RoleContextTester.const_get('Admin')
+      refute_instance_of Class, role
+      assert_kind_of Module, role
+    end
+
+    it 'marks the constant private' do
+      error = assert_raises(NameError){
+        RoleContextTester::Admin
+      }
+      assert_match /private constant/, error.message
+    end
+  end
+
+  class WrapperRoleContext
+    extend Surrounded::Context
+
+    role :admin, :wrap do
+
+    end
+  end
+
+  describe 'wrappers' do
+    it 'creates a wrapper' do
+      role = WrapperRoleContext.const_get('Admin')
+      assert_includes(role.ancestors, SimpleDelegator)
+    end
+
+    it 'marks the constant private' do
+      error = assert_raises(NameError){
+        WrapperRoleContext::Admin
+      }
+      assert_match /private constant/, error.message
+    end
+  end
+  if RedCard.check '2.0'
+    class InterfaceContext
+      extend Surrounded::Context
+
+      initialize(:admin, :other)
+
+      role :admin, :interface do
+        def hello
+          'hello from admin'
+        end
+      end
+
+      trigger :admin_hello do
+        admin.hello
+      end
+    end
+
+    class Hello
+      def hello
+        'hello'
+      end
+    end
+
+    describe 'interfaces' do
+      let(:context){
+        InterfaceContext.new(Hello.new, Hello.new)
+      }
+      it 'sets interface objects to use interface methods before singleton methods' do
+        assert_equal 'hello from admin', context.admin_hello
+      end
+
+      it 'marks the inteface constant private' do
+        error = assert_raises(NameError){
+          InterfaceContext::AdminInterface
+        }
+        assert_match /private constant/, error.message
+      end
+
+      it 'creates a private accessor method' do
+        assert_respond_to(context, :admin)
+      end
+    end
+  end
+
+  describe 'unknown' do
+    it 'raises an error' do
+      assert_raises(Surrounded::Context::InvalidRoleType){
+        class UnknownRole
+          extend Surrounded::Context
+
+          role :admin, :unknown do
+          end
+        end
+      }
+    end
+  end
+
+  describe 'custom default' do
+    it 'allows the use of custom default role types' do
+      class CustomDefaultWrap
+        extend Surrounded::Context
+
+        self.default_role_type = :wrap
+        apply_roles_on(:initialize)
+
+        initialize(:admin)
+
+        role :admin do
+        end
+      end
+      context = CustomDefaultWrap.new(Object.new)
+      assert_kind_of(SimpleDelegator, context.send(:admin))
+    end
+
+    it 'allows the setting of custom default role time for all Surrounded::Contexts' do
+      begin
+        old_default = Surrounded::Context.default_role_type
+        Surrounded::Context.default_role_type = :wrap
+        class CustomGlobalDefault
+          extend Surrounded::Context
+          apply_roles_on(:initialize)
+
+          initialize(:admin)
+
+          role :admin do
+          end
+        end
+
+        context = CustomGlobalDefault.new(Object.new)
+        assert_kind_of(SimpleDelegator, context.send(:admin))
+      ensure
+        Surrounded::Context.default_role_type = old_default
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: surrounded
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - '''Jim Gay'''
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-21 00:00:00.000000000 Z
+date: 2013-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: triad
@@ -81,8 +81,8 @@ files:
 - README.md
 - Rakefile
 - examples/rails.rb
-- examples/wrappers.rb
 - lib/surrounded.rb
+- lib/surrounded/README.md
 - lib/surrounded/context.rb
 - lib/surrounded/context/negotiator.rb
 - lib/surrounded/context/role_map.rb
@@ -92,6 +92,7 @@ files:
 - test/example_proxy_test.rb
 - test/example_threaded_test.rb
 - test/example_wrapper_test.rb
+- test/role_context_method_test.rb
 - test/surrounded_context_test.rb
 - test/surrounded_test.rb
 - test/test_helper.rb
@@ -123,6 +124,7 @@ test_files:
 - test/example_proxy_test.rb
 - test/example_threaded_test.rb
 - test/example_wrapper_test.rb
+- test/role_context_method_test.rb
 - test/surrounded_context_test.rb
 - test/surrounded_test.rb
 - test/test_helper.rb

data/examples/wrappers.rb

@@ -1,39 +0,0 @@
-# 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