cushion_defaults 0.5.1 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: eb9a0010fb2ee9d019f6fc9552354d422289810f
-  data.tar.gz: e34bed7551afc9746f0195766b50d2d17c02f8f5
+  metadata.gz: bca05c80623f43fc5f8d61f016ffb6ee18f832cb
+  data.tar.gz: daa36bc9f2da343a5e4699bd42e6c415da8e80cf
 SHA512:
-  metadata.gz: a7cfe9bf2ef8919910408925c54ab14ae43b4efe50ebe3212a0e90fd850af8d6d94523d8b512d9093ea5905654d708ccb59ed44e57a3d69cf9c0fab67b84bee7
-  data.tar.gz: f6701c502a954b8c3a266366135377119c515053e8342d36ebc124fe503169a40795982b2a07069a0b002d85538713d52ad1848c0ffd784702c9b4c1aabbbbeb
+  metadata.gz: 46c86103b998e49862173cc1456e1c14b6615426e9c1816ac50fa9e964b8386c3b13e27fb403cd597cfd2b65df6e6fbdb7bb556e86de0473ca2a91f7ba172cb5
+  data.tar.gz: 8b149e6f6e9d07047c9768348263ebd90acd1ad7242d2bd3368157accadb26e709ec4c5bf9e5daaf8e9c28df6a4c27a0e73f4856a3210668a45cc35890266f89

data/CHANGELOG.md

@@ -1,74 +1,88 @@
 # CHANGELOG
 
-## 0.0.x
+## 0.5.x
 
-- 0.0.0: Initial version.
-- 0.0.1
-    - Include MIT License.
-    - Specify GitHub homepage.
-- 0.0.2
-    - Improve `cushion_reader` speed by approx. 15%.
-    - Specify Ruby version >= 2.0.0.
-- 0.0.3
-    - Fix various bugs related to YAML config loading.
-    - Improve examples.
+- 0.5.2: PERFORMANCE
+    - Another 40% shaved off `cushion_reader` execution times. (In total, execution speed is ~180% faster than v. 0.0.0.)
+    - Between roughly 18% and 75% shaved off `cushion_writer` (depending on input).
 
-## 0.1.x
+- 0.5.1
+    - DEPENDENCY: Support now added for Ruby >= 1.9.3
+    - CONFIGURATION: Default log level now WARN (was INFO)
+    - BUGFIX: Remove unnecessary warning on adding `bang_readers`
+    - PERFORMANCE: Moderate performance gains (approx. 20%) on `cushion_reader`
 
-- 0.1.0
-    - NEW FEATURE: Logging
-        - Add `config.record_in_log` (boolean), `config.log_lvl (int)`, and `config.logger` (Logger or similar) options.
-        - Add logging throughout the module at various levels.
-        - Logging enabled by default at info level.
-    - Improve performance of `cushion_reader` by approx. 115%.
-- 0.1.1
-    - Greatly improve and expand documentation.
-    - Switch from rdoc to Yard
+- 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_reader`
+    - NEW OPTION: bang_things_up
+        - If true, bang readers will automatically be set up every time a cushion_reader is created.
+        - Default: true
+    - BUGFIX: fix interaction between procs and #crystallize_defaults
+    - DOCUMENTATION: Expand README.md
+
+## 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.
+
+## 0.3.x
+
+- 0.3.1: BUGFIX: Corrected fatal error in #freeze_defaults, #deep_freeze_defaults, and #thaw_defaults
+
+- 0.3.0 - NEW FEATURE: 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 now makes this possible via a freezing and thawing API.
+    - For more information, see especially:
+        - ClassMethods#freeze_default
+        - ClassMethods#deep_freeze_default
+        - ClassMethods#thaw_default
 
 ## 0.2.x
 
 - 0.2.0
     - Place Configuration within the CushionDefaults module.
+
     - IMPROVEMENT: `cushion_defaults.gemspec`
         - Clarify and expand `cushion_defaults.gemspec`. Was insufficient before.
         - Now specifies development dependencies.
         - Add Gemfile for bundler
+
     - IMPROVEMENT: Testing
         - `test/` renamed to `spec/`
         - Add `.rspec` and `spec/spec_helper.rb`
+
     - DOCUMENTATION: Numerous expansions
 
-## 0.3.x
+## 0.1.x
 
-- 0.3.0 - NEW FEATURE: 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 now makes this possible via a freezing and thawing API.
-    - For more information, see especially:
-        - ClassMethods#freeze_default
-        - ClassMethods#deep_freeze_default
-        - ClassMethods#thaw_default
-- 0.3.1: BUGFIX: Corrected fatal error in #freeze_defaults, #deep_freeze_defaults, and #thaw_defaults
+- 0.1.1
+    - Greatly improve and expand documentation.
+    - Switch from rdoc to Yard
 
-## 0.4.x
+- 0.1.0
+    - NEW FEATURE: Logging
+        - Add `config.record_in_log` (boolean), `config.log_lvl (int)`, and `config.logger` (Logger or similar) options.
+        - Add logging throughout the module at various levels.
+        - Logging enabled by default at info level.
 
--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.
+    - Improve performance of `cushion_reader` by approx. 115%.
 
-## 0.5.x
+## 0.0.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: fix interaction between procs and #crystallize_defaults
-    - DOCUMENTATION: Expand README.md
+- 0.0.3
+    - Fix various bugs related to YAML config loading.
+    - Improve examples.
 
--0.5.1
-    - DEPENDENCY: Support now added for Ruby >= 1.9.3
-    - CONFIGURATION: Default log level now WARN (was INFO)
-    - BUGFIX: Remove unnecessary warning on adding +bang_readers+
-    - PERFORMANCE: Moderate performance gains (approx. 20%) on +cushion_reader+
+- 0.0.2
+    - Improve `cushion_reader` speed by approx. 15%.
+    - Specify Ruby version >= 2.0.0.
+
+- 0.0.1
+    - Include MIT License.
+    - Specify GitHub homepage.
+
+
+- 0.0.0: Initial version.

data/README.md

@@ -27,32 +27,50 @@ I try to keep all of this up-to-date, but the latest information can always be f
 ## Give Me a Quick Example
 
 ```ruby
+require 'cushion_defaults' # This will be assumed henceforth.
 require 'color'
 
 class Person
   include CushionDefaults
+
+  # Set the cushion or default value for @favorite_color to the static value 'blue'
   self.defaults[:favorite_color] = 'blue'
-  self.defaults[:favorite_shade_of_gray] = do |instance|
+
+  # Set the cushion for @favorite_shade_of_gray to the following proc.
+  # As long as @favorite_shade_of_gray is not set, this proc will be evaluated at each call to #favorite_shade_of_gray.
+  # If we wanted to fix or crystallize the value, we could call the bang version #favorite_shade_of_gray!
+  self.defaults[:favorite_shade_of_gray] = proc do |instance|
       Color::RGB.by_name(instance.favorite_color).to_grayscale.to_rgb
   end
+
+  # #cushion sets up a cushion_reader and cushion_writer for each of the symbols passed in
   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')
+# This value is computed by the proc cushion defined above, since ryan's @favorite_shade_of_gray isn't defined
+ryan.favorite_shade_of_gray # RGB [#808080]
+
+ryan.favorite_shade_of_gray = Color::RGB.by_name('silver') # RGB [#cccccc]
+
+# Since ryan's @favorite_shade_of_gray is defined now, the proc isn't called
 ryan.favorite_shade_of_gray # RGB [#cccccc]
 
 ryan.favorite_color # 'blue'
 ryan.has_specified?(:favorite_color) # true
 
 julia.favorite_color # 'blue'
+
+# When we call julia.favorite_color, we're only getting the default color
 julia.has_specified?(:favorite_color) # false
 
+# Now we set the default value for @favorite_color to a new value.
 Person.defaults[:favorite_color] = 'green'
 
