cushion_defaults 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e7fd6692745ad995ce699917618f66bf08ba58a4
-  data.tar.gz: 8e17dbed0aae4f20cb657ebb2dc1e7113bd9b31c
+  metadata.gz: e4ae7cc718182c777f0867383128216f35841d45
+  data.tar.gz: d7735d85bada9bb54e534fa2eb1ffc4b826711e5
 SHA512:
-  metadata.gz: 7cb89e14bc6fd047ee279443012fe41c103699e5ad6e87ee8c8bf4d1c8e49e671e88cbc03624eb4122dd846b4a508891365cdeeeca3dbb1b96997aec92973b43
-  data.tar.gz: 68740c0fdb797b9b32dddeaf470f72530b8216ac188edaa7b7da406ed1dbee283990bb24a3dff1d8e66e554e1f13fbc921f95f502278178e56ebce47b27453fb
+  metadata.gz: 179c1e3ad13f662357a1baad18902a11ef2e10e1c8acf19d14ae5e1a18855a10f5daafbab9fdd8b840ca61f916e30b79a1a1d9a39e7f6b689a903e7423675f86
+  data.tar.gz: ffef5ddacf6255e6dc576d9c4e0dbf618396168c9c3a35d207e54515cd886e548683eaae0f6f0514f400172d2ed826910290332bc29990d22be6600072c9e9bd

data/CHANGELOG.md

@@ -46,4 +46,10 @@
         - ClassMethods#freeze_default
         - ClassMethods#deep_freeze_default
         - ClassMethods#thaw_default
-- 0.3.1: Bugfix to #freeze_defaults, #deep_freeze_defaults, and #thaw_defaults
+- 0.3.1: Bugfix to #freeze_defaults, #deep_freeze_defaults, and #thaw_defaults
+
+## 0.4.x
+
+-0.4.0 - NEW FEATURE: Proc Cushions
+    - You can now set a default to a proc that will be evaluated whenever an instance variable is absent.
+    - For more information, see "Proc Cushions" in README.md.

data/README.md

@@ -47,9 +47,12 @@ julia.favorite_color # 'green'
 ## How Do I Get It?
 `gem install 'cushion_defaults'` if you just want the gem.
 
-If you want to help out the project or edit the source code, clone the repository (hosted at [GitHub](https://github.com/posgarou/cushion_defaults)).
+If you want to help out the project or edit the source code, clone the repository (hosted at [GitHub](https://github.com/posgarou/cushion_defaults)), fork it, make changes, and make a pull request.
+
 ## Give Me the Rundown
+
 ### The Basics
+
 Setting up a DefaultsHash, populating it, and setting up `cushion_reader`s and `cushion_writer`s is a simple process.
 
 ```ruby
@@ -206,6 +209,80 @@ update_readers: true
 update_writers: true
 ```
 
+### Proc Cushions
+
+CushionDefaults now supports proc cushions, which offer a powerful new level of flexibility in getting and setting defaults.
+
+If a default is set to a Proc, then cushion_readers will yield both an instance variable and a symbol representing the instance variable queried.  (Since it's a proc, though, we do not need to worry about everything passed in.)
+
+Take the following example:
+
+```ruby
+class Language
+    attr_accessor :greeting
+    def initialize(&block)
+        yield self if block_given?
+    end
+end
+
+$languages = {
+        en: Language.new { |l| l.greeting = 'Hello' },
+        fr: Language.new { |l| l.greeting = 'Bonjour' }
+    }
+
+class Person
+    include CushionDefaults
+
+    self.defaults[:language] = $languages[:en]
+
+    # By default, return the greeting for the instance's language
+    self.defaults[:greeting] = proc do |instance|
+        instance.language.greeting
+    end
+
+    cushion_defaults
+end
+
+john = Person.new
+john.greeting # 'Hello'
+
+pierre = Person.new
+pierre.greeting # 'Hello', since languages[:en] is the default language
+
+pierre.language = $languages[:fr]
+pierre.greeting # 'Bonjour', since languages[:fr] is now pierre's greeting
+
+pierre.greeting = 'Salut!'
+pierre.greeting # 'Salut!', since pierre has a custom greeting
+
+```
+
+It is also possible to combine this technique with calls to writer methods to produce a lazily-evaluated instance variable.
+
+```ruby
+class Person
+    include CushionDefaults
+
+    self.defaults[:when_i_noticed_you] = proc do |instance|
+        instance.when_i_noticed_you = Time.now
+    end
+
+    cushion :when_i_noticed_you
+end
+
+passerby = Person.new
+
+# since @when_i_noticed_you is undefined, above proc sets it to Time.now
+passerby.when_i_noticed_you # Time.now
+
+# wait a sec
+sleep(1.0)
+
+passerby.when_i_noticed_you == Time.now # false—1 sec later
+```
+
+These two techniques can provide sophisticated means of both setting cushions or defaults while allowing customizable values for particular instances.
+
 ### Freezing and Thawing Defaults
 
 You may wish to prevent a default from further modification, either permanently or temporarily. This can prevent silly mistakes that are otherwise difficult to track down. CushionDefaults makes this possible via a freezing and thawing API.  The key methods here are `#freeze_default` and `#thaw_default`.
@@ -260,7 +337,7 @@ By default, CushionDefaults checks for YAML files for each class but does not co
 
 CushionDefaults looks for these YAML files at `config/cushion_defaults/class_name.yaml`. For class Klass, then, it would expect a config file at `config/cushion_defaults/klass.yaml`. Classes in a namespace are expected to have their YAML files in a folder named after their namespace, e.g. Modjewel::Klass in `config/cushion_defaults/modjewel/klass.yaml`.
 
-These YAML files are completely unremarkable in form. Note that all defaults should be specified at root (not in `defaults:`, and currently only simple types are processed.  For the above Chair class, we could place the defaults in a YAML class file like the following:
+These YAML files are completely unremarkable in form. Note that all defaults should be specified at root (not in `defaults:`), and currently only simple types are processed.  For the above Chair class, we could place the defaults in a YAML class file like the following:
 
 ```yaml
 # config/cushion_defaults/chair.yaml

data/lib/cushion_defaults/class_methods.rb

@@ -83,6 +83,9 @@ module CushionDefaults
     # The only exception to this rule is when we have pushy defaults. If a default is pushy, we return it regardless of
     # what this object's instance variable may or may not be.
     #
+    # Note that if the default responds to :call (a proc, e.g.), then the default is instead called with the instance
+    # variable and the symbolic representation of the default requested. This allows for proc cushions.
+    #
     # The readers are named according to the same format as +attr_reader+.
     # @param syms [*#to_sym] instance variables that should have +cushion_readers+
     # @see Configuration#update_readers
@@ -97,6 +100,8 @@ module CushionDefaults
         define_method(sym) do
           if instance_variable_defined?(instance_variable_string) && (CushionDefaults.conf.no_pushies? || defaults.not_pushy?(sym))
             instance_variable_get(instance_variable_string)
+          elsif defaults[sym].respond_to? :call
+            defaults[sym].call(self, sym)
           else
             defaults[sym]
           end

data/lib/cushion_defaults.rb

@@ -28,7 +28,7 @@ require 'cushion_defaults/errors'
 module CushionDefaults
 
   # Version constant
-  VERSION = '0.3.1'
+  VERSION = '0.4.0'
 
   # The path of the first file that +includes+ CushionDefaults.
   CALLING_PATH = File.expand_path(File.dirname($0)) + '/'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cushion_defaults
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Ryan Mitchell
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-12-09 00:00:00.000000000 Z
+date: 2014-12-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec