cushion_defaults 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e4ae7cc718182c777f0867383128216f35841d45
-  data.tar.gz: d7735d85bada9bb54e534fa2eb1ffc4b826711e5
+  metadata.gz: 725ea185c013e34737b4bf5f46e0fa08fff68428
+  data.tar.gz: 8414ae7cce652e15c91e654194c435ebe8aa0ed4
 SHA512:
-  metadata.gz: 179c1e3ad13f662357a1baad18902a11ef2e10e1c8acf19d14ae5e1a18855a10f5daafbab9fdd8b840ca61f916e30b79a1a1d9a39e7f6b689a903e7423675f86
-  data.tar.gz: ffef5ddacf6255e6dc576d9c4e0dbf618396168c9c3a35d207e54515cd886e548683eaae0f6f0514f400172d2ed826910290332bc29990d22be6600072c9e9bd
+  metadata.gz: eaf552d0557b4c07c083fa3db1074f4ddc058b20d8039e35d1f1c772e5f49ce3ba1e1e5a78b92973d7f4565a3ed45ebbbad2f36eee2f2e1a8c2fe3af9bce3f82
+  data.tar.gz: 68c8e99dd1543ae61ba627678eddaf63e962f276b5ffceb2e38eb812ec67dca281afd9f4157cbf7acae57a10d3e114bc49bb98204d7315fdf850ef9869dc7887

data/CHANGELOG.md

@@ -52,4 +52,17 @@
 
 -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.
+    - For more information, see "Proc Cushions" in README.md.
+
+## 0.5.x
+
+-0.5.0
+    - NEW FEATURE: Bang Readers
+        - When called, a bang reader (e.g., +var!+) crystallizes +var+, if not set, to the default value for +var+.
+        - Especially useful for permanently fixing the value of a proc cushion.
+        - Key method: +ClassMethods#bang_the_cushion+
+    - NEW OPTION: bang_things_up
+        - If true, bang readers will automatically be set up every time a cushion_reader is created.
+        - Default: true
+    - Bugfix interaction between procs and #crystallize_defaults
+    - Expand README.md

data/README.md

@@ -22,20 +22,32 @@ I try to keep all of this up-to-date, but the latest information can always be f
 3. Easily allow subclasses to inherit the default values of their ancestor classes or override them with their own default values. CushionDefaults is in this respect more flexible than using either constants or `@@defaults` variables. As an added bonus, changes to the defaults of a superclass cascade down and affect the defaults of subclasses.
 4. Optionally, if you think of your defaults as configuration rather than logic, pull them out of your code and put them in class-specific YAML files that can be automatically loaded in.
 5. Using the YAML technique, you can maintain multiple sets of defaults and load in the appropriate one depending on the environment.