+# ryan has a custom favorite color, so it doesn't affect him, but julia returns 'green' now
 ryan.favorite_color # 'blue'
 julia.favorite_color # 'green'
 ```

data/lib/cushion_defaults/class_methods.rb

@@ -2,15 +2,15 @@ module CushionDefaults
   # A series of class methods to be plopped into any class that includes CushionDefaults.
   module ClassMethods
 
-    # Reader for the +defaults+ +DefaultsHash+.
+    # Reader for the @defaults@ @DefaultsHash@.
     attr_reader :defaults
 
     # @!attribute [w] defaults
-    # Wipe @defaults and replace it with the keys/vals of +replacement_hash+.
+    # Wipe @defaults and replace it with the keys/vals of @replacement_hash@.
     #
     # If you only want to add one or more defaults, then write instead self.defaults += {new_key: val}.
     #
-    # Note that all keys are coerced into +Symbols+.
+    # Note that all keys are coerced into @Symbols@.
     def defaults=(replacement_hash)
       # Need to copy over keys/vals to ensure @defaults remains a DefaultsHash and retains identity
 
@@ -24,9 +24,9 @@ module CushionDefaults
       end
     end
 
-    # Equivalent to +@defaults[key] = val+
+    # Equivalent to @@defaults[key] = val@
     # @param key [#to_sym] key for new default.
-    # @param val [Object] Default value for +key+.
+    # @param val [Object] Default value for @key@.
     def set_default(key, val)
       @defaults[key.to_sym] = val
     end
@@ -34,14 +34,14 @@ module CushionDefaults
     # @!group Mass Default Setting Methods
 
     # Load in the defaults for this class from a YAML file.
-    # If +file_name+ is specified, this YAML file is loaded. Otherwise, {Configuration#yaml_file_for} is evaluated for
-    # the current class. By default, the yaml file for +Klass+ is expected to be at +config/cushion_defaults/klass.yaml+.
+    # If @file_name@ is specified, this YAML file is loaded. Otherwise, {Configuration#yaml_file_for} is evaluated for
+    # the current class. By default, the yaml file for @Klass@ is expected to be at @config/cushion_defaults/klass.yaml@.
     # @param file_name [String] name of the YAML file to be loaded in for this class
     # @see Configuration#auto_load_from_yaml
     # @see Configuration#whiny_yaml
     def defaults_from_yaml(file_name = nil)
       if file_name
-        yaml_path = "#{CushionDefaults::configuration.yaml_source_full_path}#{file_name}.yaml"
+        yaml_path = "#{CushionDefaults.conf.yaml_source_full_path}#{file_name}.yaml"
       else
         yaml_path = CushionDefaults.conf.yaml_file_for(self)
       end
@@ -75,7 +75,7 @@ module CushionDefaults
 
     # @!group Reader/Writer
 
-    # Sets up a cushion_reader for each :sym in +syms+.
+    # Sets up a cushion_reader for each :sym in @syms@.
     #
     # Each reader method checks if its instance variable (:sym) is defined.  If it is, it returns that.  If not, it
     # returns the default value.
@@ -89,8 +89,8 @@ module CushionDefaults
     # 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+
+    # 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
     def cushion_reader(*syms)
       syms.each do |sym|
@@ -98,14 +98,14 @@ module CushionDefaults
         if self_or_parent_instance_method?(sym)
           CushionDefaults.log("#{self} or a parent class already has what looks like a getter method for #{sym_str}", :warn)
         end
-        instance_variable_string = "@#{sym}"
+        instance_variable_sym = "@#{sym}".to_sym
 
         # significant performance gains from using this rather than #defaults in method below
         defaults_cache = @defaults
 
         define_method(sym) do
-          if instance_variable_defined?(instance_variable_string) && (CushionDefaults.conf.no_pushies? || defaults_cache.not_pushy?(sym))
-            instance_variable_get(instance_variable_string)
+          if instance_variable_defined?(instance_variable_sym) && (CushionDefaults.conf.no_pushies? || defaults_cache.not_pushy?(sym))
+            instance_variable_get(instance_variable_sym)
           else
             # much faster to save as var
             da_default = defaults_cache[sym]
@@ -117,16 +117,16 @@ module CushionDefaults
       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+
+    # 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 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+
+    # @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
     #
@@ -177,7 +177,7 @@ module CushionDefaults
       end
     end
 
-    # Sets up a cushion_writer for each :sym in +syms+.
+    # Sets up a cushion_writer for each :sym in @syms@.
     #
     # Each writer method carries out one of several checks.
     #
@@ -191,20 +191,20 @@ module CushionDefaults
     #
     # Finally, assuming it was not flagged as nilish, the variable is set to the new value.
     #
-    # The writers are named according to the same format as +attr_writer+.
-    # @param syms [*#to_sym] instance variables that should have +cushion_writers+
+    # The writers are named according to the same format as @attr_writer@.
+    # @param syms [*#to_sym] instance variables that should have @cushion_writers@
     # @see Configuration#update_writers
     # @see Configuration#ignore_attempts_to_set_nil
     # @see Configuration#blank_str_is_nil
     # @see Configuration#whiny_ignores
     def cushion_writer(*syms)
       syms.each do |sym|
-        method_name = "#{sym}="
+        method_name = "#{sym}=".to_sym
         if self_or_parent_instance_method?(method_name)
           CushionDefaults.log("#{self} or a parent class already has what looks like a setter method for #{sym}", :warn)
         end
 
-        instance_variable_string = "@#{sym}"
+        instance_variable_sym = "@#{sym}".to_sym
 
         defaults_cache = @defaults
 
@@ -213,12 +213,11 @@ module CushionDefaults
             if CushionDefaults.conf.whiny_ignores
               CushionDefaults.log("You are attempting to set a nilish value for #{sym}. This will not be recorded, and any value set will be deleted.", :warn)
             end
-            remove_instance_variable(instance_variable_string) if instance_variable_defined?(instance_variable_string)
           else
             if CushionDefaults.conf.we_have_a_pushy? && defaults_cache.pushy?(sym)
               CushionDefaults.log("You are setting a value for #{sym}, but this is a pushy default and this value will not be returned by any cushion_readers.", :warn)
             end
-            instance_variable_set(instance_variable_string, y)
+            instance_variable_set(instance_variable_sym, y)
           end
         end
         CushionDefaults.log("cushion_writer #{sym}= established for #{self}")
@@ -226,7 +225,7 @@ module CushionDefaults
     end
 
     # 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.
+    # @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)
       sym = sym.to_sym
@@ -237,7 +236,7 @@ module CushionDefaults
     end
 
     # 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.
+    # @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
@@ -258,7 +257,7 @@ module CushionDefaults
       end
     end
 
-    # Sets up both {#cushion_reader}s and {#cushion_writer}s for +syms+. Will set up {#bang_reader}s if
+    # 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)
@@ -267,24 +266,24 @@ module CushionDefaults
       cushion_writer(*syms)
     end
 
-    # Defines {#cushion_reader}s for all of this class' +defaults+.
+    # Defines {#cushion_reader}s for all of this class' @defaults@.
     #
-    # Only defines +cushion_readers+ for defaults specified for this class. All other readers are assumed to have been defined
+    # Only defines @cushion_readers@ for defaults specified for this class. All other readers are assumed to have been defined
     # further up the class tree.
     #
-    # Thus, if class +A+ defines the default +var1+, and class +B+ defines the default +var2+, calling this method
-    # within class +B+ will only generate a reader for +var2+.
+    # Thus, if class @A@ defines the default @var1@, and class @B@ defines the default @var2@, calling this method
+    # within class @B@ will only generate a reader for @var2@.
     def cushion_readers_for_defaults
       cushion_reader *defaults.keys
     end
 
-    # Defines {#cushion_reader}s and {#cushion_writer}s for all of this class' +defaults+.
+    # Defines {#cushion_reader}s and {#cushion_writer}s for all of this class' @defaults@.
     #
-    # Only defines +cushion_readers+ and +cushion_writers+ for this class defaults. All other getters are assumed to
+    # Only defines @cushion_readers@ and @cushion_writers@ for this class defaults. All other getters are assumed to
     # have been defined further up the class tree.
     #
-    # Thus, if class +A+ defines the default +var1+, and class +B+ defines the default +var2+, calling this method
-    # within class +B+ will only generate a getter for +var2+.
+    # Thus, if class @A@ defines the default @var1@, and class @B@ defines the default @var2@, calling this method
+    # within class @B@ will only generate a getter for @var2@.
     #
     # See also:
     # - #cushion
@@ -324,12 +323,12 @@ module CushionDefaults
       freeze_default *defaults.keys
     end
 
-    # In addition to preventing the +default[:sym]+ from being set to a new value (see {#freeze_default}), also freezes
-    # the value to which +default[:sym]+ is currently set.
+    # In addition to preventing the @default[:sym]@ from being set to a new value (see {#freeze_default}), also freezes
+    # the value to which @default[:sym]@ is currently set.
     #
     # Does not throw an error when you attempt to freeze an already-frozen default, but it does log at warning level.
     #
-    # Equivalent to calling: +freeze_default :sym; defaults[:sym].freeze+
+    # Equivalent to calling: @freeze_default :sym; defaults[:sym].freeze@
     #
     # @api freeze
     def deep_freeze_default(*syms)
@@ -349,9 +348,9 @@ module CushionDefaults
 
     # Thaws a frozen default, allowing it to be set to a new value.
     #
-    # Note that if the value of the +default[:sym]+ is itself frozen (using {#deep_freeze_default} or +Object#freeze+),
-    # thaw_default allows you to set +default[:sym]+ to a *new* value but does not and cannot allow you to modify the
-    # value to which +default[:sym]+ points until and unless +default[:sym]+ is set to a new value.
+    # Note that if the value of the @default[:sym]@ is itself frozen (using {#deep_freeze_default} or @Object#freeze@),
+    # thaw_default allows you to set @default[:sym]@ to a *new* value but does not and cannot allow you to modify the
+    # value to which @default[:sym]@ points until and unless @default[:sym]@ is set to a new value.
     #
     # Does not throw an error when you attempt to thaw a non-frozen default, but it does log at warning level.
     #
@@ -390,10 +389,10 @@ module CushionDefaults
 
     # @!endgroup
 
-    # Ensure that if class +Klass+ includes +CushionDefaults+, then any class that subclasses +Klass+ will include it as
+    # Ensure that if class @Klass@ includes @CushionDefaults@, then any class that subclasses @Klass@ will include it as
     # well.
     #
-    # Called automatically whenever any class that includes +CushionDefaults+ is inherited.
+    # Called automatically whenever any class that includes @CushionDefaults@ is inherited.
     # @api private
     def inherited(inheritor)
       inheritor.send :include, CushionDefaults
@@ -401,13 +400,13 @@ module CushionDefaults
 
     protected
 
-    # Check whether this class or any parent class includes the instance method denoted by +sym+
+    # Check whether this class or any parent class includes the instance method denoted by @sym@
     # @param sym [#to_sym] method in question
     def self_or_parent_instance_method?(sym)
       instance_methods(true).include?(sym.to_sym)
     end
 
-    # Check whether this class includes the instance method denoted by +sym+
+    # Check whether this class includes the instance method denoted by @sym@
     # @param sym [#to_sym] method in question
     def self_has_method?(sym)
       instance_methods(false).include?(sym.to_sym)

data/lib/cushion_defaults/configuration.rb

@@ -1,9 +1,9 @@
 require 'logger'
 
 module CushionDefaults
-  # Effectively a singleton class, +Configuration+ keeps track of various configuration options for +CushionDefaults+.
+  # Effectively a singleton class, @Configuration@ keeps track of various configuration options for @CushionDefaults@.
   #
-  # In addition, it also keeps track of certain state data for +CushionDefaults+.
+  # In addition, it also keeps track of certain state data for @CushionDefaults@.
   #
   # For configuration options, see the attribute writers.
   #
@@ -96,7 +96,7 @@ module CushionDefaults
     # Returns or computes the folder where class-specific yaml files are expected to reside.
     # @return [String] path to yaml config files.
     def yaml_source_full_path
-      @yaml_source_full_path || CushionDefaults::CALLING_PATH + yaml_source_folder
+      @yaml_source_full_path || "#{CushionDefaults::CALLING_PATH}#{yaml_source_folder}"
     end
 
     # @!endgroup
@@ -107,7 +107,7 @@ module CushionDefaults
       @we_have_a_pushy = false
     end
 
-    # Update configuration options with those values contained within +loaded_config+.
+    # Update configuration options with those values contained within @loaded_config@.
     #
     # @param loaded_config [Hash] hash of config options and settings
     def from_hash(loaded_config)
@@ -166,7 +166,7 @@ module CushionDefaults
     # @param klass [Class] class in question.
     # @return [String] expected path to the YAML file
     def yaml_file_for(klass)
-      "#{CushionDefaults::configuration.yaml_source_full_path}#{underscore(klass.to_s)+'.yaml'}"
+      "#{CushionDefaults::configuration.yaml_source_full_path}#{underscore(klass.to_s)}.yaml}"
     end
 
 
@@ -207,7 +207,7 @@ module CushionDefaults
 
     protected
 
-    # Specifies the formatter for logger. Will not be called if a logger is assigned with +should_assign_formatter+ set to
+    # Specifies the formatter for logger. Will not be called if a logger is assigned with @should_assign_formatter@ set to
     # false.
     def assign_formatter_to_logger
       logger.formatter = proc do |severity, _time, progname, msg|

data/lib/cushion_defaults/defaults_hash.rb

@@ -1,16 +1,16 @@
 module CushionDefaults
-  # Slight expansion of +Hash+.
+  # Slight expansion of @Hash@.
   #
-  # Records a link to +owner+ and will traverse up the chain of owners looking for a default value for +x+ if no default
-  # value for +x+ is specified.
+  # Records a link to @owner@ and will traverse up the chain of owners looking for a default value for @x@ if no default
+  # value for @x@ is specified.
   #
   # In general, a program should treat this class like a normal Hash, with two salient differences:
   # - The {DefaultsHash#+} method has been overridden.
   # - The {DefaultsHash#has_ish_key?}, which returns true if this or a parent has the key specified.
   class DefaultsHash < Hash
-    # +default_proc+ does most of the work.
+    # @default_proc@ does most of the work.
 
-    # Must be initialized with an +owner+ class.
+    # Must be initialized with an @owner@ class.
 
     # Set of defaults marked as pushy.
     attr_reader :pushy_defaults
@@ -22,7 +22,7 @@ module CushionDefaults
     # @param owner [Class] class for which this DefaultsHash holds the defaults.
     def initialize(owner)
       self.default_proc = proc { |_hash, key| super_defaults[key] }
-      # look in the superclass' +defaults+ hash, if a key is not found in this class' +defaults+ hash
+      # look in the superclass' @defaults@ hash, if a key is not found in this class' @defaults@ hash
       @owner = owner
       @pushy_defaults = Set.new
       @polite_defaults = Set.new
@@ -35,7 +35,7 @@ module CushionDefaults
     #
     # Note that this also enables +=.
     #
-    # If +key+ is in +self+ and +y+, then the value of +y+ will replace that in +self+ in the resulting +Hash+.
+    # If @key@ is in @self@ and @y@, then the value of @y@ will replace that in @self@ in the resulting @Hash@.
     #
     # @note This method was incorrectly programmed to modify self in place. In a future release, this will be changed,
     #   and the current behavior should not be depended upon.
@@ -97,16 +97,16 @@ module CushionDefaults
       CushionDefaults.log("All defaults cleared for #{@owner}.", :info)
     end
 
-    # Determine if this +DefaultsHash+ "ish" has a key.  In other words, whether it or any Hashes up the chain of
-    # +super_defaults+ has the key +key+.
+    # Determine if this @DefaultsHash@ "ish" has a key.  In other words, whether it or any Hashes up the chain of
+    # @super_defaults@ has the key @key@.
     #
     # @see #ish_keys
     def has_ish_key?(key)
-      # Obviously, this method gives much better performance than calling +ish_keys.include?(key)+.
+      # Obviously, this method gives much better performance than calling @ish_keys.include?(key)@.
       if has_key?(key)
         true
-      elsif !super_defaults.empty?
-        # super_defaults could theoretically be either a DefaultsHash or a regular Hash
+      # super_defaults could theoretically be either a DefaultsHash or a regular Hash
+      elsif super_defaults
         if super_defaults.respond_to? :has_ish_key?
           super_defaults.has_ish_key?(key)
         else
@@ -117,7 +117,7 @@ module CushionDefaults
       end
     end
 
-    # Returns the keys of this class' +defaults+ as well as those of parent classes (if extant).
+    # Returns the keys of this class' @defaults@ as well as those of parent classes (if extant).
     #
     # @see #has_ish_key?
     def ish_keys
@@ -238,7 +238,7 @@ module CushionDefaults
 
     protected
 
-    # Return (unless cached) a reference to the superclass' +defaults+ hash.
+    # Return (unless cached) a reference to the superclass' @defaults@ hash.
     def super_defaults
       @super_defaults ||= @owner.superclass.respond_to?(:defaults) ? @owner.superclass.defaults : {}
     end

data/lib/cushion_defaults.rb

@@ -5,19 +5,22 @@ require 'cushion_defaults/class_methods'
 require 'cushion_defaults/defaults_hash'
 require 'cushion_defaults/errors'
 
-# Base module. Should be included in any class that needs the functionality offered by CushionDefaults. For a basic
-# introduction, you are strongly encouraged to consult the {file:README.md readme}.
+# h2. The Basics
 #
-# There are also several short example programs in the +examples/+ folder. (If anyone has any more examples to include,
+# Base module. Should be included in any class that needs the functionality offered by CushionDefaults.
+#
+# For a detailed introduction, you are strongly encouraged to consult the "README":file.readme.html.
+#
+# There are also several short example programs in the @examples/@ folder. (If anyone has any more examples to include,
 # please pass them along!)
 #
 # And if you would like to run a very simple benchmark of how CushionDefaults compares to similar methods, run
-# +benchmarks/simple_benchmark.rb+.
+# @benchmarks/simple_benchmark.rb@.
 #
-# == Automatic Inclusion in Child Classes
+# h2. Automatic Inclusion in Child Classes
 #
-# NB: When included in a superclass +Klass+, it automatically includes itself in all subclassses that subsequently
-# subclass +Klass+.
+# When included in a superclass @Klass@, CushionDefaults automatically includes itself in all subclassses that subsequently
+# subclass @Klass@.
 # @example Inclusion in Child Class
 #   class Klass
 #     include CushionDefaults
@@ -28,26 +31,29 @@ require 'cushion_defaults/errors'
 module CushionDefaults
 
   # Version constant
-  VERSION = '0.5.1'
+  VERSION = '0.5.2'
 
-  # The path of the first file that +includes+ CushionDefaults.
+  # The path of the first file that includes CushionDefaults.
   CALLING_PATH = File.expand_path(File.dirname($0)) + '/'
 
   # Location CushionDefaults looks here for an (optional) config file, as well as off of the {CALLING_PATH}.
-  CONFIG_LOCATION = CALLING_PATH + 'config/cushion_defaults.yaml'
+  CONFIG_LOCATION = "#{CALLING_PATH}config/cushion_defaults.yaml"
+
+  # Establish our configuration object
+  @conf = Configuration.new
 
-  # Create or return a cached (effectively singleton) {Configuration} object.
+  # Return CushionDefaults' {Configuration} object.
   # @return [Configuration] the module's configuration object
   # @see Configuration
-  def self.configuration
-    @configuration ||= Configuration.new
+  def self.conf
+    @conf
   end
 
-  # Create or return a cached (effectively singleton) {Configuration} object. Alias for {self.configuration}.
+  # Return CushionDefaults' {Configuration} object.
   # @return [Configuration] the module's configuration object
   # @see Configuration
-  def self.conf
-    self.configuration
+  def self.configuration
+    @conf
   end
 
   # Logs a message to the logger at {Configuration#logger} as long as {Configuration#record_in_log} is true.
@@ -56,44 +62,42 @@ module CushionDefaults
   #   :warn, :error, :fatal, :unknown
   # @param caller_method_name [String] name of the method whose actions are being logged. If nil, the name is determined
   #   programmatically.
-  def self.log(str, level=:debug, caller_method_name=nil)
+  def self.log(str, level=:debug, caller_method_name=caller[0].to_s)
 
-    # conf.record_in_log tells us whether we should be logging at all
-    return unless conf.record_in_log
+    # @conf.record_in_log tells us whether we should be logging at all
+    return unless @conf.record_in_log
 
     # If caller_method_name is nil, magically get the name of the calling method
-    caller_method_name ||= caller[0].to_s
-    conf.logger.progname = caller_method_name unless caller_method_name == ''
+    @conf.logger.progname = caller_method_name unless caller_method_name == ''
 
     case level
       when :debug, 0
-        conf.logger.debug {str}
+        @conf.logger.debug {str}
       when :fatal, 4
-        conf.logger.fatal {str}
+        @conf.logger.fatal {str}
       when :error, 3
-        conf.logger.error {str}
+        @conf.logger.error {str}
       when :warn, 2
-        conf.logger.warn {str}
+        @conf.logger.warn {str}
       when :info, 1
-        conf.logger.info {str}
+        @conf.logger.info {str}
       else
-        conf.logger.unknown {str}
+        @conf.logger.unknown {str}
     end
   end
 
   # Determine whether a value should be treated as nil or nil-like. If {Configuration#ignore_attempts_to_set_nil} is
   # false, this method always returns false. If that setting is true, then it examines {Configuration#blank_str_is_nil}.
-  # If that setting is true, it returns true if value is nil or '' (like ActiveSupport's ``#blank?``)
+  # If that setting is true, it returns true if value is nil or '' (like ActiveSupport's @#blank?@)
   # @param value [Object] value to examine
   # @return [boolean] as specified above
   #
   # @api private
   def self.nilish?(value)
-    if conf.ignore_attempts_to_set_nil
-      value.nil? || (conf.blank_str_is_nil && value.eql?(''))
-    else
-      false
-    end
+    # @conf is guaranteed to be defined by the call to self.preliminary_setup below
+    # Using the instance variable here gives us surprising performance gains
+
+    @conf.ignore_attempts_to_set_nil && (value.nil? || (value.is_a?(String) && @conf.blank_str_is_nil && value.empty?))
   end
 
   # Yield the module's configuration object for manipulation.
@@ -113,7 +117,7 @@ module CushionDefaults
   #
   # @see Configuration
   def self.configure
-    yield(configuration)
+    yield(@conf)
   end
 
   # Add class methods and set up an @defaults {DefaultsHash} when the module is included in a class. Called
@@ -131,14 +135,14 @@ module CushionDefaults
 
     base.extend(ClassMethods)
 
-    if configuration.auto_load_from_yaml
+    if @conf.auto_load_from_yaml
       base.defaults_from_yaml
     else
       base.initialize_defaults_hash
     end
   end
 
-  # Get class {DefaultsHash}. If +x+ is a +Klass+, then +x#defaults+ returns +Klass.defaults+.
+  # Get class {DefaultsHash}. If @x@ is a @Klass@, then @x#defaults@ returns @Klass.defaults@.
   # @return [DefaultsHash] the defaults for self.class
   def defaults
     self.class.defaults
@@ -153,17 +157,17 @@ module CushionDefaults
     defaults[sym]
   end
 
-  # Wraps (in somewhat more convenient form) +Object#instance_variable_defined?+.
+  # Wraps (in somewhat more convenient form) @Object#instance_variable_defined?@.
   # @param sym [#to_s] String or coercable object that denotes the instance variable in question
   # @return [boolean] true if the instance variable denoted by sym is defined, false otherwise
   def has_specified?(sym)
     instance_variable_defined?("@#{sym}")
   end
 
-  # 'Crystallize' the default: i.e., if this instance does not have +sym+ specified, then set the value of +sym+
+  # 'Crystallize' the default: i.e., if this instance does not have @sym@ specified, then set the value of @sym@
   # explicitly to the default value.
   #
-  # This is most useful if you want to update the default value for +sym+ but do not want to affect one or more already
+  # This is most useful if you want to update the default value for @sym@ but do not want to affect one or more already
   # exsiting instances of the class.
   #
   # @param default_key [#to_sym] default to crystallize for this object
@@ -185,7 +189,7 @@ module CushionDefaults
 
   # Loads the optional config file, looking at the various locations specified therein.
   def self.preliminary_setup
-    local_conf_path = CALLING_PATH + configuration.yaml_source_folder + 'cushion_defaults.yaml'
+    local_conf_path = CALLING_PATH + @conf.yaml_source_folder + 'cushion_defaults.yaml'
     if File.exists?(CONFIG_LOCATION)
       t = File.open(CONFIG_LOCATION)
       log("Found and opened config file at #{CONFIG_LOCATION}", :info)
@@ -197,7 +201,7 @@ module CushionDefaults
       log("No config file found. Looked at #{CONFIG_LOCATION} and #{local_conf_path}.", :info)
     end
 
-    conf.from_hash(YAML::load(t)) if t
+    @conf.from_hash(YAML::load(t)) if t
   end
 
   self.preliminary_setup

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cushion_defaults
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.5.2
 platform: ruby
 authors:
 - Ryan Mitchell
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-12-10 00:00:00.000000000 Z
+date: 2014-12-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -24,8 +24,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.11'
-description: Cushion your instance variables. Get a default if a variable isn’t defined.
-  DRY off your code.
+description: Cushion your attributes. Return a static or dynamic default if your @variable
+  isn’t defined. DRY off your code.
 email: posgarou@gmail.com
 executables: []
 extensions: []