usable 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 066825f3c1df23a18aed5177540f36a57e163251
-  data.tar.gz: 1d298ec0d9ce23ab4c6850d43cbdb04cd832e591
+  metadata.gz: 8e995dd364713419052b4643dcc4c3fd32ad3f65
+  data.tar.gz: 133be5883cae3533d8bbd483f63afa53aa950b62
 SHA512:
-  metadata.gz: 4056167e5a41c520e054f9c0e66ddee45bf3e336b5fd17b8ab8a29ff80a3a33cd9ff6eb9d79614a37632a184798301513f9b209ed22421741ba0e771374ee91e
-  data.tar.gz: 62438f10155e987c3e1a995ac9ccf9d42d0b7905231ccca4372dc072e26e8d51cfb038bc5066ccdd1c482b5d20255ffc194a473b9ba534ccfeddb2e0a6e6fd02
+  metadata.gz: fa11820e33b0cf6ffdf9eeb83772dd70de4794296e7ca85039e96885d57cdf21edaef12ac7271b906ca7dba666eb2ad0ee531d11fa8ac8e86ed1d12de6d4a70a
+  data.tar.gz: d5c339c6300345698e10b7cac58a827f06caa55e1f683691520de0785738fdba9c592b766a2ed361843b575ee87c734b74ff2729f808ff8af16e3ef6e8b5b499

data/README.md

@@ -1,10 +1,10 @@
 # Usable [![Gem Version](https://badge.fury.io/rb/usable.svg)](http://badge.fury.io/rb/usable)
 
-A simple way to mount and configure your modules. Usable gives you control over which methods are included, and the class
-level config provides a safe interface for calling them.
+A simple way to mount and configure your modules. Usable gives you control over which methods are included, and a simple
+interface to help you call dynamic methods with confidence.
 
 ```ruby
-module VersionKit
+module VersionMixin
   def save_version
     "Saving up to #{self.class.usable_config.max_versions} versions to #{self.class.usable_config.table_name}"
   end
@@ -13,35 +13,38 @@ module VersionKit
     "Deleting versions from #{self.class.usable_config.table_name}"
   end
 end
-  
+
 class Model
   extend Usable
 
-  usable VersionKit, only: :save_version do |config|
+  usable VersionMixin, only: :save_version do |config|
     config.max_versions = 10
     config.table_name = 'custom_versions'
   end
+
+  def save
+    self.class.usable_method(self, :save_version).call
+  end
 end
 
->> Model.usable_config.table_name
-=> "custom_versions"
->> Model.new.save_version
-=> "Saving up to 10 versions to custom_versions"
->> Model.usable_config.available_methods[:save_version].bind(Model.new).call
-=> "Saving up to 10 versions to custom_versions"
->> Model.new.respond_to? :destroy_version     
-=> false
->> Model.usable_config.available_methods[:destroy_version].bind(Model.new).call
-=> nil
+model = Model.new
+model.save_version     # => "Saving up to 10 versions to custom_versions"
+model.destroy_version  # => NoMethodError: undefined method `destroy_version' for #<Model:...
 ```
-What's going on here? Well `#save_versions` is now extended onto the `Model` class, but `#destroy_version` is not!
+You'll notice that `#save_versions` is now included on `Model`, but `#destroy_version` isn't defined.
+
+## Confidently calling methods
+
+We should all be writing [confident code](http://www.confidentruby.com/). That's why it is encouraged
+to reference methods through the `usable_method` class level function. Methods passed in with the `:only` option
+will always return `nil` when called.
 
-## But wait, you undefined my methods?
+Here's the same example as above, rewritten to call methods through the Usable interface:
 
-Yes. Well ... yes, at least on the copy of the module included in the target class. But, checking if an object responds
-to a method all time doesn't produce very [confident code](http://www.confidentruby.com/). That's why it is encouraged
-to reference methods through the `Model.usable_config.available_methods` hash. This way you can confidently call methods,
-just don't rely on the return value, because methods that are removed via `:only` will return `nil`.
+```ruby
+Model.usable_method(model, :save_version).call    # => "Saving up to 10 versions to custom_versions"
+Model.usable_method(model, :destroy_version).call # => nil
+```
 
 ## Separate included module from configurable methods
 
@@ -52,37 +55,41 @@ conflicts will be resolved by giving precedence to the parent module.
 For example:
 
 ```ruby
-module VersionKit
+module Mixin
+  def name
+    "defined by Mixin"
+  end
+
+  def from_mixin
+    "always here"
+  end
+
+  # @description Usable will apply the :only to just the methods defined by this module
   module UsableSpec
-    def version
-      "yo"
+    def from_spec
+      "can be excluded"
     end
-    
+
     def name
-      "nope"
+      "defined by UsableSpec"
     end
   end
-  
-  def name
-    "yup"
-  end
-  
-  def self.included(base)
-    puts base.usable_config.available_methods[:version].bind(self).call
-  end
 end
 
->> Example = Class.new.extend Usable
-=> Example
->> Example.usable VersionKit
-yo
-=> Example
->> Example.new.version
-=> "yo"
->> Example.new.name
-=> "yup"
+class Example
+  extend Usable
+  usable Mixin, only: [:name, :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)
 ```
 
+Noticed that Usable assigns the modified module to a constant with the same name as the given module, but with "Used" appended.
+The main module and the spec were both included, but `Mixin` was not modified, so it didn't need a new name.
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/bin/console

@@ -10,7 +10,7 @@ require "usable"
 # require "pry"
 # Pry.start
 
-module VersionKit
+module VersionMixin
   def save_version
     "Saving up to #{self.class.usable_config.max_versions} versions to #{self.class.usable_config.table_name}"
   end
@@ -20,13 +20,43 @@ module VersionKit
   end
 end
 
+module Mixin
+  def name
+    "defined by Mixin"
+  end
+
+  def from_mixin
+    "always here"
+  end
+
+  # @description Usable will apply the :only 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 Model
   extend Usable
 
-  usable VersionKit, only: :save_version do |config|
+  usable VersionMixin, only: :save_version do |config|
     config.max_versions = 10
     config.table_name = 'custom_versions'
   end
+
+  def save
+    self.class.usable_method(self, :save_version).call
+  end
+end
+
+class Example
+  extend Usable
+  usable Mixin, only: [:name, :from_spec]
 end
 
 require "irb"

data/lib/usable/version.rb

@@ -1,3 +1,3 @@
 module Usable
-  VERSION = "1.1.1".freeze
+  VERSION = "1.2.0".freeze
 end

data/lib/usable.rb

@@ -47,4 +47,9 @@ module Usable
     usable_config.modules << mod
     send :include, mod
   end
+
+  # @return [Method] bound to the given -context-
+  def usable_method(context, method_name)
+    usable_config.available_methods[method_name].bind(context)
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: usable
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Ryan Buckley
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-02-15 00:00:00.000000000 Z
+date: 2016-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler