surrounded 0.8.1 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f382683688ed856434a815e352dcc47f4acba5bc
-  data.tar.gz: c4701d73fe34507e5f4d57c06166c76a9f17d151
+  metadata.gz: 8a0524827a23eeb3aa9829988d8d5bc7773e81ca
+  data.tar.gz: ad49086b9e50454fbfb31c143d5428d52d46c0f9
 SHA512:
-  metadata.gz: eff04f84a73c9f73b933e5e30491524d6641bc42e7e16a84a33245a4cc4ab5b2f916ae0e545ca3669134e0e97041701811380988c9fca34ec27a8e07a9a6c804
-  data.tar.gz: 29dcf1aa2d0705efd2111b83f940ea6d67818966d0fc52c51392ab096783ee300ad0476e9ad19d3e1fe0f415d3a4fc2024b0d5e9e02287e50ccba89fd8ffd65d
+  metadata.gz: d84eaf1f7907b2b6c6a80e585721104916142f47fb79b4d5ccee6abdd6516868b7c08463234a38ea0d5f713914c11facef87abff0434ff3b9dc140e03da22100
+  data.tar.gz: eeb0bd64cf19f0d7e8ecd17df70d77f2ecc4e193ec95f952f95fda2f504e1fd8182beb92c953e6a4ab0e64475795b38f6c253bab820a705bb61901131d38db10

data/Gemfile

@@ -5,6 +5,7 @@ group :test do
   gem "simplecov"
   gem 'coveralls', :require => false
   gem 'casting'
+  gem 'rubinius-coverage', :platform => :rbx
 end
 
 platforms :rbx do

data/README.md

@@ -14,7 +14,7 @@ The purpose of this library is to clear away the details of getting things setup
 There are two main parts to this library. 
 
 1. `Surrounded` gives objects an implicit awareness of other objects in their environments.
-2. `Surrounded::Context` helps you create objects which encapsulate other objects. These *are* the environments.
+2. `Surrounded::Context` helps you create objects which encapsulate other objects **and** their behavior. These *are* the environments.
 
 First, take a look at creating contexts. This is where you'll spend most of your time.
 
@@ -307,7 +307,24 @@ 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_shove_it?` method defined.
 
-If you call the disallowed trigger directly, you'll raise a `Surrounded::Context::AccessError` exception and the code in your trigger will not be run.
+If you call the disallowed trigger directly, you'll raise a `MyEnvironment::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.
+
+Here's how you enforce it:
+
+```ruby
+class MyEnvironment
+  extend Surrounded::Context
+  east_oriented_triggers
+end
+```
+
+That's it.
+
+With that change, any trigger you define will execute the block you provide and return `self`, being the instance of the context.
 
 ## Where roles exist
 
@@ -472,15 +489,9 @@ class ActiviatingAccount
     # pass an array of arrays with role name symbol and the object for that role
     map_roles([[:activator, activator],[:account, account]])
   end
-  
-  # if you want to stick with the `initialize` shortcut you can define these methods
-  # for special initialization behavior.
-  def preinitialize
-    # to happen before any role mapping
-  end
-  def postinitialize
-    # to happen after any role mapping
-  end
+  # these also must be done if you create your own initialize method.
+  # this is a shortcut for using attr_reader and private
+  private_attr_reader :activator, :account
 
   role :activator do # module by default
     def some_behavior; end
@@ -549,6 +560,10 @@ class ActiviatingAccount
     instance.some_trigger_method
   end
   
