surrounded 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 32e91c5123e8db80ef2b15289144c2cec4f5a774
-  data.tar.gz: 8ffdd46f4497eee0fc0c96f29de1efb0631879d6
+SHA256:
+  metadata.gz: e6cd923340dae45ac571dd98abf41be26d111f4569c59d98c27cd4e71f6204d1
+  data.tar.gz: a5d11c76eccb01b30fdec8aaced90571449d96c21fe4eced13e55dc1603241da
 SHA512:
-  metadata.gz: a2c8b8e5b137b7b8b74c2642cdc490bbcab860dcd85ca0a08e9b67490ce0f1ff4c5b405821bb3daa1e3a643514e75023265cc902b0617a3cff1bee90a61a2480
-  data.tar.gz: a25fd8d9c292be440405e732ce59f5087a0100a628a0f424ad95a918f72e924377c8485eeeec4a70fa1d01dd900ad5828530ee693ab252d1b56ebfa569aa16ad
+  metadata.gz: 90659aa84b6565797f5b45fb4b637d0dfa21190dfed5366c20b586c4351ca1d0f02fdc5f8d6c45620ac6c9b36dccac28a842ce74b93a2d0a9258297db3d9e0e4
+  data.tar.gz: 4831ec1fe6a7dda8a9578776ecb0b2e2030ff37490d15f7e7f35351253bfe7f2c52c9ae1aa8fb7172cb471236b3d5c639f7eae8ef8c5510668a56542ba0fe014

data/Changelog.md

@@ -1,19 +1,19 @@
-# Change Log
+# Changelog
 
 All notable changes to this project will be documented in this file.
 
-## [1.0.0]
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
 
-- Drop deprecations around Context initialize method. It now requires keyword arguments. Non-keyword argumennts may be used with initialize_without_keywords
-- Remove code supporting exception cause it InvalidRoleType prior to ruby 2.1
+## [1.1.1] - 2025-10-17
 
-## [0.9.11]
+### Changed
 
-- Rely on the standard library Forwardable to setup how the RoleMap forwards messages to the container.
-- Update RoleMap role_player? method to rescue from StandardError, a non-implementation-specific exception.
-- Move to using triad 0.3.0 which relies on concurrent-ruby 0.9+ and moves off of thread_safe 0.3.5
+- Version and changelog management with Reissue. (c919a3a)
+- Set the gemspec to use a file list rather than depending on git (69b9a43)
+- Update singularize_name to duplicate a string before altering the value. (3487d0d)
+- Alter the list of identity methods in Negotiator to include __id__. (b98fb5a)
 
-## [0.9.10]
+### Removed
 
-- Do something with name collisions when a role player has an existing method of another role in the context.
-- Move InvalidRoleType exception under the host context class namespace. This allows you to rescue from your own namespace.
+- Code Climate and Pull Review configuration. (46f0057)

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2013-2016 'Jim Gay'
+Copyright (c) 2013-2025 'Jim Gay'
 
 MIT License
 

data/README.md

@@ -1,8 +1,8 @@
 # ![Surrounded](http://saturnflyer.github.io/surrounded/images/surrounded.png "Surrounded")
+
 ## Be in control of business logic.
 
