README.md in surrounded-1.0.0 vs README.md in surrounded-1.1.0
- old
+ new
@@ -1,9 +1,9 @@
# 
## Be in control of business logic.
-[](https://travis-ci.org/saturnflyer/surrounded)
+[](https://github.com/saturnflyer/surrounded/actions)
[](https://codeclimate.com/github/saturnflyer/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.
## How to think about your objects
@@ -51,17 +51,17 @@
1. define behaviors for each role and
2. define how you can trigger their actions
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)
user2 = User.find(2)
context = Employment.new(user1, user2)
@@ -634,10 +634,26 @@
# special behavior to be applied to each member in the collection
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
+```
+
## 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:
```ruby
@@ -822,21 +838,35 @@
# 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
context.rebind(activator: another_object, account: another_account)
```
## Dependencies
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
Surrounded is designed to be flexible for you. If you have your own code to manage applying behaviors, you can setup your context class to use it.
@@ -916,12 +946,12 @@
role_player.cleanup # or whatever your need to do with your constant and object.
end
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:
```ruby
class Postcode