cushion_defaults 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: afcfd510eb6d2f7ceaa05cc1fdba5464b5c407ed
-  data.tar.gz: 570e83a012861e042c33e582bf79fc29da25b383
+  metadata.gz: bacbeab26c1d40ab130cc3fb66b06a7e0eb26012
+  data.tar.gz: b056aa659f1279580225fa627482894ac8ac5e90
 SHA512:
-  metadata.gz: 8e7f8f996945dd467466654fae31c8f62648cc3519738b9f97085787e3b7ea4a245e225b9b083509572cb40c443de9e23a0d94e1389e1ee70cedfd335409bbce
-  data.tar.gz: a3d35fc0f44e465c22a0de9fa3576d6852ac6be3a5af34daf7227ee694da7e4be088071b2ce29e2f72ac849fc0936ac09dde07b042a187b809163afe5c9d7ba3
+  metadata.gz: 3d427f699e5ffb42d22c5e4cc7c2ae9817df5edeb347e984b0fff367924100defc1c8e30582f7ebcdead9b86006cd44a6bd5556357f096610335a80f25b4ed53
+  data.tar.gz: 4dca3355fac1a733c93d85511df0d943548774e65bc590300656b4d8cb141fa54f09282f180837924b83d8f3908488e314ff300a02272b7d83398e05260e3f07

data/CHANGELOG.md

@@ -0,0 +1,39 @@
+# CHANGELOG
+
+## 0.0.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.1.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.
+    - Improve performance of `cushion_reader` by approx. 115%.
+- 0.1.1
+    - Greatly improve and expand documentation.
+    - Switch from rdoc to Yard
+
+## 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`
+    - Improve documentation further.

data/README.md