-[![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)
+[![Build Status](https://github.com/saturnflyer/surrounded/actions/workflows/test.yml/badge.svg)](https://github.com/saturnflyer/surrounded/actions)
 
 Surrounded is designed to help you better manage your business logic by keeping cohesive behaviors together. Bring objects together to implement your use cases and gain behavior only when necessary.
 
@@ -53,13 +53,13 @@ There are 2 things left to do:
 
 Initializing contexts does not require the use of keyword arguments, but you may opt out.
 
-You should consider using explicit names when initialize now by using `initialize_without_keywords`:
+You should consider using explicit names when initializing now by using `initialize_without_keywords`:
 
 ```ruby
 class Employment
   extend Surrounded::Context
 
-  initialize_withou_keywords :employee, :boss
+  initialize_without_keywords :employee, :boss
 end
 
 user1 = User.find(1)
@@ -636,6 +636,22 @@ class Organization
 end
 ```
 
+If you want to change the way the singular verson of a role is used, override `singularize_name`:
+
+```ruby
+class Organization
+  extend Surrounded::Context
+
+  def singularize_name(name)
+    if name == "my special rule"
+      # do your thing
+    else
+      super # use the default
+    end
+  end
+end
+```
+
 ## Reusing context objects
 
 If you create a context object and need to use the same type of object with new role players, you may use the `rebind` method. It will clear any instance_variables from your context object and map the given objects to their names:
@@ -824,7 +840,7 @@ context = ActiviatingAccount.new(some_object, some_account)
 context.triggers # => lists a Set of triggers
 # when using protect_triggers
 context.triggers # => lists a Set of triggers which may currently be called
-context.triggers # => lists a Set of all triggers (the same as if protect_triggers was _not_ used)
+context.all_triggers # => lists a Set of all triggers (the same as if protect_triggers was _not_ used)
 context.allow?(:trigger_name) # => returns a boolean if the trigger may be run
 
 # reuse the context object with new role players
@@ -835,6 +851,20 @@ context.rebind(activator: another_object, account: another_account)
 
 The dependencies are minimal. The plan is to keep it that way but allow you to configure things as you need. The [Triad](http://github.com/saturnflyer/triad) project was written specifically to manage the mapping of roles and objects to the modules which contain the behaviors. It is used in Surrounded to keep track of role player, roles, and role constant names but it is not a hard requirement. You may implement your own but presently you'll need to dive into the implementation to fully understand how. Future updates may provide better support and guidance.
 
+If you want to override the class used for mapping roles to behaviors, override the `role_map` method.
+
+```ruby
+class MyContext
+  extend Surrounded::Context
+
+  def role_map
+    @container ||= role_mapper_class.new(base: MySpecialDataContainer)
+  end
+end
+```
+
+The class you provide will be initialized with `new` and is expected to implement the methods: `:update`, `:each`, `:values`, and `:keys`.
+
 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
@@ -890,7 +920,7 @@ end
 
 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.
+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
@@ -918,9 +948,9 @@ class MyCustomContext
 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`.
+You can remember the method name by the convention that `remove` or `apply` describes it's function, `behavior` refers to the first argument (the constant holding the behaviors), and then the name of the role which refers to the role playing object: `remove_behavior_role`.
 
-##Name collisions between methods and roles
+## Name collisions between methods and roles
 
 Lets say that you wish to create a context as below, intending to use instances of the following two classes as role players:
 
@@ -952,7 +982,6 @@ Lets say that you wish to create a context as below, intending to use instances
       postcode.send
     end
 
-    end
     role :postcode do
       def send
         # do things...
@@ -961,6 +990,7 @@ Lets say that you wish to create a context as below, intending to use instances
     end
   end
 ```
+
 When you call the `:send` trigger you are likely to be greeted with an `NoMethodError` exception. The reason for this is that there is a name collision between `Postcode#country`, and the `:country` role in the `SendAParcel` context. Where a name collision exists, the method in the role player overrides that of the calling class and you get unexpected results.
 
 To address this issue, use `on_name_collision` to specify the name of a method to use when collisions are found:

data/Rakefile

@@ -1,17 +1,24 @@
 require "bundler/gem_tasks"
 
-require 'rake/testtask'
+require "rake/testtask"
 
 Rake::TestTask.new do |t|
   t.libs << "test"
-  t.test_files = FileList['test/*_test.rb']
-  t.ruby_opts = ["-w"]
+  t.test_files = FileList["test/*_test.rb"]
   t.verbose = true
+  t.warning = true
 end
-task :default => :test
 
+task default: :test
+
+require "reissue/gem"
+
+Reissue::Task.create :reissue do |task|
+  task.version_file = "lib/surrounded/version.rb"
+  task.fragment = :git
+end
 
 # task :mutant, [:class] do |task, args|
 #   klass = args[:class] || 'Surrounded'
 #   sh "bundle exec mutant --include lib --require surrounded --use minitest #{klass}"
-# end
+# end

data/lib/surrounded/access_control.rb

@@ -2,75 +2,68 @@ module Surrounded
   module Context
     class AccessError < ::StandardError; end
   end
+
   module AccessControl
     def self.extended(base)
       base.send(:include, AccessMethods)
       Surrounded::Exceptions.define(base, exceptions: :AccessError)
     end
-    
+
     private
-    
+
     def disallow(*names, &block)
       names.map do |name|
         define_access_method(name, &block)
       end
     end
-    alias guard disallow
-    
+    alias_method :guard, :disallow
+
     def trigger_return_content(name, *args, &block)
       %{
 
         method_restrictor = "disallow_#{name}?"
         if self.respond_to?(method_restrictor, true) && self.send(method_restrictor)
-          raise ::#{self.to_s}::AccessError.new("access to #{self.name}##{name} is not allowed")
+          raise ::#{self}::AccessError.new("access to #{self.name}##{name} is not allowed")
         end
 
       #{super}
       }
     end
-    
+
     def define_access_method(name, &block)
       mod = Module.new
       mod.class_eval {
         define_method "disallow_#{name}?" do
-          begin
-            apply_behaviors
-            instance_exec(&block)
-          ensure
-            remove_behaviors
-          end
+          apply_behaviors
+          instance_exec(&block)
+        ensure
+          remove_behaviors
         end
       }
       const_set("SurroundedAccess#{name}", mod)
       include mod
     end
-    
+
     module AccessMethods
       # Return a Set of all defined triggers regardless of any disallow blocks
       def all_triggers
         self.class.triggers
       end
-    
+
       # Return a Set of triggers which may be run according to any restrictions defined
       # in disallow blocks.
       def triggers
-        all_triggers.select {|name|
-          method_restrictor = "disallow_#{name}?"
-          !self.respond_to?(method_restrictor, true) || !self.send(method_restrictor)
+        all_triggers.select { |name|
+          allow?(name)
         }.to_set
       end
 
       # Ask if the context will allow access to a trigger given the current players.
       def allow?(name)
-        unless self.respond_to?(name)
-          raise NoMethodError, %{undefined method `#{name}' for #{self.inspect}}
-        end
-        if self.respond_to?("disallow_#{name}?")
-          !self.public_send("disallow_#{name}?")
-        else
-          true
-        end
+        raise NoMethodError, %(undefined method `#{name}' for #{inspect}) unless respond_to?(name)
+        predicate = "disallow_#{name}?"
+        !respond_to?(predicate) || !public_send(predicate)
       end
     end
   end
-end
+end

data/lib/surrounded/context/forwarding.rb

@@ -1,27 +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 |*args, &block|
-          self.send(receiver).public_send(message,*args, &block)
+      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 |*args, **kwargs, &block|
+          send(receiver).public_send(message, *args, **kwargs, &block)
         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
+
+      alias_method :forward, :forward_trigger
+      alias_method :forwards, :forward_triggers
     end
   end
-end
+end

data/lib/surrounded/context/initializing.rb

@@ -1,19 +1,21 @@
 module Surrounded
   module Context
     module Initializing
+      extend Seclusion
+
       # Shorthand for creating an instance level initialize method which
       # handles the mapping of the given arguments to their named role.
       def initialize_without_keywords(*setup_args, &block)
-        parameters = setup_args.join(',')
+        parameters = setup_args.join(",")
         default_initializer(parameters, setup_args, &block)
       end
 
       def initialize(*setup_args, &block)
-        parameters = setup_args.map{|a| "#{a}:"}.join(',')
+        parameters = setup_args.map { |a| "#{a}:" }.join(",")
         default_initializer(parameters, setup_args, &block)
       end
-      alias keyword_initialize initialize
-      alias initialize_with_keywords keyword_initialize
+      alias_method :keyword_initialize, :initialize
+      alias_method :initialize_with_keywords, :keyword_initialize
 
       def initializer_block
         @initializer_block
@@ -30,15 +32,16 @@ module Surrounded
         line = __LINE__; mod.class_eval %{
           def initialize(#{params})
             @role_map = role_mapper_class.new
-            @initializer_arguments = Hash[#{setup_args.to_s}.zip([#{setup_args.join(',')}])]
+            @initializer_arguments = Hash[#{setup_args}.zip([#{setup_args.join(",")}])]
             map_roles(@initializer_arguments)
             self.class.apply_initializer_block(self)
           end
         }, __FILE__, line
-        const_set("ContextInitializer", mod)
+        const_set(:ContextInitializer, mod)
         include mod
+
         private_attr_reader :initializer_arguments
       end
     end
   end
-end
+end

data/lib/surrounded/context/name_collision_detector.rb

@@ -1,56 +1,56 @@
 module Surrounded
   module Context
-    class NameCollisionError <::StandardError; end
-    module NameCollisionDetector
+    class NameCollisionError < ::StandardError; end
 
+    module NameCollisionDetector
       attr_reader :handler
 
       def self.extended(base)
         base.send :include, NameCollisionHandler
         Surrounded::Exceptions.define(base, exceptions: :NameCollisionError)
       end
-  
+
       def on_name_collision(method_name)
         @handler = method_name
       end
 
       module NameCollisionHandler
-    
         private
-    
+
         def detect_collisions(role_object_map)
           if handler
             handle_collisions(collision_warnings(role_object_map))
           end
         end
-    
+
         def collision_warnings(role_object_map)
-          role_object_map.select{|role, object|
+          role_object_map.select { |role, object|
             ![object.methods & role_object_map.keys].flatten.empty?
-          }.map{|role, object|
-            role_collision_message(role,(object.methods & role_object_map.keys).sort)
+          }.map { |role, object|
+            role_collision_message(role, (object.methods & role_object_map.keys).sort)
           }.join("\n")
         end
-    
+
         def handle_collisions(collisions)
           handler_args = [collisions]
           if handler == :raise
             handler_args.unshift self.class::NameCollisionError
           end
-      
+
           handler_method.call(*handler_args)
         end
-    
+
         def role_collision_message(role, colliding_method_names)
           "#{role} has name collisions with #{colliding_method_names}"
         end
-    
-        def nothing(*); end
+
+        def nothing(*)
+        end
 
         def handler
           self.class.handler
         end
-    
+
         def handler_method
           if handler.respond_to?(:call)
             handler
@@ -59,10 +59,10 @@ module Surrounded
           elsif self.class.respond_to?(handler, true)
             self.class.method(handler)
           else
-            raise ArgumentError, %{your name collision handler was set to `#{handler}' but there is no instance nor class method of that name}
+            raise ArgumentError, %(your name collision handler was set to `#{handler}' but there is no instance nor class method of that name)
           end
         end
       end
     end
   end
-end
+end

data/lib/surrounded/context/negotiator.rb

@@ -14,24 +14,24 @@ module Surrounded
           # For each method in the module, directly forward to the wrapped object to
           # circumvent method_missing
           mod.instance_methods(false).each do |meth|
-            num = __LINE__; klass.class_eval %{
-              def #{meth}(*args, &block)
-                __behaviors__.instance_method(:#{meth}).bind(@object).call(*args, &block)
+            klass.class_eval <<~MOD, __FILE__, __LINE__ + 1
+              def #{meth}(...)
+                @#{meth}_method ||= __behaviors__.instance_method(:#{meth}).bind(@object)
+                @#{meth}_method.call(...)
               end
-            }, __FILE__, num
+            MOD
           end
           klass
         end
       end
 
-
-      identity = %w[__send__ object_id equal?]
+      identity = %w[__send__ __id__ object_id equal?]
       method_access = %w[respond_to? method __behaviors__]
 
-      reserved_methods = (identity + method_access).join('|')
+      reserved_methods = (identity + method_access).join("|")
 
       # Remove all methods except the reserved methods
-      instance_methods.reject{ |m|
+      instance_methods.reject { |m|
         m.to_s =~ /#{reserved_methods}/
       }.each do |meth|
         undef_method meth
@@ -51,19 +51,19 @@ module Surrounded
         self
       end
       # These only differ in the message they send
-      alias remove_context store_context
+      alias_method :remove_context, :store_context
 
       def initialize(object)
         @object = object
       end
 
-      def method_missing(meth, *args, &block)
-        @object.send(meth, *args, &block)
+      def method_missing(meth, ...)
+        @object.send(meth, ...)
       end
 
-      def respond_to_missing?(meth, include_private=false)
+      def respond_to_missing?(meth, include_private = false)
         @object.respond_to?(meth, include_private)
       end
     end
   end
-end
+end

data/lib/surrounded/context/role_builders.rb

@@ -3,13 +3,14 @@ module Surrounded
     class InvalidRoleType < ::StandardError; end
 
     module RoleBuilders
+      extend Seclusion
 
       def self.extended(base)
         Surrounded::Exceptions.define(base, exceptions: :InvalidRoleType)
       end
 
       # Define behaviors for your role players
-      def role(name, type=default_role_type, &block)
+      def role(name, type = default_role_type, &block)
         if type == :module
           mod_name = RoleName(name)
           mod = Module.new(&block).send(:include, ::Surrounded)
@@ -25,7 +26,7 @@ module Surrounded
 
       # Create a named behavior for a role using the standard library SimpleDelegator.
       def wrap(name, &block)
-        require 'delegate'
+        require "delegate"
         wrapper_name = RoleName(name)
         klass = private_const_set(wrapper_name, Class.new(SimpleDelegator, &block))
         klass.send(:include, Surrounded)
@@ -35,7 +36,7 @@ module Surrounded
       # 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'
+        require "delegate"
         wrapper_name = RoleName(name)
         klass = private_const_set(wrapper_name, DelegateClass(Object.const_get(class_name.to_s)))
         klass.class_eval(&block)
@@ -52,19 +53,19 @@ module Surrounded
       # access them from any of its methods.
       def interface(name, &block)
         # AdminInterface
-        interface_name = RoleName(name, 'Interface')
+        interface_name = RoleName(name, "Interface")
         behavior = private_const_set(interface_name, Module.new(&block))
 
-        require 'surrounded/context/negotiator'
+        require "surrounded/context/negotiator"
         # Admin
         private_const_set(RoleName(name), Negotiator.for_role(behavior))
       end
 
       private
-      def RoleName(text, suffix=nil)
+
+      def RoleName(text, suffix = nil)
         RoleName.new(text, suffix)
       end
-
     end
   end
 end

data/lib/surrounded/context/role_map.rb

@@ -1,41 +1,48 @@
-require 'triad'
-require 'forwardable'
+require "triad"
+require "forwardable"
 module Surrounded
   module Context
     class RoleMap
       extend Forwardable
 
       class << self
-        def from_base(klass=::Triad)
-          role_mapper = Class.new(self)
-          Surrounded::Exceptions.define(role_mapper, exceptions: :ItemNotPresent, namespace: klass)
-          role_mapper.container_class=(klass)
-          role_mapper.def_delegators :container, :update, :each, :values, :keys
-          role_mapper
+        # Get the role map container and provide an alternative if desired
+        # Ex: RoleMap.from_base(SomeCustomContainer)
+        def from_base(klass = ::Triad)
+          unless const_defined?(:Container)
+            role_mapper = Class.new(self)
+            role_mapper.container_class = (klass)
+            Surrounded::Exceptions.define(role_mapper, exceptions: :ItemNotPresent, namespace: klass)
+            const_set(:Container, role_mapper)
+          end
+          const_get(:Container)
         end
 
-        def container_class=(klass)
-          @container_class = klass
-        end
+        attr_writer :container_class
       end
 
+      def_delegators :container, :update, :each, :values, :keys
+
       def container
         @container ||= self.class.instance_variable_get(:@container_class).new
       end
 
+      # Check if a role exists in the map
       def role?(role)
         keys.include?(role)
       end
 
+      # Check if an object is playing a role in this map
       def role_player?(object)
         !values(object).empty?
-      rescue ::StandardError
+      rescue container.class::ItemNotPresent
         false
       end
 
+      # Get the object playing the given role
       def assigned_player(role)
         values(role).first
       end
     end
   end
-end
+end

data/lib/surrounded/context/seclusion.rb

@@ -0,0 +1,20 @@
+module Surrounded
+  module Context
+    module Seclusion
+      # Set a named constant and make it private
+      def private_const_set(name, const)
+        unless role_const_defined?(name)
+          const = const_set(name, const)
+          private_constant name.to_sym
+        end
+        const
+      end
+
+      # Create attr_reader for the named methods and make them private
+      def private_attr_reader(*method_names)
+        attr_reader(*method_names)
+        private(*method_names)
+      end
+    end
+  end
+end