+  # Set triggers to always return the context object
+  # so you can enforce East-oriented style or Tell, Don't Ask
+  east_oriented_triggers
+  
 end
 ```
 

data/lib/surrounded/access_control.rb

@@ -2,6 +2,9 @@ module Surrounded
   module AccessControl
     def self.extended(base)
       base.send(:include, AccessMethods)
+      unless defined?(base::AccessError)
+        base.const_set(:AccessError, Class.new(::Surrounded::Context::AccessError))
+      end
     end
     
     private
@@ -20,10 +23,10 @@ module Surrounded
             
             method_restrictor = "disallow_#{name}?"
             if self.respond_to?(method_restrictor, true) && self.send(method_restrictor)
-              raise ::Surrounded::Context::AccessError.new("access to #{self.name}##{name} is not allowed")
+              raise ::#{self.to_s}::AccessError.new("access to #{self.name}##{name} is not allowed")
             end
             
-            self.send("__trigger_#{name}")
+            #{trigger_return_content(name)}
 
           ensure
             remove_roles if __apply_role_policy == :trigger

data/lib/surrounded/context.rb

@@ -2,6 +2,7 @@ require 'set'
 require 'surrounded/context/role_map'
 require 'surrounded/access_control'
 require 'surrounded/shortcuts'
+require 'surrounded/east_oriented'
 
 # Some features are only available in versions of Ruby
 # where this method is true
@@ -62,7 +63,10 @@ module Surrounded
     def protect_triggers;  self.extend(::Surrounded::AccessControl); end
     
     # Automatically create class methods for each trigger method.
-    def shortcut_triggers; self.extend(::Surrounded::Shortcuts);     end
+    def shortcut_triggers; self.extend(::Surrounded::Shortcuts); end
+    
+    # Automatically return the context object from trigger methods.
+    def east_oriented_triggers; self.extend(::Surrounded::EastOriented); end
 
     def default_role_type
       @default_role_type ||= Surrounded::Context.default_role_type
@@ -192,7 +196,7 @@ module Surrounded
           begin
             apply_roles if __apply_role_policy == :trigger
 
-            self.send("__trigger_#{name}")
+            #{trigger_return_content(name)}
 
           ensure
             remove_roles if __apply_role_policy == :trigger
@@ -201,6 +205,10 @@ module Surrounded
       }, __FILE__, __LINE__
     end
     
+    def trigger_return_content(name)
+      %{self.send("__trigger_#{name}")}
+    end
+    
     # === Utility shortcuts
     
     # Set a named constant and make it private

data/lib/surrounded/east_oriented.rb

@@ -0,0 +1,13 @@
+module Surrounded
+  module EastOriented
+    # Always return the context object to ensure that a context may
+    # not be asked for information.
+    def trigger_return_content(name)
+      %{
+        self.send("__trigger_#{name}")
+        
+        self
+      }
+    end
+  end
+end

data/lib/surrounded/version.rb

@@ -1,3 +1,3 @@
 module Surrounded
-  VERSION = "0.8.1"
+  VERSION = "0.8.2"
 end

data/test/context_access_test.rb

@@ -45,13 +45,22 @@ describe Surrounded::Context, 'access control' do
     refute context.triggers.include?(:if_ready)
   end
   
-  it 'raises errors when trigger method not allowed' do
-    error = assert_raises(::Surrounded::Context::AccessError){
+  it 'raises error specific to the context class when trigger method not allowed' do
+    error = assert_raises(::FilteredContext::AccessError){
       context.if_ready
     }
     assert_match(/access to FilteredContext#if_ready is not allowed/i, error.message)
   end
   
+  it 'supports rescuing from Surrounded defined error when trigger method not allowed' do
+    begin
+      context.if_ready
+    rescue ::Surrounded::Context::AccessError => error
+      assert "rescued!"
+    end
+    assert_match(/access to FilteredContext#if_ready is not allowed/i, error.message)
+  end
+  
   it 'applies roles in disallow blocks' do
     assert_equal 'special user method', context.disallow_check_disallow_behavior?
   end

data/test/east_oriented_triggers_test.rb

@@ -0,0 +1,36 @@
+require 'test_helper'
+
+class EastTestContext
+  extend Surrounded::Context
+  east_oriented_triggers
+  
+  initialize :user, :other_user
+  
+  trigger :ask? do
+    "asking a question..."
+  end
+end
+
+describe Surrounded::Context, '.east_oriented_triggers' do
+  let(:user){ User.new("Jim") }
+  let(:other_user){ User.new("Guille") }
+  let(:context){ EastTestContext.new(user, other_user) }
+
+  it 'returns the context object from trigger methods' do
+    assert_equal context, context.ask?
+  end
+end
+
+describe Surrounded::Context, '.east_oriented_triggers with protect_triggers' do
+  let(:user){ User.new("Jim") }
+  let(:other_user){ User.new("Guille") }
+  let(:context){ 
+    ctxt = EastTestContext.new(user, other_user)
+    ctxt.singleton_class.send(:protect_triggers)
+    ctxt
+  }
+
+  it 'returns the context object from trigger methods' do
+    assert_equal context, context.ask?
+  end
+end

metadata

@@ -1,57 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: surrounded
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.8.2
 platform: ruby
 authors:
-- "'Jim Gay'"
-autorequire: 
+- '''Jim Gay'''
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2014-01-29 00:00:00.000000000 Z
+date: 2014-02-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: triad
-  requirement: !ruby/object:Gem::Requirement
+  version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: 0.1.2
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: 0.1.2
+  prerelease: false
+  type: :runtime
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: !ruby/object:Gem::Requirement
+  version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.3'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.3'
+  prerelease: false
+  type: :development
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: !ruby/object:Gem::Requirement
+  version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
+  prerelease: false
+  type: :development
 description: Gives an object implicit access to other objects in it's environment.
 email:
 - jim@saturnflyer.com
@@ -59,9 +59,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- ".simplecov"
-- ".travis.yml"
+- .gitignore
+- .simplecov
+- .travis.yml
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -73,11 +73,13 @@ files:
 - lib/surrounded/context/negotiator.rb
 - lib/surrounded/context/role_map.rb
 - lib/surrounded/context_errors.rb
+- lib/surrounded/east_oriented.rb
 - lib/surrounded/shortcuts.rb
 - lib/surrounded/version.rb
 - surrounded.gemspec
 - test/context_access_test.rb
 - test/context_shortcuts_test.rb
+- test/east_oriented_triggers_test.rb
 - test/example_proxy_test.rb
 - test/example_threaded_test.rb
 - test/example_wrapper_test.rb
@@ -89,29 +91,30 @@ homepage: http://github.com/saturnflyer/surrounded
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.2.0
-signing_key: 
+rubyforge_project:
+rubygems_version: 2.1.9
+signing_key:
 specification_version: 4
 summary: Create encapsulated environments for your objects.
 test_files:
 - test/context_access_test.rb
 - test/context_shortcuts_test.rb
+- test/east_oriented_triggers_test.rb
 - test/example_proxy_test.rb
 - test/example_threaded_test.rb
 - test/example_wrapper_test.rb