-6. If you follow the common pattern of setting instance variables to the default value (e.g., `@var = params[:var] || default_for_var`), you have no way of distinguishing between when `x@var` is set to the default value because that was actively selected (`params[:var]...`) and when it is set to the default because it otherwise would have been nil (`... || default_for_var`). This is especially important when defaults change occasionally (or even vary regularly!).  CushionDefaults makes this situation easy to handle. Consider the following:
+6. If you follow the common pattern of setting instance variables to the default value (e.g., `@var = params[:var] || default_for_var`), you have no way of distinguishing between when `x@var` is set to the default value because that was actively selected (`params[:var]...`) and when it is set to the default because it otherwise would have been nil (`... || default_for_var`). This is especially important when defaults change occasionally (or even vary regularly!).  CushionDefaults makes this situation easy to handle.
+
+## Give Me a Quick Example
 
 ```ruby
+require 'color'
+
 class Person
   include CushionDefaults
   self.defaults[:favorite_color] = 'blue'
-  cushion :favorite_color
+  self.defaults[:favorite_shade_of_gray] = do |instance|
+      Color::RGB.by_name(instance.favorite_color).to_grayscale.to_rgb
+  end
+  cushion :favorite_color, :favorite_shade_of_gray
 end
 
 ryan, julia = Person.new, Person.new
 ryan.favorite_color = 'blue'
 
+ryan.favorite_shade_of_gray # RGB [#808080], computed from favorite_color == 'blue'
+ryan.favorite_shade_of_gray = Color::RGB.by_name('silver')
+ryan.favorite_shade_of_gray # RGB [#cccccc]
+
 ryan.favorite_color # 'blue'
 ryan.has_specified?(:favorite_color) # true
+
 julia.favorite_color # 'blue'
 julia.has_specified?(:favorite_color) # false
 
@@ -44,7 +56,9 @@ Person.defaults[:favorite_color] = 'green'
 ryan.favorite_color # 'blue'
 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)), fork it, make changes, and make a pull request.
@@ -99,10 +113,12 @@ class Klass
   self.defaults = {first: Klass, second: Klass, third: Klass}
   cushion_defaults
 end
+
 class SubKlass < Klass
   self.defaults += {second: SubKlass, fourth: SubKlass}
   cushion :fourth
 end
+
 class SubSubKlass < SubKlass
   self.defaults[:third] = SubSubKlass
 end
@@ -114,14 +130,14 @@ z.first = 'custom'
 Calling `#first`, `#second`, `#third`, and `#fourth`, then, would produce the following results on x, y, and z:
 
 ```ruby
-puts [x.first, x.second, x.third]
+[x.first, x.second, x.third]
 # [Klass, Klass, Klass]
 # x.fourth would return NoMethodError
 
-puts [y.first, y.second, y.third, y.fourth]
+[y.first, y.second, y.third, y.fourth]
 # [Klass, SubKlass, Klass, SubKlass]
 
-puts [z.first, z.second, z.third, z.fourth]
+[z.first, z.second, z.third, z.fourth]
 # ['custom', SubKlass, SubSubKlass, SubKlass]
 ```
 
@@ -135,7 +151,7 @@ z.second # 'totally new value'
 
 ### Adding and Removing Readers and Writers
 
-Now, if we were to later add a new default to Plant
+Now, if we were to later add a new default to our Plant class from up above
 
 ```ruby
 Plant.defaults[:climate] = 'temperate'
@@ -144,6 +160,7 @@ Plant.defaults[:climate] = 'temperate'
 and ran
 
 ```ruby
+rhododendron = Plant.new
 rhododendron.climate
 ```
 
@@ -209,6 +226,8 @@ update_readers: true
 update_writers: true
 ```
 
+For a complete list of options available (along with explanations), see the docs for CushionDefaults::Configuration, especially the method group "Option Reader/Writers."
+
 ### Proc Cushions
 
 CushionDefaults now supports proc cushions, which offer a powerful new level of flexibility in getting and setting defaults.
@@ -219,38 +238,44 @@ Take the following example:
 
 ```ruby
 class Language
-    attr_accessor :greeting
+    attr_accessor :say_hello
     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' }
+        en: Language.new { |l| l.say_hello = 'Hello' },
+        fr: Language.new { |l| l.say_hello = 'Bonjour' }
     }
 
 class Person
     include CushionDefaults
 
+    attr_accessor :name
+
+    def initialize(&block)
+        yield self if block_given?
+    end
+
     self.defaults[:language] = $languages[:en]
 
-    # By default, return the greeting for the instance's language
+    # By default, return the greeting for the person's language and the person's name
     self.defaults[:greeting] = proc do |instance|
-        instance.language.greeting
+        "#{instance.language.say_hello}, #{instance.name}"
     end
 
     cushion_defaults
 end
 
-john = Person.new
-john.greeting # 'Hello'
+peter = Person.new { |p| p.name = 'Peter' }
+peter.greeting # 'Hello, Peter'
 
-pierre = Person.new
-pierre.greeting # 'Hello', since languages[:en] is the default language
+pierre = Person.new { |p| p.name = 'Pierre' }
+pierre.greeting # 'Hello, Pierre', since languages[:en] is the default language
 
 pierre.language = $languages[:fr]
-pierre.greeting # 'Bonjour', since languages[:fr] is now pierre's greeting
+pierre.greeting # 'Bonjour, Pierre', since languages[:fr] is now pierre's language, and #greeting gets its #say_hello
 
 pierre.greeting = 'Salut!'
 pierre.greeting # 'Salut!', since pierre has a custom greeting
@@ -279,9 +304,32 @@ passerby.when_i_noticed_you # Time.now
 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.
+Alternatively, you can write a normal proc and call the variable's +bang_reader+ if you're worried the variable may not be set.
+
+```ruby
+class Person
+    include CushionDefaults
+
+    self.defaults[:when_i_noticed_you] = proc { Time.now }
+
+    cushion :when_i_noticed_you
+end
+
+passerby = Person.new
+
+# since @when_i_noticed_you is undefined the bang_reader 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 techniques can provide sophisticated means of both setting cushions or defaults while allowing customizable values for particular instances.
 
 ### Freezing and Thawing Defaults
 
