surrounded 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: eec57f6f3717bca03404f2acde19afb3cb2a08d4
+  data.tar.gz: 7c6fef1028b60551bcc1cafdb5e7e9099d1ab7ef
+SHA512:
+  metadata.gz: 2fe9113c6aaed6c7a09c687045cb54ba792bc59521b8917b09fdbc43a7d17c065cb54eac1a437a1fabcd9d4f094e78e9d67bf75333553ffef6cc63b7d000524e
+  data.tar.gz: 6472c2aef734c56f55d9dc2a0f9992b7e4f693f2ff677685586a3fee3a872cb9bf2602f6cb05e9b68b82a040fc0bf2be32b6aec0c3d4f7ef849df02874a95f65

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+.rvmrc
+.DS_Store
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.simplecov

@@ -0,0 +1,3 @@
+SimpleCov.start do
+  add_filter 'test'
+end

data/.travis.yml

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

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+group :test do
+  gem 'minitest'
+  gem "simplecov"
+  gem 'coveralls', :require => false
+  gem 'casting'
+end
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 'Jim Gay'
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,205 @@
+# Surrounded
+
+[![Build Status](https://travis-ci.org/saturnflyer/surrounded.png?branch=master)](https://travis-ci.org/saturnflyer/surrounded)
+[![Code Climate](https://codeclimate.com/github/saturnflyer/surrounded.png)](https://codeclimate.com/github/saturnflyer/surrounded)
+[![Coverage Status](https://coveralls.io/repos/saturnflyer/surrounded/badge.png)](https://coveralls.io/r/saturnflyer/surrounded)
+
+## Create encapsulated environments for your objects.
+
+Keep the distraction of other features out of your way. Write use cases and focus on just the business logic
+
+## Usage
+
+Add `Surrounded` to your objects to give them awareness of other objects.
+
+```ruby
+class User
+  include Surrounded
+end
+```
+
+Now your user instances will be able to get objects in their environment.
+
+_What environment!? I don't get it._
+
+I didn't explain that yet.
+
+You can make an object which contains other objects. It acts as an environment
+and objects inside should have knowledge of the other objects in the environment.
+Take a breath, because there's a lot going on.
+
+First, you extend a class with the appropriate module to turn it into an object environment:
+
+```ruby
+class MyEnvironment
+  extend Surrounded::Context
+end
+```
+
+Typical initialization of this environment has a lot of code. For example:
+
+```ruby
+class MyEnvironment
+  extend Surrounded::Context
+
+  attr_reader :employee, :boss
+  private :employee, :boss
+  def initialize(employee, boss)
+    @employee = employee.extend(Exmployee)
+    @boss = boss
+  end
+
+  module Employee
+    # extra behavior here...
+  end
+end
+```
+
+_WTF was all that!?_
+
+Relax. I'll explain.
+
+When you create an instance of `MyEnvironment` it has certain objects inside.
+Here we see that it has an `employee` and a `boss`. Inside the methods of the environment it's simpler and easier to write `employee` instead of `@employee` so we make them `attr_reader`s. But we don't need these methods to be externally accessible so we set them to private.
+
+Next, we want to add environment-specific behavior to the `employee` so we extend the object with the module `Employee`.
+
+If you're going to be doing this a lot, it's painful. Here's what `Surrounded` does for you:
+
+```ruby
+class MyEnvironment
+  extend Surrounded::Context
+
+  setup(:employee, :boss)
+
+  module Employee
+    # extra behavior here...
+  end
+end
+```
+
+There! All that boilerplate code is cleaned up.
+
+Notice that there's no `Boss` module. If a module of that name does not exist, the object passed into initialize simply won't gain any new behavior.
+
+_OK. I think I get it, but what about the objects? How are they aware of their environment? Isn't that what this is supposed to do?_
+
+Yup. Ruby doesn't have a notion of a local environment, so we lean on `method_missing` to do the work for us.
+
+```ruby
+class User
+  include Surrounded
+end
+```
+
+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.
+
+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.
+
+Here's an example of what we want:
+
+```ruby
+class MyEnvironment
+  # other stuff from above is still here...
+
+  def shove_it
+    Thread.current[:context] = self
+    employee.quit
+    Thread.current[:context] = nil
+  end
+
+  module Employee
+    def quit
+      say("I'm sick of this place, #{boss.name}!")
+      stomp
+      throw_papers
+      say("I quit!")
+    end
+  end
+end
+```
+
+What's happening in there is that when the `shove_it` method is called, the current environment object is stored as the context.
+
+The behavior defined in the `Employee` module assumes that it may access other objects in it's local environment. The `boss` object, for example, is never explicitly passed in as an argument.
+
+_WTF!? That's insane!_
+
+I thought so too, at first. But continually passing references assumes there's no relationship between objects in that method. What `Surrounded` does for us is to make the relationship between objects and gives them the ability to access each other.
+
+This simple example may seem trivial, but the more contextual code you have the more cumbersome passing references becomes. By moving knowledge to the local environment, you're free to make changes to the procedures without the need to alter method signatures with new refrences or the removal of unused ones.
+
+By using `Surrounded::Context` you are declaring a relationship between the objects inside.
+
+Because all the behavior is defined internally and only relevant internally, those relationships don't exist outside of the environment.
+
+_OK. I think I understand. So I can change business logic just by changing the procedures and the objects. I don't need to adjust arguments for a new requirement. That's kind of cool!_
+
+Damn right.
+
+But you don't want to continually set those `Thread` variables, do you?
+
+_No. That's annoying._
+
+Yeah. Instead, it would be easier to have this library do the work for us.
+Here's what you can do:
+
+```ruby
+class MyEnvironment
+  # the other code from above...
+
+  trigger :shove_it do
+    employee.quit
+  end
+end
+```
+
+By using this `trigger` keyword, our block is the code we care about, but internally the method is written to set the `Thread` variables.
+
+_Hmm. I don't like having to do that._
+
+Me either. I'd rather just use `def` but getting automatic code for setting the context is really convenient.
+It also allows us to store the triggers so that you can, for example, provide details outside of the environment about what triggers exist.
+
+```ruby
+context = MyEnvironment.new(current_user, the_boss)
+context.triggers #=> [:shove_it]
+```
+
+You might find that useful for dynamically defining user interfaces.
+
+## Dependencies
+
+The dependencies are minimal. The plan is to keep it that way but allow you to configure things as you need.
+
+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.
+
+## To Do
+
+Casting provides a way to remove features outside of a block. For now, the code doesn't attempt to `uncast` an object. It will in the future though.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'surrounded'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install surrounded
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/*_test.rb']
+  t.ruby_opts = ["-w"]
+  t.verbose = true
+end
+task :default => :test

data/examples/rails.rb

@@ -0,0 +1,65 @@
+# Here's an example of how you might use this in rails.
+
+# First, be guarded against changes in third-party libraries
+module Awareness
+  include Surrounded
+  include Casting::Client
+  delegate_missing_methods
+end
+
+class User
+  include Awareness
+end
+
+class ApplicationController
+  include Awareness
+end
+
+class SomeUseCase
+  extend Surrounded::Context
+
+  setup(:user, :other_user, :listener)
+
+  trigger :do_something do
+    user.something
+  end
+
+  module User
+    def something
+      puts "Hello, #{other_user}"
+      listener.redirect_to('/')
+    end
+  end
+end
+
+class SomethingController < ApplicationController
+  use_case = :SomeUseCase
+  def create
+    use_case = :SomeOverrideUseCase
+    trigger :do_something, current_user, User.last
+  end
+
+  def trigger(meth, *args)
+    use_case.new(*(args << self)).send(meth)
+  end
+
+  def self.use_case=(name)
+    @_default_use_case_name = name
+  end
+
+  def self.use_case
+    @_default_use_case_name.to_s.constantize
+  end
+
+  def use_case=(name)
+    @_use_case_name = name
+  end
+
+  def use_case
+    if defined?(@_use_case_name)
+      @_use_case_name.to_s.constantize
+    else
+      self.class.use_case
+    end
+  end
+end

data/lib/surrounded.rb

@@ -0,0 +1,24 @@
+require "surrounded/version"
+
+module Surrounded
+  private
+
+  def method_missing(meth, *args, &block)
+    context.role?(meth){} || super
+  end
+
+  def respond_to_missing?(meth, include_private=false)
+    !!context.role?(meth){} || super
+  end
+
+  def context
+    Thread.current[:context] ||= []
+    Thread.current[:context].first || NullContext.new
+  end
+
+  class NullContext < BasicObject
+    def role?(*args)
+      nil
+    end
+  end
+end

data/lib/surrounded/context.rb

@@ -0,0 +1,86 @@
+require 'set'
+module Surrounded
+  module Context
+    def self.extended(base)
+      base.send(:include, InstanceMethods)
+    end
+
+    def triggers
+      @triggers.dup
+    end
+
+    private
+
+    def setup(*setup_args)
+      attr_reader(*setup_args)
+      private(*setup_args)
+
+      define_method(:initialize){ |*args|
+        Hash[setup_args.zip(args)].each{ |role, object|
+
+          role_module_name = Context.classify_string(role)
+          klass = self.class
+
+          if mod = klass.const_defined?(role_module_name) && !mod.is_a?(Class)
+            object = Context.modify(object, klass.const_get(role_module_name))
+          end
+
+          roles[role.to_s] = object
+          instance_variable_set("@#{role}", object)
+        }
+      }
+    end
+
+    def trigger(name, *args, &block)
+      store_trigger(name)
+
+      define_method(:"trigger_#{name}", *args, &block)
+
+      private :"trigger_#{name}"
+
+      define_method(name, *args){
+        begin
+          (Thread.current[:context] ||= []).unshift(self)
+          self.send("trigger_#{name}", *args)
+        ensure
+          (Thread.current[:context] ||= []).shift
+        end
+      }
+    end
+
+    def store_trigger(name)
+      @triggers ||= Set.new
+      @triggers << name
+    end
+
+    def self.classify_string(string)
+      string.to_s.gsub(/(?:^|_)([a-z])/) { $1.upcase }
+    end
+
+    def self.modify(obj, mod)
+      return obj if mod.is_a?(Class)
+      if obj.respond_to?(:cast_as)
+        obj.cast_as(mod)
+      else
+        obj.extend(mod)
+      end
+    end
+
+    module InstanceMethods
+      def role?(name, &block)
+        accessor = eval('self', block.binding)
+        roles.values.include?(accessor) && roles[name.to_s]
+      end
+
+      def triggers
+        self.class.triggers
+      end
+
+      private
+
+      def roles
+        @roles ||= {}
+      end
+    end
+  end
+end

data/lib/surrounded/version.rb

@@ -0,0 +1,3 @@
+module Surrounded
+  VERSION = "0.1.0"
+end

data/surrounded.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'surrounded/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "surrounded"
+  spec.version       = Surrounded::VERSION
+  spec.authors       = ["'Jim Gay'"]
+  spec.email         = ["jim@saturnflyer.com"]
+  spec.description   = %q{Gives an object implicit access to other objects in it's environment.}
+  spec.summary       = %q{Create encapsulated environments for your objects.}
+  spec.homepage      = "http://github.com/saturnflyer/surrounded"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+end

data/test/surrounded_context_test.rb

@@ -0,0 +1,161 @@
+require 'test_helper'
+
+describe Surrounded::Context, '#triggers' do
+  let(:user){ User.new("Jim") }
+  let(:other_user){ User.new("Guille") }
+  let(:context){ TestContext.new(user, other_user) }
+
+  it 'lists the externally accessible trigger methods' do
+    assert context.triggers.include?(:access_other_object)
+  end
+
+  it 'prevents altering the list of triggers externally' do
+    original_trigger_list = context.triggers
+    context.triggers << 'another_trigger'
+    assert_equal original_trigger_list, context.triggers
+  end
+end
+
+describe Surrounded::Context, '.triggers' do
+  it 'lists the externally accessible trigger methods' do
+    assert TestContext.triggers.include?(:access_other_object)
+  end
+
+  it 'prevents altering the list of triggers externally' do
+    original_trigger_list = TestContext.triggers
+    TestContext.triggers << 'another_trigger'
+    assert_equal original_trigger_list, TestContext.triggers
+  end
+end
+
+describe Surrounded::Context, '.trigger' do
+  let(:user){ User.new("Jim") }
+  let(:other_user){ User.new("Guille") }
+  let(:context){ TestContext.new(user, other_user) }
+
+  it 'defines a public method on the context' do
+    assert context.respond_to?(:access_other_object)
+  end
+
+  it 'gives objects access to each other inside the method' do
+    assert_raises(NoMethodError){
+      user.other_user
+    }
+    assert_equal "Guille", context.access_other_object
+  end
+end
+
+describe Surrounded::Context, '#role?' do
+  let(:user){
+    test_user = User.new("Jim")
+
+    def test_user.get_role(name, context)
+      context.role?(name){}
+    end
+
+    test_user
+  }
+  let(:other_user){ User.new("Guille") }
+  let(:external){
+    external_object = Object.new
+    def external_object.get_role_from_context(name, context)
+      context.role?(name){}
+    end
+    external_object
+  }
+  let(:context){ TestContext.new(user, other_user) }
+
+  it 'returns the object assigned to the named role' do
+    assert_equal user, user.get_role(:user, context)
+  end
+
+  it 'returns false if the role does not exist' do
+    refute user.get_role(:non_existant_role, context)
+  end
+
+  it 'returns false if the accessing object is not a role player in the context' do
+    refute external.get_role_from_context(:user, context)
+  end
+
+  it 'checks for the role based upon the calling object' do
+    refute context.role?(:user){} # this test is the caller
+  end
+end
+
+require 'casting'
+CastingUser = Struct.new(:name)
+class CastingUser
+  include Casting::Client
+  delegate_missing_methods
+end
+
+class RoleAssignmentContext
+  extend Surrounded::Context
+
+  setup(:user, :other_user)
+
+  trigger :user_ancestors do
+    user.singleton_class.ancestors
+  end
+
+  trigger :other_user_ancestors do
+    other_user.singleton_class.ancestors
+  end
+
+  trigger :check_user_response do
+    user.respond_to?(:a_method!)
+  end
+
+  trigger :check_other_user_response do
+    user.respond_to?(:a_method!)
+  end
+
+  module User
+    def a_method!; end
+  end
+  module OtherUser
+    def a_method!; end
+  end
+end
+
+describe Surrounded::Context, 'assigning roles' do
+  let(:user){ CastingUser.new("Jim") }
+  let(:other_user){ User.new("Guille") }
+  let(:context){ RoleAssignmentContext.new(user, other_user) }
+
+  it 'tries to use casting to add roles' do
+    refute_includes(context.user_ancestors, RoleAssignmentContext::User)
+  end
+
+  it 'extends objects with role modules failing casting' do
+    assert_includes(context.other_user_ancestors, RoleAssignmentContext::OtherUser)
+  end
+
+  it 'sets role players to respond to role methods' do
+    assert context.check_user_response
+    assert context.check_other_user_response
+  end
+
+  it 'will not use classes as roles' do
+    ClassRoleAssignmentContext = Class.new do
+      extend Surrounded::Context
+
+      setup(:thing, :the_test)
+
+      trigger :check_user_response do
+        the_test.refute thing.respond_to?(:method_from_class), 'did respond to :method_from_class'
+      end
+
+      class Thing
+        def method_from_class; end
+      end
+
+    end
+
+    user = User.new('Jim')
+
+    context = ClassRoleAssignmentContext.new(user, self)
+
+    context.check_user_response
+  end
+end

data/test/surrounded_test.rb

@@ -0,0 +1,43 @@
+require 'test_helper'
+
+describe "Surrounded", 'without context' do
+
+  let(:jim){ User.new("Jim") }
+
+  it "never has context roles" do
+    Thread.current[:context] = []
+    assert_nil jim.send(:context).role?('anything')
+  end
+
+end
+
+describe "Surrounded" do
+  let(:jim){ User.new("Jim") }
+  let(:guille){ User.new("Guille") }
+  let(:external_user){ User.new("External User") }
+
+  let(:context){
+    TestContext.new(jim, guille)
+  }
+
+  before do
+    Thread.current[:context] = [context]
+  end
+
+  it "has access to objects in the context" do
+    assert_equal jim.other_user, guille
+  end
+  it "responds to messages for roles on the context" do
+    assert jim.respond_to?(:other_user)
+
+    Thread.current[:context] = []
+
+    refute jim.respond_to?(:other_user)
+  end
+
+  it "prevents access to context objects for external objects" do
+    assert_raises(NoMethodError){
+      external_user.user
+    }
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,25 @@
+require 'simplecov'
+require 'minitest/autorun'
+require 'coveralls'
+
+if ENV['COVERALLS']
+  Coveralls.wear!
+end
+
+require 'surrounded'
+require 'surrounded/context'
+
+User = Struct.new(:name)
+class User
+  include Surrounded
+end
+
+class TestContext
+  extend Surrounded::Context
+
+  setup(:user, :other_user)
+
+  trigger :access_other_object do
+    user.other_user.name
+  end
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: surrounded
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- '''Jim Gay'''
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-06-12 00:00:00.000000000 Z
+dependencies:
+- !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.
+email:
+- jim@saturnflyer.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .simplecov
+- .travis.yml
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/rails.rb
+- lib/surrounded.rb
+- lib/surrounded/context.rb
+- lib/surrounded/version.rb
+- surrounded.gemspec
+- test/surrounded_context_test.rb
+- test/surrounded_test.rb
+- test/test_helper.rb
+homepage: http://github.com/saturnflyer/surrounded
+licenses:
+- MIT
+metadata: {}
+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.0.3
+signing_key: 
+specification_version: 4
+summary: Create encapsulated environments for your objects.
+test_files:
+- test/surrounded_context_test.rb
+- test/surrounded_test.rb
+- test/test_helper.rb