surrounded 0.9.11 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 3364c250a02c0589ae2cbaf9645235cfd83f7406
-  data.tar.gz: 28bcbe612f92d77a9df5d4a5294ebc22420013a2
+SHA256:
+  metadata.gz: 152c9c728084be8069384cf825cedf5ab827d4fd28b0710cbdd19229d8284bc7
+  data.tar.gz: 82a50b285aa5328084481c438d78f8ed3e17ba362bcad45c14efaf5ad1bf0fc3
 SHA512:
-  metadata.gz: bf99487271fdcc488dbf5b8dc36d8f7fdd66354bb218bf753682de69cc281d63c9808e3c5f3b7a23c7e71a31f61fa8df0643d9ca4b049c47d35e5734c3f63e79
-  data.tar.gz: 5ce4fcdc96205adf8e24d31de75e88ce5e42877266c4714a8066084f61d3e598140bf2830f8f7193c63e318d61c9fb627278e3f5e43b7785d954544e895128dd
+  metadata.gz: 9f7cf841bf2c4ceeb27fd6bd2f11c4041cad7c28e1ce71574b5bbc1c201b0944a2481966b1c2349b3cbfd465a98f7627f1621fae0e0e8d2c2c9fcde42859577f
+  data.tar.gz: aa91c16fefb0cdc19f1b597d2fffd876c2f0bce15bcbcaacb3a713570acac350d8ff434a8c3d6177d4c9e1a79c620611f012d1aff2bcd24fef10ddf696bcd13b

data/.github/workflows/codeql-analysis.yml

@@ -0,0 +1,70 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ master ]
+  schedule:
+    - cron: '41 18 * * 4'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'ruby' ]
+        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]
+        # Learn more about CodeQL language support at https://git.io/codeql-language-support
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v3
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v2
+      with:
+        languages: ${{ matrix.language }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+        # queries: ./path/to/local/query, your-org/your-repo/queries@main
+
+    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+    # If this step fails, then you should remove it and run the build manually (see below)
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v2
+
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 https://git.io/JvXDl
+
+    # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
+    #    and modify them (or add more) to build your code if your project
+    #    uses a compiled language
+
+    #- run: |
+    #   make bootstrap
+    #   make release
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v2

data/.github/workflows/test.yml

@@ -0,0 +1,18 @@
+name: spec
+
+on: push
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: [ '2.7', '3.0', '3.1' ]
+    name: Ruby ${{ matrix.ruby }} sample
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle exec rake

data/Changelog.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.1.0]
+
+- Dropped support for Ruby below 2.7 to take advantage of the ellipsis for argument forwarding
+- Memoize the Negotiator methods for interface
+
+## [1.0.1]
+
+- Fix a bug where shortcut_triggers would not work with keyword initialize
+
+## [1.0.0]
+
+- 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
+
 ## [0.9.11]
 
 - Rely on the standard library Forwardable to setup how the RoleMap forwards messages to the container.
@@ -11,4 +25,4 @@ All notable changes to this project will be documented in this file.
 ## [0.9.10]
 
 - 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.
+- Move InvalidRoleType exception under the host context class namespace. This allows you to rescue from your own namespace.

data/Gemfile

@@ -2,15 +2,8 @@ source 'https://rubygems.org'
 
 group :test do
   gem 'minitest'
-  # gem 'mutant', git: 'https://github.com/kbrock/mutant.git', ref: 'minitest'
   gem "simplecov"
-  gem 'coveralls', :require => false
   gem 'casting'
-  gem 'rubinius-coverage', :platform => :rbx
-end
-
-platforms :rbx do
-  gem 'rubysl', '~> 2.0'
 end
 
 gemspec

data/LICENSE.txt

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

data/README.md

@@ -1,10 +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)
+[![Build Status](https://github.com/saturnflyer/surrounded/actions/workflows/test.yml/badge.svg)](https://github.com/saturnflyer/surrounded/actions)
 [![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)
-[![Gem Version](https://badge.fury.io/rb/surrounded.png)](http://badge.fury.io/rb/surrounded)
 
 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.
 
@@ -43,7 +41,7 @@ Here, you've specified the order when initializing so you can use it like this:
 ```ruby
 user1 = User.find(1)
 user2 = User.find(2)
-context = Employment.new(user1, user2)
+context = Employment.new(employee: user1, boss: user2)
 ```
 
 That ensures that `user1` will become (and have all the features of) the `employee` and `user2` will become (and have all the features of) the `boss`.
@@ -53,20 +51,20 @@ There are 2 things left to do:
 1. define behaviors for each role and
 2. define how you can trigger their actions
 
-Currently initializing contexts does not require the use of keyword arguments, _but it will in the future_.
+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 `keyword_initialize`:
+You should consider using explicit names when initializing now by using `initialize_without_keywords`:
 
 ```ruby
 class Employment
   extend Surrounded::Context
 
-  keyword_initialize :employee, :boss
+  initialize_without_keywords :employee, :boss
 end
 
 user1 = User.find(1)
 user2 = User.find(2)
-context = Employment.new(employee: user1, boss: user2)
+context = Employment.new(user1, user2)
 ```
 
 This will allow you to prepare your accessing code to use keywords.
@@ -135,7 +133,7 @@ end
 You'll need to define way to trigger these behaviors to occur so that you can use them.
 
 ```ruby
-context = Employment.new(user1, user2)
+context = Employment.new(employee: user1, boss: user2)
 
 context.plan_weekend_work
 ```
@@ -249,7 +247,7 @@ By adding `Surrounded::Context` you can shortcut all this work.
 ```ruby
 class Employment
   extend Surrounded::Context
-  
+
   initialize(:employee, :boss)
 
   module Employee
@@ -269,7 +267,7 @@ Well, it just so happens that you can. This code will work just fine:
 ```ruby
 class Employment
   extend Surrounded::Context
-  
+
   initialize(:employee, :boss)
 
   class Employee < SimpleDelegator
@@ -285,7 +283,7 @@ But the syntax can be even simpler than that if you want.
 ```ruby
 class Employment
   extend Surrounded::Context
-  
+
   initialize(:employee, :boss)
 
   role :employee do
@@ -299,7 +297,7 @@ By default, this code will create a module for you named `Employee`. If you want
 ```ruby
 class Employment
   extend Surrounded::Context
-  
+
   initialize(:employee, :boss)
 
   wrap :employee do
@@ -313,7 +311,7 @@ But if you're making changes and you decide to move from a module to a wrapper o
 ```ruby
 class Employment
   extend Surrounded::Context
-  
+
   initialize(:employee, :boss)
 
   role :employee, :wrapper do
@@ -346,7 +344,7 @@ end
 
 Now the `User` instances will be able to implicitly access objects in their environment.
 
-Via `method_missing` those `User` instances can access a `context` object it stores in an internal collection. 
+Via `method_missing` those `User` instances can access a `context` object it stores in an internal collection.
 
 Inside of the `Employment` context we saw above, the `employee` and `boss` objects are instances of `User` for this example.
 
@@ -442,7 +440,7 @@ context.triggers #=> [:plan_weekend_work]
 
 You might find that useful for dynamically defining user interfaces.
 
-Sometimes I'd rather not use this DSL, however. I want to just write regular methods. 
+Sometimes I'd rather not use this DSL, however. I want to just write regular methods.
 
 We can do that too. You'll need to opt in to this by specifying `trigger :your_method_name` for the methods you want to use.
 
@@ -454,7 +452,7 @@ class Employment
     employee.quit
   end
   trigger :plan_weekend_work
-  
+
   # or in Ruby 2.x
   trigger def plan_weekend_work
     employee.quit
@@ -487,12 +485,12 @@ By running `protect_triggers` you'll be able to define when triggers may or may
 class Employment
   extend Surrounded::Context
   protect_triggers
-  
+
   def plan_weekend_work
     employee.quit
   end
   trigger :plan_weekend_work
-  
+
   disallow :plan_weekend_work do
     employee.bank_balance > 1000000
   end
@@ -627,14 +625,30 @@ class Organization
   extend Surrounded::Context
 
   initialize_without_keywords :leader, :members
-  
+
   role :members do
     # special behavior for the collection
   end
-  
+
   role :member do
     # special behavior to be applied to each member in the collection
-  end  
+  end
+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
 ```
 
@@ -643,7 +657,7 @@ end
 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:
 
 ```ruby
-context = Employment.new(current_user, the_boss)
+context = Employment.new(employee: current_user, boss: the_boss)
 context.rebind(employee: another_user, boss: someone_else) # same context, new players
 ```
 
@@ -671,7 +685,7 @@ class ExpensiveCalculation
     end
   end
 end
-ExpensiveCalculation.new(some_object, some_collection).send_to_background(:do_expensive_calculation)
+ExpensiveCalculation.new(leader: some_object, members: some_collection).send_to_background(:do_expensive_calculation)
 ```
 
 The above example is merely pseudo-code to show how `initializer_arguments` can be used. Customize it according to your own needs.
@@ -686,14 +700,14 @@ Surrounded::Context.default_role_type = :module # also :wrap, :wrapper, or :inte
 
 class ActiviatingAccount
   extend Surrounded::Context
-  
+
   # set the default role type only for this class
   self.default_role_type = :module # also :wrap, :wrapper, or :interface
 
   # shortcut initialization code
   initialize(:activator, :account)
   # or handle it yourself
-  def initialize(activator, account)
+  def initialize(activator:, account:)
     # 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]])
@@ -707,18 +721,21 @@ class ActiviatingAccount
   # 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
-  
+
   # If you need to mix default initialzation and extra work use a block
   initialize :activator, :account do
     map_roles(:third_party => get_some_other_object)
+    # explicitly set a single role
+    map_role(:something_new, 'SomeRoleConstant', object_to_play_the_role)
   end
+
   # but remember to set the extra accessors:
-  private_attr_reader :third_party
+  private_attr_reader :third_party, :something_new
 
-  # initialize with keyword arguments
-  keyword_initialize(:activator, :account)
-  # this makes the following instance method signature with required keyword arguments
-  def initialize(activator:, account:)
+  # initialize without keyword arguments
+  initialize_without_keywords(:activator, :account)
+  # this makes the following instance method signature with positional arguments
+  def initialize(activator, account)
     # ...
   end
 
@@ -756,7 +773,7 @@ class ActiviatingAccount
   #   end
   # end
 
-  # if you use a regular method and want to use context-specific behavior, 
+  # if you use a regular method and want to use context-specific behavior,
   # you must handle storing the context yourself:
   def regular_method
     apply_behaviors # handles the adding of all the roles and behaviors
@@ -771,30 +788,30 @@ class ActiviatingAccount
   trigger :some_trigger_method do
     activator.some_behavior # behavior always available
   end
-  
+
   trigger def some_other_trigger
     activator.some_behavior # behavior always available
   end
-  
+
   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
-  
+
   # 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
   # you could also use `guard` instead of `disallow`
-  
+
   # or define your own method without the `disallow` keyword
   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)
   # This will make all triggers shortcuts.
@@ -804,11 +821,11 @@ class ActiviatingAccount
     instance = self.new(activator, account)
     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
-  
+
   # 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
@@ -816,14 +833,14 @@ class ActiviatingAccount
   forwarding [:list, :of, :methods, :to, :forward] => :role_name
 end
 
-# with keyword_initialize (will be changed to initialize)
+# with initialize (also keyword_initialize)
 context = ActiviatingAccount.new(activator: some_object, account: some_account)
-# with initialize (this will be moved to initialize_without_keywords)
+# with initialize_without_keywords
 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
@@ -834,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
@@ -917,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:
 
@@ -1072,7 +1103,7 @@ And then execute:
 Or install it yourself as:
 
     $ gem install surrounded
-    
+
 ## Installation for Rails
 
 See [surrounded-rails](https://github.com/saturnflyer/surrounded-rails)