@@ -475,6 +523,48 @@ Plant.new.color # 'green'
 
 (Crystallizing defaults should be carefully distinguished from freezing defaults: crystallizing defaults applies to specific instances, whereas freezing defaults applies to the class itself.)
 
+### What About Persistence?
+
+The key rule when using CushionDefaults with any sort of persistence is this: use instance variables, and not `cushion_reader`s, when preparing objects for storage.
+
+If you use `cushion_reader`s when storing your objects, you run the risk of accidentally crystallizing your defaults. Take, for instance, the following (incorrect) code:
+
+```ruby
+class AccidentallyInLove
+    include CushionDefaults
+    self.defaults[:girl_for_me] = proc { %w(Sally Jane Dora Annabel).sample }
+    cushion :girl_for_me
+
+    def marshal_dump
+        # This is the problem: it returns the default for marshaling!
+        [girl_for_me]
+    end
+    def marshal_load array
+        self.girl_for_me = array.first
+    end
+end
+
+marco = AccidentallyInLove.new
+
+# only 0.4% chance these are the same!
+5.times { puts marco.girl_for_me }
+
+marco = Marshal.load(Marshal.dump(marco))
+
+# Marco settled down without realizing it
+5.times { puts marco.girl_for_me }
+```
+
+Assuming your intent in marshaling isn't to crystallize the default and force him to settle down, you can either leave in place the default methods (which work) or overload `marshal_dump` as follows:
+
+```ruby
+def marshal_dump
+    [@girl_for_me]
+end
+```
+
+(Note, however, that any sort of reconstruction of objects is incompatible with setting `Configuration.ignore_attempts_to_set_nil` to false.)
+
 ### Pushy and Polite Defaults
 
 Pushy and polite defaults are an experimental feature. Rough documentation can be found in the docs, and more details will be forthcoming.
@@ -518,4 +608,27 @@ If you have the time, tell me why.
 
 Not a useful concept? Don't like the implementation? Think the default configuration options should be different? Edit [the wiki](https://github.com/posgarou/cushion_defaults/wiki) and let me know.
 
-If you have any specific suggestions for how to make CushionDefaults better, I'd love to hear them.
+If you have any specific suggestions for how to make CushionDefaults better, I'd love to hear them.
+
+## Should I Stay or Should I Go Now?
+
+Ultimately that's your decision. Try it, and see if it works for your use case.  That said, here are some general guidelines from my perspective.
+
+### When *Should* I Use CushionDefaults?
+
+When you need or want...
+
+1. DRY defaults handling.
+2. Flexibility.
+3. A powerful feature set for handling (and overriding) inheritance of defaults.
+4. To know when an instance variable is set to the default and when it is simply not specified.
+5. The ability to manage and maintain multiple sets of defaults (while remaining DRY).
+6. To separate your defaults (configuration) off from your codebase (logic).
+7. To gracefully handle changing defaults.
+8. To ensure that some or all of your defaults *don't* change.
+
+### When *Shouldn't* I Use CushionDefaults?
+
+1. *When speed is absolutely critical.* CushionDefaults is pretty fast (see `benchmarks/simple_benchmark.rb`), since it runs almost entirely on a series of hash lookups. But there's no way it could be as fast as `attr_accessor`: it just does more, and more computations means more time. If you have hundreds of thousands of calculations that you need performed lightning fast, you should look elsewhere.
+2. *When working in a Rails environment.* CushionDefaults may eventually spawn a companion project CushionDefaults-Rails, but for now it's just not the right tool for a Rails job. There are plenty of libraries that would be better for this purpose, e.g., [default_value_for](https://github.com/FooBarWidget/default_value_for).
+3. *When you want to keep your dependencies down.* Some people end up with 150 apps on their phones; others end up with 150 gems in their projects. CushionDefaults itself doesn't depend on any other gems (in production), but that still doesn't mean it's worth the extra overhead to use it in every project.