@@ -0,0 +1,331 @@
+# Cushion Defaults
+## What Does It Do?
+
+### TL;DR
+
+An easy, flexible, and powerful alternative to hashes of defaults. Can be used both in individual classes and in complex class hierarchies.
+
+### The Long Version
+
+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.
+
+If, for example, the default value for `@wheels` in class Car is 4 and we set up a new instance called `ford` (`ford = Car.new`), then calling `ford.wheels` will return 4—even though no instance variable `@wheels` has been directly specified for `ford`.  And if we later change the default value of `wheels` for Car (`Car.defaults[:wheels] = 6`), then all subsequent calls to `ford.wheels` will return 6 (unless we crystallize it beforehand—see below for more details).
+
+## Why Should I Care?
+
+1. Don't Repeat Yourself (DRY): Gather your defaults in one place, and specify them only once.
+2. Correspondingly, minimize the amount of code you have to write and maintain. You'll be writing `x || default_value_for_x` a lot less—and if you later change the default value for x, you only have to update a single line of code.
+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:
+
+```ruby
+class Person
+  include CushionDefaults
+  self.defaults[:favorite_color] = 'blue'
+  cushion :favorite_color
+end
+
+ryan, julia = Person.new, Person.new
+ryan.favorite_color = 'blue'
+
+ryan.favorite_color # 'blue'
+ryan.has_specified?(:favorite_color) # true
+julia.favorite_color # 'blue'
+julia.has_specified?(:favorite_color) # false
+
+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)).
+## 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
+class Plant
+  include CushionDefaults
+  self.defaults = {color: 'green', sunlight_needed: 'full'}
+  
+  # cushion_defaults is here equivalent to:
+  #   cushion_reader :color, :sunlight_needed
+  #   cushion_writer :color, :sunlight_needed
+  cushion_defaults
+  
+  def needs_full_sunlight?
+    sunlight_needed.eql?('full')
+  end
+end
+
+rhododendron = Plant.new
+rhododendron.color # 'green'
+rhododendron.needs_full_sunlight? # true
+```
+
+Now, if we later decide to place our Plant class within Brandon Sanderson's [Mistborn](http://brandonsanderson.com/books/mistborn/the-final-empire/) world, we may want to update our defaults:
+
+```ruby
+Plant.defaults[:color] = 'brown'
+```
+
+As soon as we do this, all Plants that do not have a color explicitly assigned will return the new default value when we call their `#color` method.
+
+```ruby
+rhododendron.color # 'brown'
+```
+
+### Crystallizing Defaults
+You can prevent this auto-updating, if desired, by calling `#crystallize_default` on those instances you don't want auto-updated. `#crystallize_default(sym)` effectively says "If no value for `@sym` is explicitly set, then explictly set it to the default value." Obviously, then, `#crystallize_default(sym)` affects only those instances that do not have a value explicitly specified for `sym`.
+
+```ruby
+tulip, rose = Plant.new, Plant.new
+tulip.color # 'brown'
+rose.color = 'red'
+tulip.has_specified?(:color) # false
+rose.has_specified?(:color) # true
+
+# crystallizes :color to 'brown'
+tulip.crystallize_default(:color)
+
+# has no effect, since :color is already set to 'red'
+rose.crystallize_default(:color)
+
+tulip.has_specified?(:color) # true
+
+Plant.defaults[:color] = 'green'
+
+tulip.color # 'brown'
+rose.color # 'red'
+Plant.new.color # 'green'
+```
+
+### Defaults and Inheritance
+Classes inherit the defaults of those ancestors that respond to `#defaults` with a Hash or a descendent thereof.
+
+This all takes place automatically.  When CushionDefaults is included in a class, it automatically includes itself in all classes that subclass that class, and when a `cushion_reader` is called, it automatically moves up the class hierarchy if no value for the key is specified in the instance variable or in the current class.
+
+```ruby
+class Klass
+  include CushionDefaults
+  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
+
+x, y, z = Klass.new, SubKlass.new, SubSubKlass.new
+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]
+# [Klass, Klass, Klass]
+# x.fourth would return NoMethodError
+
+puts [y.first, y.second, y.third, y.fourth]
+# [Klass, SubKlass, Klass, SubKlass]
+
+puts [z.first, z.second, z.third, z.fourth]
+# ['custom', SubKlass, SubSubKlass, SubKlass]
+```
+
+Obviously, changing the default of a parent class changes the value returned by subclass instances, unless they have explicitly overridden the default.
+
+```ruby
+SubKlass.defaults[:second] = 'totally new value'
+z.class # SubSubKlass, which < SubKlass
+z.second # 'totally new value'
+```
+
+### Adding and Removing Readers and Writers
+Now, if we were to later add a new default to Plant
+
+```ruby
+Plant.defaults[:climate] = 'temperate'
+```
+
+and ran
+
+```ruby
+rhododendron.climate
+```
+
+we would get a `NoMethodError`.
+
+By default, CushionDefaults does not automatically add or remove readers and writers when defaults are added and removed. To change methods, you need to manually add readers and writers for the new default:
+
+```ruby
+Plant.cushion :climate
+```
+
+If at any point you want to manually remove the `cushion_reader` or `cushion_writer` for a class (although the need for this should be rare, as you can simply overwrite it), you can run the following:
+
+```ruby
+Plant.remove_reader :climate
+Plant.remove_writer :climate
+```
+
+Alternatively, CushionDefaults can automatically add and remove methods for any new defaults added and any existing defaults removed.  But to do that, we need to configure CushionDefaults.
+
+### Configuring CushionDefaults
+
+There are two recommended techniques for configuring CushionDefaults (although a few other variations will work as well).
+
+The simplest is to use `CushionDefaults.configure`, which yields a `CushionDefaults::Configuration` object that can be modified by a number of different methods, detailed in the docs.
+
+```ruby
+CushionDefaults.configure do |conf|
+  conf.update_readers = true
+  conf.update_writers = true
+end
+```
+
+If the above `#configure` call is placed immediately after the require statement, then no explicit calls to `cushion`, `cushion_reader`, or `cushion_writer` are needed.
+
+```ruby
+CushionDefaults.configure do |conf|
+  conf.update_readers = true
+  conf.update_writers = true
+end
+
+class Chair
+  include CushionDefaults
+  self.defaults = {material: 'wood', comfort_factor: 5}
+end
+
+dining_room_hardback = Chair.new
+dining_room_hardback.comfort_factor = 3
+
+dining_room_hardback.material # 'wood'
+dining_room_hardback.comfort_factor # 3
+
+# automatically adds #number_accomodated and #number_accomodated=, because of above-specified options
+Chair.defaults[:number_accomodated] = 1
+
+dining_room_hardback.number_accomodated # 1
+```
+
+As an alternative to the `CushionDefaults.configure` block, you can define a cushion_defaults.yaml file.  By default, CushionDefaults looks for this at `config/cushion_defaults.yaml` (relative either to the directory of the first file to require CushionDefaults or the gem's location in the file system). The YAML format is unremarkable, with the above `CushionDefaults.config do ... end` block equivalent to:
+
+```yaml
+update_readers: true
+update_writers: true
+```
+
+### Storing Class Defaults in YAML Files
+
+By default, CushionDefaults checks for YAML files for each class but does not complain if no YAML files are found.  (If you want it to complain, set `config.whiny_yaml` to true.)
+
+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`.
+
+You can specify a different YAML source folder relative to the calling directory (`config/cushion_defaults/` by default) by setting `config.yaml_source_folder`, or you can specify an absolute path to the YAML source folder by setting `config.yaml_source_full_path`.
+
+If you ever are bug-hunting and want to see where CushionDefaults expects a YAML file to be located, you can pass the class object to `config.yaml_file_for(klass)`.
+
+These YAML files are loaded automatically (unless `config.auto_load_from_yaml` has been set to false). But if you ever want to (wipe and) reload the defaults for a class—or load for the first time if the above option is disabled—use the class method `defaults_from_yaml`.
+
+### Managing Multiple Class Defaults
+
+#### Multiple Sets of Class Defaults
+
+You can use the above techniques to maintain different sets of class defaults for all of your classes. This is especially useful if your application needs to run in different environments or regions. For a more complex (but still simple enough) example, see Example 4 in the examples folder. Following is a trivial example.
+
+```ruby
+class Season
+  # Obviously this is only meteorological seasons, and only valid for the Northern hemisphere
+  attr_accessor :months, :short_code
+  def initialize(&block)
+    yield(self) if block_given?
+  end
+  def include?(date)
+    months.include?(date.month)
+  end
+  def yaml_source_path
+    "config/cushion_defaults/#{short_code}/"
+  end
+end
+seasons = [
+  Season.new {|s| s.months=[3,4,5]; s.short_code='spr'},
+  Season.new {|s| s.months=[6,7,8]; s.short_code='sum'},
+  Season.new {|s| s.months=[9,10,11]; s.short_code='fal'},
+  Season.new {|s| s.months=[12,1,2]; s.short_code='win'}
+]
+current_season = seasons.select{|s| s.include?(Date.today)}.first
+CushionDefaults.configure {|conf| conf.yaml_source_path = current_season.yaml_source_path}
+```
+
+The above will set the root directory for all class defaults, depending on the current date, to one of the following: `config/cushion_defaults/spr/`, `config/cushion_defaults/sum/`, `config/cushion_defaults/fal/`, or `config/cushion_defaults/win/`.
+
+#### Multiple Defaults for a Single Class
+
+Alternatively, if there is only a single class whose defaults you would like to load in one of several forms, you can do something like the following:
+
+```ruby
+# select a random language
+current_lang = ['en','fr','de'].sample
+class Person
+  include CushionDefaults
+  defaults_from_yaml "#{self.to_s}_#{current_lang}"
+  cushion_defaults
+end
+```
+
+In this example, we load (randomly) either `person_en.yaml`, `person_fr.yaml`, or `person_de.yaml`.
+
+### 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.
+
+### Testing and Bug Fixing
+
+The most common testing configuration options are available by calling `config.testing!`.
+
+You may find the following methods helpful in testing and bug fixing:
+
+- `instance#has_specified?(sym)`: returns true if the instance has the instance variable denoted by `sym` defined
+- `defaults#ish_keys`: returns the keys of both its defaults and those it inherits from its parents
+- `defaults#has_ish_key?(key)`: returns true if `key` is an ish_key.
+- `defaults#where_is_that_default_again(sym)`: returns the closest ancestor class in which `sym` is defined as a default. If no ancestor class has it defined as a default, returns `nil`.
+
+## But I need...
+
+If you need more than CushionDefaults offers right now, you've got a couple different options:
+
+1. Suggest a feature. Please explain why you think this feature would be valuable, and offer a couple different use cases to showcase how it would help people.
+2. Code a feature. Fork and pull, and I'll fold it in and implement it if it looks solid and generally useful.
+3. Check out Cascading Configuration. You may want to check out [Cascading Configuration](https://github.com/RidiculousPower/cascading_configuration), which tackles a similar problem but offers a different approach and featureset.
+
+## Feedback
+
+Any feedback is very much appreciated!
+
+###Bugs
+
+Run into any bugs or issues? Please report them on the [GitHub issue tracker](https://github.com/posgarou/cushion_defaults/issues).
+
+###Like It?
+
+1. Tell a friend.
+2. Star or [fork](https://github.com/posgarou/cushion_defaults/fork) the [GitHub repository](https://github.com/posgarou/cushion_defaults).
+3. If you're feeling generous, [offer a tip](https://gratipay.com/posgarou/).
+
+###Not Sold?
+
+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.

data/lib/cushion_defaults.rb

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

data/lib/cushion_defaults/configuration.rb

@@ -1,199 +1,199 @@
 require 'logger'
 
-# TODO Place in module CushionDefaults--dumb mistake
-
-# 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+.
-#
-# For configuration options, see the attribute writers.
-#
-class Configuration
-  # adapted from http://brandonhilkert.com/blog/ruby-gem-configuration-patterns/
-
-  # @return [boolean] true if readers should automatically be added, false otherwise. Def. false.
-  attr_accessor :update_readers
-
-  # @return [boolean] true if writers should automatially be added, false otherwise. Def. false.
-  attr_accessor :update_writers
-
-  # @return [boolean] true if CushionDefaults should automatically check whether a YAML file exists for each class that
-  #   includes it, false otherwise. Def. true.
-  # @see ClassMethods.defaults_from_yaml defauls_from_yaml
-  attr_accessor :auto_load_from_yaml
-
-  # @return [string] the location, relative to the directory of the first file to include CushionDefaults, where YAML
-  #   config files are looked for by default. Def. 'config/cushion_defaults/'
-  attr_accessor :yaml_source_folder
-
-  # @return [string] the full path to the directory where YAML config files are looked for. If specified, this overrides
-  #   {#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, 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
-  #   obj.var = nil # has no effect
-  #   obj.var # 'default value'
-  # @see blank_str_is_nil
-  attr_accessor :ignore_attempts_to_set_nil
-
-  # @return [boolean] if true, cushion_writers will also not record blank strings. Has no effect if
-  #   {#ignore_attempts_to_set_nil} is false. Def. true.
-  # @example Ignored Call to cushion_writer When blank_str_is_nil == false
-  #   obj.var = '' # has no effect
-  #   obj.var # 'default value'
-  attr_accessor :blank_str_is_nil
-
-  # @return [boolean] if true, cushion_writers will issue a warning when you attempt to set an instance variable to
-  #   nil or '' (as applicable). Has no effect if {#ignore_attempts_to_set_nil} == false. Def. false.
-  attr_accessor :whiny_ignores
-
-  # Has no effect.
-  # @deprecated
-  attr_accessor :cushion_child_defaults_in_parent
-
-  # @return [Logger] returns the Logger object to which CushionDefaults sends log entries.
-  attr_reader :logger
-
-  # Initializes with the values specified in {#defaults!}
-  def initialize
-    defaults!
-    @we_have_a_pushy = false
-  end
+module 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+.
+  #
+  # For configuration options, see the attribute writers.
+  #
+  class Configuration
+    # adapted from http://brandonhilkert.com/blog/ruby-gem-configuration-patterns/
+
+    # @return [boolean] true if readers should automatically be added, false otherwise. Def. false.
+    attr_accessor :update_readers
+
+    # @return [boolean] true if writers should automatially be added, false otherwise. Def. false.
+    attr_accessor :update_writers
+
+    # @return [boolean] true if CushionDefaults should automatically check whether a YAML file exists for each class that
+    #   includes it, false otherwise. Def. true.
+    # @see ClassMethods.defaults_from_yaml defauls_from_yaml
+    attr_accessor :auto_load_from_yaml
+
+    # @return [string] the location, relative to the directory of the first file to include CushionDefaults, where YAML
+    #   config files are looked for by default. Def. 'config/cushion_defaults/'
+    attr_accessor :yaml_source_folder
+
+    # @return [string] the full path to the directory where YAML config files are looked for. If specified, this overrides
+    #   {#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, 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
+    #   obj.var = nil # has no effect
+    #   obj.var # 'default value'
+    # @see blank_str_is_nil
+    attr_accessor :ignore_attempts_to_set_nil
+
+    # @return [boolean] if true, cushion_writers will also not record blank strings. Has no effect if
+    #   {#ignore_attempts_to_set_nil} is false. Def. true.
+    # @example Ignored Call to cushion_writer When blank_str_is_nil == false
+    #   obj.var = '' # has no effect
+    #   obj.var # 'default value'
+    attr_accessor :blank_str_is_nil
+
+    # @return [boolean] if true, cushion_writers will issue a warning when you attempt to set an instance variable to
+    #   nil or '' (as applicable). Has no effect if {#ignore_attempts_to_set_nil} == false. Def. false.
+    attr_accessor :whiny_ignores
+
+    # Has no effect.
+    # @deprecated
+    attr_accessor :cushion_child_defaults_in_parent
+
+    # @return [Logger] returns the Logger object to which CushionDefaults sends log entries.
+    attr_reader :logger
+
+    # Initializes with the values specified in {#defaults!}
+    def initialize
+      defaults!
+      @we_have_a_pushy = false
+    end
 
-  # @!attribute [r] yaml_source_full_path
-  # 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
-  end
+    # @!attribute [r] yaml_source_full_path
+    # 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
+    end
 
-  # 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)
-    log_str = 'Loading configuration options from hash...'
-    loaded_config.each do |key, val|
-      log_str << "\n\t\t#{key}: #{val}"
-      # We need to be able to use some of the checks and responses in the custom setter methods
-      writer_sym = "#{key}=".to_sym
-      send writer_sym, val if respond_to? writer_sym
-      #instance_variable_set("@#{key.to_sym}", val) if instance_variable_defined? "@#{key.to_sym}"
+    # 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)
+      log_str = 'Loading configuration options from hash...'
+      loaded_config.each do |key, val|
+        log_str << "\n\t\t#{key}: #{val}"
+        # We need to be able to use some of the checks and responses in the custom setter methods
+        writer_sym = "#{key}=".to_sym
+        send writer_sym, val if respond_to? writer_sym
+        #instance_variable_set("@#{key.to_sym}", val) if instance_variable_defined? "@#{key.to_sym}"
+      end
+      CushionDefaults.log(log_str, :info)
     end
-    CushionDefaults.log(log_str, :info)
-  end
 
-  # Sets or resets configuration object to default configuration settings.
-  def defaults!
-    self.update_readers = false
-    self.update_writers = false
-    self.auto_load_from_yaml = true
-    self.yaml_source_folder = 'config/cushion_defaults/'
-    self.yaml_source_full_path = nil
-    self.record_in_log = true
-    self.logger = Logger.new $stdout
-    self.log_lvl = Logger::INFO
-    self.whiny_yaml = false
-    self.whiny_ignores = false
-    self.ignore_attempts_to_set_nil = true
-    self.blank_str_is_nil = true
-  end
+    # Sets or resets configuration object to default configuration settings.
+    def defaults!
+      self.update_readers = false
+      self.update_writers = false
+      self.auto_load_from_yaml = true
+      self.yaml_source_folder = 'config/cushion_defaults/'
+      self.yaml_source_full_path = nil
+      self.record_in_log = true
+      self.logger = Logger.new $stdout
+      self.log_lvl = Logger::INFO
+      self.whiny_yaml = false
+      self.whiny_ignores = false
+      self.ignore_attempts_to_set_nil = true
+      self.blank_str_is_nil = true
+    end
 
-  # Sets configuration object to most common testing (and development) options.
-  def test_settings!
-    defaults!
-    self.whiny_yaml = true
-    self.whiny_ignores = true
-    self.log_lvl = Logger::DEBUG
-  end
+    # Sets configuration object to most common testing (and development) options.
+    def test_settings!
+      defaults!
+      self.whiny_yaml = true
+      self.whiny_ignores = true
+      self.log_lvl = Logger::DEBUG
+    end
 
-  # @!attribute [w] logger
-  # Sets @logger to either a different Logger or another object that implements roughly the same interface. Note
-  #   that only minimal checking is done to ensure the interface is implemented, and passing in an object with an
-  #   incomplete implementation of the interface will cause errors. If you want to disable logging, you should instead
-  #   set {#record_in_log} to false.
-  # @see #record_in_log
-  def logger=(new_logger)
-    if new_logger.nil?
-      self.record_in_log = false
-      @logger = nil
-    else
-      if new_logger.respond_to? :info
-        @logger = new_logger
-        assign_formatter_to_logger
+    # @!attribute [w] logger
+    # Sets @logger to either a different Logger or another object that implements roughly the same interface. Note
+    #   that only minimal checking is done to ensure the interface is implemented, and passing in an object with an
+    #   incomplete implementation of the interface will cause errors. If you want to disable logging, you should instead
+    #   set {#record_in_log} to false.
+    # @see #record_in_log
+    def logger=(new_logger)
+      if new_logger.nil?
+        self.record_in_log = false
+        @logger = nil
       else
-        CushionDefaults.log("config.logger not set to #{new_logger}, as it does not appear to implement standard logging methods.", :error)
+        if new_logger.respond_to? :info
+          @logger = new_logger
+          assign_formatter_to_logger
+        else
+          CushionDefaults.log("config.logger not set to #{new_logger}, as it does not appear to implement standard logging methods.", :error)
+        end
       end
     end
-  end
 
-  # CamelCase to underscores
-  # @param s [String] CamelCase
-  # @return [String] underscored version of s
-  def underscore(s)
-    s.gsub(/::/, '/').
-        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
-        gsub(/([a-z\d])([A-Z])/,'\1_\2').
-        tr("-", "_").
-        downcase
-  end
+    # CamelCase to underscores
+    # @param s [String] CamelCase
+    # @return [String] underscored version of s
+    def underscore(s)
+      s.gsub(/::/, '/').
+          gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+          gsub(/([a-z\d])([A-Z])/,'\1_\2').
+          tr("-", "_").
+          downcase
+    end
 
-  # Expected YAML location for a class.
-  # @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'}"
-  end
+    # Expected YAML location for a class.
+    # @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'}"
+    end
 
-  # @!attribute [w] log_lvl
-  # Set the level of logging. Alias of logger.level=. 0: debug, 1: info, 2: warn, 3: error, 4: fatal, 5: unknown
-  def log_lvl=(lvl)
-    if @logger
-      @logger.level = lvl
+    # @!attribute [w] log_lvl
+    # Set the level of logging. Alias of logger.level=. 0: debug, 1: info, 2: warn, 3: error, 4: fatal, 5: unknown
+    def log_lvl=(lvl)
+      if @logger
+        @logger.level = lvl
+      end
     end
-  end
 
-  # @!attribute [r] we_have_a_pushy
-  # Denotes whether (over the life of the program) any defaults have been marked pushy.
-  # In the future, this may instead denote whether any defaults are *currently* marked as pushy.
-  # @return [boolean] true if a pushy was set at any time
-  # @api private
-  def we_have_a_pushy?
-    @we_have_a_pushy
-  end
+    # @!attribute [r] we_have_a_pushy
+    # Denotes whether (over the life of the program) any defaults have been marked pushy.
+    # In the future, this may instead denote whether any defaults are *currently* marked as pushy.
+    # @return [boolean] true if a pushy was set at any time
+    # @api private
+    def we_have_a_pushy?
+      @we_have_a_pushy
+    end
 
-  # Opposite of {#we_have_a_pushy?}
-  # @return [boolean] true if no pushies have been set over the life of the program
-  # @api private
-  def no_pushies?
-    # Note that if you add a pushy, and then remove it, this will still return false. Basically, the method returns
-    # whether there was, at any point in time, a pushy default.
-    #
-    # The whole handling of pushies can and will be improved in the future.
-    !@we_have_a_pushy
-  end
+    # Opposite of {#we_have_a_pushy?}
+    # @return [boolean] true if no pushies have been set over the life of the program
+    # @api private
+    def no_pushies?
+      # Note that if you add a pushy, and then remove it, this will still return false. Basically, the method returns
+      # whether there was, at any point in time, a pushy default.
+      #
+      # The whole handling of pushies can and will be improved in the future.
+      !@we_have_a_pushy
+    end
 
-  # Declares that a pushy default has been set.
-  # @api private
-  def we_have_a_pushy!
-    @we_have_a_pushy = true
-  end
+    # Declares that a pushy default has been set.
+    # @api private
+    def we_have_a_pushy!
+      @we_have_a_pushy = true
+    end
 
-  protected
+    protected
 
-  # 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|
-      "\nCUSHIONDEFAULTS: #{severity}\n\t\##{progname ? "#{progname} at" : "At"} #{time.strftime('%d %b %Y, %H:%M:%S%p')}\n\t#{msg}\n"
+    # 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|
+        "\nCUSHIONDEFAULTS: #{severity}\n\t\##{progname ? "#{progname} at" : "At"} #{time.strftime('%d %b %Y, %H:%M:%S%p')}\n\t#{msg}\n"
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cushion_defaults
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Ryan Mitchell
@@ -9,15 +9,47 @@ autorequire:
 bindir: bin
 cert_chain: []
 date: 2014-12-09 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !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.
 email: posgarou@gmail.com
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
+- CHANGELOG.md
 files:
+- CHANGELOG.md
+- README.md
 - lib/cushion_defaults.rb
 - lib/cushion_defaults/class_methods.rb
 - lib/cushion_defaults/configuration.rb
@@ -26,8 +58,12 @@ homepage: https://github.com/posgarou/cushion_defaults
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
-rdoc_options: []
+post_install_message: |-
+  Thanks for installing CushionDefaults!
+  For a quick overview, check out the README and examples/ folder.
+rdoc_options:
+- "--main"
+- README.md
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement