README.md in usable-2.0.0 vs README.md in usable-2.1.0
- old
+ new
@@ -25,11 +25,11 @@
max_versions 10
table_name 'custom_versions'
end
def save
- usable_method(:save_version).call
+ save_version
end
end
model = Model.new
model.save_version # => "Saving up to 10 versions to custom_versions"
@@ -44,15 +44,39 @@
Usable reserves the `:only` and `:method` keys. All other keys in the given hash are defined as config settings. If you really
want to define a config on the target class with one of these names, you can simply define them in the block:
```ruby
-Model.usable VersionMixin, only: [:save_version] do |config|
- config.only = "Will be set on `Model.usable_config.only`"
+Model.usable VersionMixin, only: [:save_version] do
+ only "Will be set on `Model.usables.only` and namespaced under `Model.usables.version_mixin.only`"
end
```
+## Configuring Modules
+
+Configuration settings defined on a "usable" module will be copied to the including class. Usable defines
+a `config` method on extended modules (alias for `usables`) to use for setting default configuration options:
+
+```ruby
+module Mixin
+ extend Usable
+ config.language = :en
+ config do
+ country 'US'
+ state 'Hawaii'
+ spec :census, {
+ population: 1_400_00,
+ daily_visitors: 218_150
+ }
+ end
+end
+
+Model.usable Mixin
+Model.usables[:state] # => 'Hawaii'
+Model.usables.census[:daily_visitors] # => 218150
+```
+
## Confidently calling methods
We should all be writing [confident code](http://www.confidentruby.com/), which is why you might want to call configurable
methods through the `usable_method` class and instance method. Methods passed in with the `:only` option
will _always_ return `nil` when called. Thus, the confidence.
@@ -68,47 +92,9 @@
## Module Naming Conventions
Modules with the following names found within the target module's namespace will be automatically used.
`ClassMethods` - extended onto the target module.
-
-`UsableSpec` - tells usable which methods are configurable via the `:only` option. Any naming conflicts will be resolved by
-giving precedence to the parent module.
-
-For example:
-
-```ruby
-module Mixin
- def name
- "defined by Mixin"
- end
-
- def from_mixin
- "always here"
- end
-
- # @description Usable will apply the :only option to just the methods defined by this module
- module UsableSpec
- def from_spec
- "can be excluded"
- end
-
- def name
- "defined by UsableSpec"
- end
- end
-end
-
-class Example
- extend Usable
- usable Mixin, only: :from_spec
-end
-
-Example.new.from_spec # => "can be excluded"
-Example.new.from_mixin # => "always here"
-Example.new.name # => "defined by Mixin"
-Example.ancestors # => [Example, Mixin, Example::MixinUsableSpecUsed, Object, Kernel, BasicObject] (ruby -v 2.3.0)
-```
## Notes
If the given module is modified by the `:only` option, then Usable will duplicate the module so that it doesn't mutate
it globally. Duplicating a module returns an anonymous module. But anonymous mods in the ancestor list can be confusing.