data/lib/cushion_defaults/class_methods.rb

@@ -86,6 +86,9 @@ module CushionDefaults
     # 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.
     #
+    # Will set up {#bang_reader}s if
+    # {CushionDefaults::Configuration#bang_things_up Configuration#bang_things_up} is true.
+    #
     # 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
@@ -106,7 +109,68 @@ module CushionDefaults
             defaults[sym]
           end
         end
-        CushionDefaults.log("cushion_reader #{sym} established for #{self}")
+        CushionDefaults.log("cushion_reader #{sym_str} established for #{self}")
+      end
+      bang_reader *syms if CushionDefaults.conf.bang_things_up
+    end
+
+    # Identical to {#cushion_reader} with one important exception: after determining the default value, +bang_reader+
+    # goes on to crystallize this default value for the instance.
+    #
+    # This is especially useful with proc cushions, as the below examples make clear.
+    #
+    # Note that this method is equivalent to calling +instance.crystallize_default(:sym)+.
+    #
+    # Note also, finally, that bang_readers can exist and function even if no {#cushion_writer}s are defined.
+    #
+    # @param syms [*#to_sym] instance variables that should have +bang_readers+
+    # @see CushionDefaults::Configuration#bang_things_up Configuration#bang_things_up
+    # @see CushionDefaults::CushionDefaults#crystalize_default CushionDefaults#crystalize_default
+    #
+    # @example Simple Example #1: Flowers for cushion_reader
+    #   class Flower
+    #       include CushionDefaults
+    #       self.defaults[:he_loves_me] = proc { (Time.now.sec % 2).zero? }
+    #       cushion :he_loves_me
+    #   end
+    #
+    #   daisy = Flower.new
+    #
+    #   daisy.he_loves_me  # true
+    #
+    #   # slight delay...
+    #   daisy.he_loves_me  # false
+    #
+    #   # slight delay...
+    #   daisy.he_loves_me! # true
+    #
+    #   5.times { daisy.he_loves_me } # [true, true, true, true, true]
+    #
+    # @example Simple Example #2: Wake Up Little Susie
+    #   class Dreamer
+    #       include CushionDefaults
+    #       self.defaults[:time_awoken] = proc { Time.now }
+    #       cushion :time_awoken
+    #    end
+    #
+    #   little_susie = Dreamer.new
+    #
+    #   little_susie.time_awoken  # returns Time.now, but doesn't set @time_awoken
+    #   little_susie.time_awoken! # sets @time_awoken to Time.now
+    #
+    #   little_susie.time_awoken  # returns the @time_awoken set in the line above
+    #   little_susie.time_awoken! # returns @time_awoken and does not set it to a new value
+    def bang_reader(*syms)
+      syms.each do |sym|
+        sym = sym.to_sym
+        sym_str = "#{sym}!"
+        if self_or_parent_instance_method?(sym)
+          CushionDefaults.log("#{self} or a parent class already has a bang method #{sym_str}", :warn)
+        end
+        define_method(sym_str.to_sym) do
+          crystallize_default(sym)
+        end
+        CushionDefaults.log("bang_reader #{sym_str} established for #{self}")
       end
     end
 
@@ -156,7 +220,7 @@ module CushionDefaults
       end
     end
 
-    # Undefines any reader for sym.
+    # Undefines the reader for sym in this class (if present).
     # @note This method will delete any method of the form +sym+, not just cushion_readers.
     # @param sym [#to_sym] instance variable to delete reader for
     def remove_reader(sym)
@@ -167,7 +231,18 @@ module CushionDefaults
       end
     end
 
