surrounded 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cb66bc4320f6971198085580154f6ca683dcc952
-  data.tar.gz: cfe6c6e94af4ff0fa78922cd1df3b74666abb58a
+  metadata.gz: c8490f4520253094598c520cdc7b3a73186d48d5
+  data.tar.gz: 31d8f5baebf2e1f42b761207972de0523ac41885
 SHA512:
-  metadata.gz: 5e9e696a657da51806a9929adfec0c0ef6f838dae69ebe2acf9c10a547998428a935d021118b7550eff2033316b1b177906749e93e50f3150c62abc60d44d0e1
-  data.tar.gz: 36395abadb826b0542061e3d51e0831f533a8c4321d4c4b113469dbfae4520f1ae15916919f4f1bf0006ff8ab84956fce227be65fd1e6b822156324aec840af9
+  metadata.gz: 161b86c91796ead35d60f817308a252585544b3690055039c026bf2ad97bf0f3ed5573709fd341673681399dcb8687113102cf698e2c5f255856d22e47471e2a
+  data.tar.gz: 975026239c9e4e2796d8f66f73c062c7907159beeaf30a8f0dfea8ee69960d970155bfdcdc1ec69b81a6c13c5ed9ad8d862cfdcfb159108758da8293db4cb270

data/.travis.yml

@@ -2,6 +2,7 @@ language: ruby
 rvm:
   - 2.0.0
   - 2.1.1
+  - 2.2.0
   - ruby-head
   - jruby-head
   - rbx

data/README.md

@@ -136,6 +136,36 @@ end
 Trigger methods are different from regular instance methods in that they apply behaviors from the roles to the role players.
 A regular instance method just does what you define. But a trigger will make your role players come alive with their behaviors.
 
+You may find that the code for your triggers is extremely simple and is merely creating a method to tell a role player what to do. If you find you have many methods like this:
+
+```ruby
+  def plan_weekend_work
+    employee.work_weekend
+  end
+  trigger :plan_weekend_work
+```
+
+You can shorten it to:
+
+```ruby
+  trigger :plan_weekend_work do
+    employee.work_weekend
+  end
+```
+
+But it can be even simpler and follows the same pattern provided by Ruby's standard library Forwardable:
+
+```ruby
+  # The first argument is the role to receive the messaged defined in the second argument.
+  # The third argument is optional and if provided will be the name of the trigger method on your context instance.
+  forward_trigger :employee, :work_weekend, :plan_weekend_work
+
+  # Alternatively, you can use an API similar to that of the `delegate` method from Forwardable
+  forwarding [:work_weekend] => :employee
+```
+
+The difference between `forward_trigger` and `forwarding` is that the first accepts an alternative method name for the context instance method. There's more on this below in the "Overview in code" section, or see `lib/surrounded/context/forwarding.rb`.
+
 There's one last thing to make this work.
 
 ## Getting your role players ready
@@ -451,11 +481,11 @@ Alternatively, if you just want to define your own methods without the DSL using
 
 In fact, that's exactly what happens with the `disallow` keyword. After using it here, we'd have a `disallow_plan_weekend_work?` method defined.
 
-If you call the disallowed trigger directly, you'll raise a `Employment::AccessError` exception and the code in your trigger will not be run. You may rescue from that or you may rescue from `Surrounded::Context::AccessError` although you should prefer to use the error name from your own class.
+If you call the disallowed trigger directly, you'll raise an `Employment::AccessError` exception and the code in your trigger will not be run. You may rescue from that or you may rescue from `Surrounded::Context::AccessError` although you should prefer to use the error name from your own class.
 
 ## Restricting return values
 
-_Tell, Don't Ask_ style programming can better be enforced by following East-oriented Code principles. This means that the returns values from methods on your objects should not provide information about their internal state. Instead of returning values, you can enforce that triggers return the context object. This forces you to place context responsiblities inside the context and prevents leaking the details and responsiblities outside of the system.
+_Tell, Don't Ask_ style programming can better be enforced by following East-oriented Code principles. This means that the return values from methods on your objects should not provide information about their internal state. Instead of returning values, you can enforce that triggers return the context object. This forces you to place context responsiblities inside the context and prevents leaking the details and responsiblities outside of the system.
 
 Here's how you enforce it:
 
