surrounded 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5b50df20142b16850a46c0824115d7286d5c5db0
-  data.tar.gz: bbf2f02bc6d2bf089f8a1a6c33627cac0efb8e43
+  metadata.gz: 31db490fd3a2fd39b290aa7c5f9368e1ce3fa963
+  data.tar.gz: eef7f29cd0632c9066686d00b873629ef80f7942
 SHA512:
-  metadata.gz: 4d1badd06972d938d14bc50ea50d8d074c882a4ebf2728724de48131e875f55f75dcdd019fbcdd64322eb6591d414ec9fccbe12cc106518fa3d309a93ab31294
-  data.tar.gz: b3aa0cfaaec0178fbe799fff2b64d16f4565be58eb6d95e29eb46542a7ef35a7bc50ddc80bae8b51ff5b614277ff3079846d4a872697e8d2c11364f3984781ea
+  metadata.gz: 6719cd08a3549f2b23a5193e86e656fb88480d3321193fad86709e09fdfe9ccf07b68659a5c51efe2b59e6c27904227246b23d17ece00882b411262123d9f881
+  data.tar.gz: 71ae69d703a4c4502ddc000f06294c6c87f047253c2c4a86b7acee3a6d3d0106abf4b9e4578bfe8320e109afbdd1f77caf99a16ecb237f1b1b604204f1087da3

data/.travis.yml

@@ -2,14 +2,15 @@ language: ruby
 rvm:
   - 1.9.3
   - 2.0.0
+  - 2.1.0
   - jruby-19mode # JRuby in 1.9 mode
   - ruby-head
   - jruby-head
-  - rbx-19mode
+  - rbx
 env:
 - COVERALLS=true
 matrix:
   allow_failures:
     - rvm: ruby-head
     - rvm: jruby-head
-    - rvm: rbx-19mode
+    - rvm: rbx

data/Gemfile

@@ -7,4 +7,8 @@ group :test do
   gem 'casting'
 end
 
+platforms :rbx do
+  gem 'rubysl', '~> 2.0'
+end
+
 gemspec

data/README.md

@@ -275,6 +275,40 @@ This will allow you to write methods like you normally would. They are aliased i
 
 This works like Ruby's `public`,`protected`, and `private` keywords in that you can send symbols of method names to it. But `trigger` does not alter the parsing of the document like those core keywords do. In other words, you can't merely type `trigger` on one line, and have methods added afterward be treated as trigger methods.
 
+## Access Control for Triggers
+
+If you decide to build a user interface from the available triggers, you'll find you need to know what triggers are available.
+
+Fortunately, you can make it easy.
+
+By running `protect_triggers` you'll be able to define when triggers may or may not be run. You can still run them, but they'll raise an error. Here's an example.
+
+```ruby
+class MyEnvironment
+  extend Surrounded::Context
+  protect_triggers
+  
+  def shove_it
+    employee.quit
+  end
+  trigger :shove_it
+  
+  disallow :shove_it do
+    employee.bank_balance < 100
+  end
+end
+```
+
+Then, when the employee role's `bank_balance` is less than `100`, the available triggers won't include `:shove_it`.
+
+You can compare the instance of the context by listing `all_triggers` and `triggers` to see what could be possible and what's currently possible.
+
+Alternatively, if you just want to define your own methods without the DSL using `disallow`, you can just follow the pattern of `disallow_#{method_name}?` when creating your own protection.
+
+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.
+
 ## Where roles exist
 
 By using `Surrounded::Context` you are declaring a relationship between the objects inside playing your defined roles.
@@ -438,12 +472,21 @@ 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
 
   role :activator do # module by default
     def some_behavior; end
   end
 
-  #  role :activator, :module do
+  #  role_methods :activator, :module do # alternatively use role_methods if you choose
   #    def some_behavior; end
   #  end
   #
@@ -457,16 +500,19 @@ class ActiviatingAccount
   #
   # use your own classes if you don't want SimpleDelegator
   # class SomeSpecialRole
-  #   include Surrounded # you must remember this
+  #   include Surrounded # <-- you must remember this in your own classes
   #   # Surrounded assumes SomeSpecialRole.new(some_special_role)
   #   def initialize(...);
   #     # ... your code here
   #   end
   # end
 
-  # works as a trigger (assigning the current context) only if set_methods_as_triggers is set
+  # if you use a regular method and want to use context-specific behavior, 
+  # you must handle storing the context yourself:
   def regular_method
+    apply_roles # handles the adding of all the roles and behaviors
     activator.some_behavior # behavior not available unless you apply roles on initialize
+    remove_roles # handles the removal of all roles and behaviors
   end
 
   trigger :some_trigger_method do
@@ -480,7 +526,18 @@ class ActiviatingAccount
   def regular_non_trigger
     activator.some_behavior # behavior always available with the following line
   end
-  trigger :regular_non_trigger # turns the method into a trigger  
+  trigger :regular_non_trigger # turns the method into a trigger
+  
+  # create restrictions on what triggers may be used
+  protect_triggers # <-- this is required if you want to protect your triggers this way.
+  disallow :some_trigger_method do
+    # whatever conditional code for the instance of the context
+  end
+  
+  # or define your own method without the `disallow` keyword
+  def disallow_some_trigger_method?
+    # whatever conditional code for the instance of the context
+  end
 end
 ```
 

data/lib/surrounded/access_control.rb

@@ -0,0 +1,48 @@
+module Surrounded
+  module AccessControl
+    def self.extended(base)
+      base.send(:include, AccessMethods)
+    end
+    
+    private
+    
+    def disallow(*names, &block)
+      names.map do |name|
+        define_method("disallow_#{name}?", &block)
+      end
+    end
+    
+    def redo_method(name)
+      class_eval %{
+        def #{name}
+          begin
+            apply_roles if __apply_role_policy == :trigger
+            
+            method_restrictor = "disallow_#{name}?"
+            if self.respond_to?(method_restrictor, true) && self.send(method_restrictor)
+              raise ::Surrounded::Context::AccessError.new("access to `#{name}' is not allowed")
+            end
+            
+            self.send("__trigger_#{name}")
+
+          ensure
+            remove_roles if __apply_role_policy == :trigger
+          end
+        end
+      }
+    end
+    
+    module AccessMethods
+      def all_triggers
+        self.class.triggers
+      end
+    
+      def triggers
+        all_triggers.select {|name|
+          method_restrictor = "disallow_#{name}?"
+          !self.respond_to?(method_restrictor, true) || !self.send(method_restrictor)
+        }.to_set
+      end
+    end
+  end
+end

data/lib/surrounded/context.rb

@@ -1,5 +1,6 @@
 require 'set'
 require 'surrounded/context/role_map'
+require 'surrounded/access_control'
 
 # Some features are only available in versions of Ruby
 # where this method is true
@@ -30,6 +31,10 @@ module Surrounded
     class << self
       attr_writer :default_role_type
     end
+    
+    def protect_triggers
+      self.extend(::Surrounded::AccessControl)
+    end
 
     def new(*args, &block)
       instance = allocate

data/lib/surrounded/context_errors.rb

@@ -3,5 +3,6 @@ module Surrounded
   module Context
     class InvalidRole < ::Triad::KeyNotPresent; end
     module InvalidRoleType; end
+    class AccessError < StandardError; end
   end
 end

data/lib/surrounded/version.rb

@@ -1,3 +1,3 @@
 module Surrounded
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/test/context_access_test.rb

@@ -0,0 +1,40 @@
+require 'test_helper'
+require 'minitest/mock'
+
+class FilteredContext
+  extend Surrounded::Context
+  protect_triggers
+  
+  initialize :user, :other_user
+  
+  trigger :if_ready do
+    'ready'
+  end
+  
+  disallow :if_ready do
+    user.name != 'Amy'
+  end
+end
+
+describe Surrounded::Context, 'access control' do
+  let(:user){ User.new("Jim") }
+  let(:other_user){ User.new("Guille") }
+  let(:context){ FilteredContext.new(user, other_user) }
+  
+  it 'includes triggers when allowed' do
+    context.stub(:disallow_if_ready?, false) do
+      assert context.triggers.include?(:if_ready)
+    end
+  end
+
+  it 'excludes triggers when not allowed' do
+    refute context.triggers.include?(:if_ready)
+  end
+  
+  it 'raises errors when trigger method not allowed' do
+    error = assert_raises(Surrounded::Context::AccessError){
+      context.if_ready
+    }
+    assert_match(/access to `if_ready' is not allowed/i, error.message)
+  end
+end

metadata

@@ -1,55 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: surrounded
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
-- "'Jim Gay'"
+- '''Jim Gay'''
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-16 00:00:00.000000000 Z
+date: 2014-01-20 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
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.3'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 description: Gives an object implicit access to other objects in it's environment.
@@ -59,21 +59,23 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- ".simplecov"
-- ".travis.yml"
+- .gitignore
+- .simplecov
+- .travis.yml
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - examples/rails.rb
 - lib/surrounded.rb
+- lib/surrounded/access_control.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/context_access_test.rb
 - test/example_proxy_test.rb
 - test/example_threaded_test.rb
 - test/example_wrapper_test.rb
@@ -91,21 +93,22 @@ 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
+rubygems_version: 2.0.14
 signing_key: 
 specification_version: 4
 summary: Create encapsulated environments for your objects.
 test_files:
+- test/context_access_test.rb
 - test/example_proxy_test.rb
 - test/example_threaded_test.rb
 - test/example_wrapper_test.rb