-    # Undefines any writer for sym.
+    # Undefines any bang method for sym in this class (if present).
+    # @note This method will delete any method of the form +sym!+, not just bang readers.
+    # @param sym [#to_sym] instance variable to delete bang method for
+    def remove_bang(sym)
+      sym = "sym!".to_sym
+      if self_has_method?(sym)
+        undef_method(sym)
+        CushionDefaults.log("bang reader #{sym} removed from #{self}", :info)
+      end
+    end
+
+    # Undefines any writer for sym in this class (if present).
     # @note This method will delete any method of the format 'sym=', not just cushion_writers.
     # @param sym [#to_sym] instance variable to delete writer for
     def remove_writer(sym)
@@ -178,7 +253,8 @@ module CushionDefaults
       end
     end
 
-    # Sets up both {#cushion_reader}s and {#cushion_writer}s for +syms+.
+    # Sets up both {#cushion_reader}s and {#cushion_writer}s for +syms+. Will set up {#bang_reader}s if
+    # {CushionDefaults::Configuration#bang_things_up Configuration#bang_things_up} is true.
     # @param syms [*#to_sym] Those instance variables that should have {#cushion_reader}s and {#cushion_writer}s.
     def cushion(*syms)
       cushion_reader(*syms)

data/lib/cushion_defaults/configuration.rb

@@ -31,13 +31,17 @@ module CushionDefaults
     #   {#yaml_source_folder}. Def. nil.
     attr_writer :yaml_source_full_path
 
-    # @return [boolean] if true, CushionDefaults makes log entries. Def. true.
-    attr_accessor :record_in_log
-
     # @return [boolean] if true, CushionDefaults will complain (warning level) when it cannot find a YAML configuration
     #   file for a class.  If false, it only posts this message at the debug level.  Def. false.
     attr_accessor :whiny_yaml
 
+    # @return [boolean] if true, all calls to {ClassMethods#cushion_reader}, implicit or explicit, will also call
+    #   {ClassMethods#bang_reader}.
+    attr_accessor :bang_things_up
+
+    # @return [boolean] if true, CushionDefaults makes log entries. Def. true.
+    attr_accessor :record_in_log
+
     # @return [boolean] if true, calls to cushion_writer methods will not set the instance variable if the value passed in
     #   is nil (thus allowing cushion_reader to still return the default value, rather than nil). Def. true.
     # @example Ignored Call to cushion_writer When ignore_attempts_to_set_nil == true
@@ -127,6 +131,7 @@ module CushionDefaults
       self.auto_load_from_yaml = true
       self.yaml_source_folder = 'config/cushion_defaults/'
       self.yaml_source_full_path = nil
+      self.bang_things_up = true
       self.record_in_log = true
       self.logger = Logger.new $stdout
       self.log_lvl = Logger::INFO

data/lib/cushion_defaults/defaults_hash.rb

@@ -232,6 +232,7 @@ module CushionDefaults
     # @see ClassMethods#remove_writer
     def remove_methods_as_needed(key)
       @owner.remove_reader key.to_sym if CushionDefaults.conf.update_readers
+      @owner.remove_bang key.to_sym if CushionDefaults.conf.update_readers
       @owner.remove_writer key.to_sym if CushionDefaults.conf.update_writers
     end
 

data/lib/cushion_defaults.rb

@@ -28,7 +28,7 @@ require 'cushion_defaults/errors'
 module CushionDefaults
 
   # Version constant
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 
   # The path of the first file that +includes+ CushionDefaults.
   CALLING_PATH = File.expand_path(File.dirname($0)) + '/'
@@ -175,7 +175,7 @@ module CushionDefaults
     # acting if a nilish value is specified and the value for :default_key is nilish.
     if !has_specified? default_key || (act_if_nilish && CushionDefaults.nilish?(instance_variable_get("@#{default_key}")))
       default_value = default(default_key)
-      instance_variable_set("@#{default_key}", default_value)
+      instance_variable_set("@#{default_key}", default_value.respond_to?(:call) ? default_value.call(self, default_key) : default_value)
     else
       log("Did not update #{default_key}")
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cushion_defaults
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Ryan Mitchell
@@ -38,9 +38,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.8'
-description: Allows you to specify a 'cushion' for various instance variables—effectively
-  a default value—that will be returned by optional reader methods if the instance
-  variable is undefined.
+description: Cushion your instance variables. Get a default if a variable isn’t defined.
+  DRY off your code.
 email: posgarou@gmail.com
 executables: []
 extensions: []