@@ -598,6 +628,10 @@ class ActiviatingAccount
     # this must be done to handle the mapping of roles to objects
     # pass an array of arrays with role name symbol and the object for that role
     map_roles([[:activator, activator],[:account, account]])
+
+    # or load extra objects, perform other functions, etc. if you need and then use super
+    account.perform_some_funtion
+    super
   end
   # these also must be done if you create your own initialize method.
   # this is a shortcut for using attr_reader and private
@@ -633,9 +667,13 @@ class ActiviatingAccount
   def regular_method
     apply_behaviors # handles the adding of all the roles and behaviors
     activator.some_behavior # behavior not available unless you apply roles on initialize
+  ensure
+     # Use ensure to enforce the removal of behaviors in case of exceptions.
+     # This also does not affect the return value of this method.
     remove_behaviors # handles the removal of all roles and behaviors
   end
 
+  # This trigger or the forward* methods are preferred for creating triggers.
   trigger :some_trigger_method do
     activator.some_behavior # behavior always available
   end
@@ -659,6 +697,8 @@ class ActiviatingAccount
   def disallow_some_trigger_method?
     # whatever conditional code for the instance of the context
   end
+  # Prefer using `disallow` because it will wrap role players in their roles for you;
+  # the `disallow_some_trigger_method?` defined above, does not.
   
   # Create shortcuts for triggers as class methods
   # so you can do ActiviatingAccount.some_trigger_method(activator, account)
@@ -674,6 +714,11 @@ class ActiviatingAccount
   # so you can enforce East-oriented style or Tell, Don't Ask
   east_oriented_triggers
   
+  # Forward context instance methods as triggers to role players
+  forward_trigger :role_name, :method_name
+  forward_trigger :role_name, :method_name, :alternative_trigger_name_for_method_name
+  forward_triggers :role_name, :list, :of, :methods, :to, :forward
+  forwarding [:list, :of, :methods, :to, :forward] => :role_name
 end
 ```
 
@@ -683,6 +728,146 @@ The dependencies are minimal. The plan is to keep it that way but allow you to c
 
 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.
 
+## Support for other ways to apply behavior
+
+Surrounded is designed to be flexible for you. If you have your own code to manage applying behaviors, you can setup your context class to use it.
+
+### Additional libraries
+
+Here's an example using [Behavioral](https://github.com/saturnflyer/behavioral)
+
+```ruby
+class MyCustomContext
+  extend Surrounded::Context
+
+  initialize :employee, :boss
+
+  def module_extension_methods
+    [:with_behaviors].concat(super)
+  end
+
+  def module_removal_methods
+    [:without_behaviors].concat(super)
+  end
+end
+```
+
+If you're using your own non-SimpleDelegator wrapper you can conform to that; whatever it may be.
+
+```ruby
+class MyCustomContext
+  extend Surrounded::Context
+
+  initialize :employee, :boss
+
+  class Employee < SuperWrapper
+    include Surrounded
+
+    # defined behaviors here...
+
+    def wrapped_object
+      # return the object that is wrapped
+    end
+
+  end
+
+  def unwrap_methods
+    [:wrapped_object]
+  end
+end
+```
+
+### Applying individual roles
+
+If you'd like to use a special approach for just a single role, you may do that too.
+
+When applying behaviors from a role to your role players, your Surrounded context will first look for a method named  `"apply_behavior_#{role}"`. Define your own method and set it to accept 2 arguments: the role constant and the role player.
+
+```ruby
+class MyCustomContext
+  extend Surrounded::Context
+
+  initialize :employee, :boss
+
+  def apply_behavior_employee(behavior_constant, role_player)
+    behavior_constant.build(role_player).apply # or whatever your need to do with your constant and object.
+  end
+end
+```
+
+You can also plan for special ways to remove behavior as well.
+
+```ruby
+class MyCustomContext
+  extend Surrounded::Context
+
+  initialize :employee, :boss
+
+  def remove_behavior_employee(behavior_constant, role_player)
+    role_player.cleanup # or whatever your need to do with your constant and object.
+  end
+end
+```
+
+You can remember the method name by the convention that `remove` or `apply` describes it's function, `behavior` refers to the first argument (thet contsant holding the behaviors), and then the name of the role which refers to the role playing object: `remove_behavior_role`.
+
+## How to read this code
+
+If you use this library, it's important to understand it.
+
+As much as possible, when you use the Surrounded DSL for creating triggers, roles, initialize methods, and others you'll likely fine the actual method definitions created in a module and then find that module included in your class.
+
+This is a design choice which allows you to override any standard behavior more easily.
+
+### Where methods exist and why
+
+When you define an initialize method for a Context class, Surrounded _could_ define the method on your class like this:
+
+```ruby
+def initialize(*roles)
+  self.class_eval do # <=== this evaluates on _your_ class and defines it there.
+    # code...
+  end
+end
+```
+
+If we used the above approach, you'd need to redefine initialize in its entirety:
+
+```ruby
+initialize(:role1, role2)
+
+def initialize(role1, role2) # <=== this will completely redefine initialize on _this class_
+  super # <=== this will NOT be the initialize method as provided to the Surrounded initialize above.
+end
+```
+
+Surrounded uses a more flexible approach for you:
+
+```ruby
+def initialize(*roles)
+  mod = Module.new
+  mod.class_eval do # <=== this evaluates on the module and defines it there.
+    # code...
+  end
+  include mod # <=== this adds it to the class ancestors
+end
+```
+
+With this approach you can use the way Surrounded is setup, but make changes if you need.
+
+```ruby
+initialize(:role1, :role2) # <=== defined in a module in the class ancestors
+
+def initialize(role1, role2)
+  super # <=== run the method as defined above in the Surrounded DSL
+  # ... then do additional work
+end
+```
+
+### Read methods, expect modules
+
+When you go to read the code, expect to find behavior defined in modules.
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/examples/rails.rb

@@ -34,6 +34,16 @@ class SomeUseCase
       listener.redirect_to('/')
     end
   end
+
+  class OtherUser < ::User
+    def special_feature
+      #....
+    end
+  end
+
+  def apply_behavior_other_user(role, behavior, role_player)
+    role_player.becomes(behavior)
+  end
 end
 
 class SomethingController < ApplicationController

data/lib/surrounded/context.rb

@@ -2,6 +2,7 @@ require 'set'
 require 'surrounded/context/role_map'
 require 'surrounded/context/role_builders'
 require 'surrounded/context/initializing'
+require 'surrounded/context/forwarding'
 require 'surrounded/context/trigger_controls'
 require 'surrounded/access_control'
 require 'surrounded/shortcuts'
@@ -17,7 +18,7 @@ module Surrounded
   module Context
     def self.extended(base)
       base.class_eval {
-        extend RoleBuilders, Initializing
+        extend RoleBuilders, Initializing, Forwarding
 
         @triggers = Set.new
         include InstanceMethods

data/lib/surrounded/context/forwarding.rb

@@ -0,0 +1,27 @@
+module Surrounded
+  module Context
+    module Forwarding
+      def forward_trigger(receiver, message, alternate=message)
+        raise(ArgumentError, %{you may not forward '%{m}`} % {m: message}) if ['__id__','__send__'].include?(message.to_s)
+        trigger alternate do
+          self.send(receiver).public_send(message)
+        end
+      end
+      
+      def forward_triggers(receiver, *messages)
+        messages.each do |message|
+          forward_trigger(receiver, message)
+        end
+      end
+      
+      def forwarding(hash)
+        hash.each { |messages, receiver|
+          forward_triggers(receiver, *messages)
+        }
+      end
+      
+      alias forward forward_trigger
+      alias forwards forward_triggers
+    end
+  end
+end

data/lib/surrounded/context/initializing.rb

@@ -1,12 +1,6 @@
 module Surrounded
   module Context
     module Initializing
-      def new(*args, &block)
-        instance = allocate
-        instance.send(:initialize, *args, &block)
-        instance
-      end
-
       # Shorthand for creating an instance level initialize method which
       # handles the mapping of the given arguments to their named role.
       def initialize(*setup_args)
@@ -16,9 +10,8 @@ module Surrounded
         line = __LINE__
         mod.class_eval "
           def initialize(#{setup_args.join(',')})
-            arguments = method(__method__).parameters.map{|arg| eval(arg[1].to_s) }
             @role_map = RoleMap.new
-            map_roles(#{setup_args}.zip(arguments))
+            map_roles(#{setup_args.to_s}.zip([#{setup_args.join(',')}]))
           end
         ", __FILE__, line
         const_set("ContextInitializer", mod)

data/lib/surrounded/context/negotiator.rb

@@ -24,5 +24,7 @@ module Surrounded
         end
       end
     end
+
+    Negotiator.send(:prepend, Surrounded)
   end
 end

data/lib/surrounded/context/role_builders.rb

@@ -3,15 +3,13 @@ module Surrounded
     module RoleBuilders
 
       # Define behaviors for your role players
-      def role(name, type=nil, &block)
-        role_type = type || default_role_type
-        if role_type == :module
-          mod_name = name.to_s.gsub(/(?:^|_)([a-z])/){ $1.upcase }
-          mod = Module.new(&block)
-          mod.send(:include, ::Surrounded)
+      def role(name, type=default_role_type, &block)
+        if type == :module
+          mod_name = RoleBuilders.mod_name(name)
+          mod = Module.new(&block).send(:include, ::Surrounded)
           private_const_set(mod_name, mod)
         else
-          meth = method(role_type)
+          meth = method(type)
           meth.call(name, &block)
         end
       rescue NameError => e
@@ -22,17 +20,25 @@ module Surrounded
       # Create a named behavior for a role using the standard library SimpleDelegator.
       def wrap(name, &block)
         require 'delegate'
-        wrapper_name = name.to_s.gsub(/(?:^|_)([a-z])/){ $1.upcase }
+        wrapper_name = RoleBuilders.mod_name(name)
         klass = private_const_set(wrapper_name, Class.new(SimpleDelegator, &block))
         klass.send(:include, Surrounded)
       end
       alias_method :wrapper, :wrap
 
+      # Create a named behavior for a role using the standard library DelegateClass.
+      # This ties the implementation of the role to a specific class or module API.
+      def delegate_class(name, class_name, &block)
+        require 'delegate'
+        wrapper_name = RoleBuilders.mod_name(name)
+        klass = private_const_set(wrapper_name, DelegateClass(Object.const_get(class_name.to_s)))
+        klass.class_eval(&block)
+        klass.send(:include, Surrounded)
+      end
 
       # Create an object which will bind methods to the role player
       def interface(name, &block)
-        class_basename = name.to_s.gsub(/(?:^|_)([a-z])/){ $1.upcase }
-        interface_name = class_basename + 'Interface'
+        interface_name = RoleBuilders.mod_name(name) + 'Interface'
 
         behavior = private_const_set(interface_name, Module.new(&block))
 
@@ -43,6 +49,10 @@ module Surrounded
         end
       end
       
+      def self.mod_name(name)
+        name.to_s.gsub(/(?:^|_)([a-z])/){ $1.upcase }
+      end
+
     end
   end
 end

data/lib/surrounded/context/trigger_controls.rb

@@ -37,7 +37,7 @@ module Surrounded
         else
           name = names.first
           define_trigger_action(*names, &block)
-          define_trigger(name, &block)
+          define_trigger(name)
           store_trigger(name)
         end
       end
@@ -53,8 +53,7 @@ module Surrounded
       end
 
       def define_trigger(name)
-        line = __LINE__
-        self.class_eval %{
+        line = __LINE__; self.class_eval %{
           def #{name}(*args, &block)
             begin
               apply_behaviors
@@ -78,9 +77,7 @@ module Surrounded
       
       
       def define_trigger_action(*name_and_args, &block)
-        trigger_action_module.module_eval do
-          define_method(*name_and_args, &block)
-        end
+        trigger_action_module.send(:define_method, *name_and_args, &block)
       end
       
       def trigger_action_module