cushion_defaults 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bacbeab26c1d40ab130cc3fb66b06a7e0eb26012
-  data.tar.gz: b056aa659f1279580225fa627482894ac8ac5e90
+  metadata.gz: 8b3c6fc2391e0197aea23df6eb08eaa1bbf91946
+  data.tar.gz: 995a6c5ad6d1caea8f5f2cbcc49f99bf3f87a15c
 SHA512:
-  metadata.gz: 3d427f699e5ffb42d22c5e4cc7c2ae9817df5edeb347e984b0fff367924100defc1c8e30582f7ebcdead9b86006cd44a6bd5556357f096610335a80f25b4ed53
-  data.tar.gz: 4dca3355fac1a733c93d85511df0d943548774e65bc590300656b4d8cb141fa54f09282f180837924b83d8f3908488e314ff300a02272b7d83398e05260e3f07
+  metadata.gz: 4c97a480b173e4a9b3dd1b11756eb502d84d1ba26fd15368323ca147eaec2b61d1c97c6a0d893c566938d725af94f56fa9cc3dc94a1d5564b726457fb86a3dfe
+  data.tar.gz: cc154a333022212a4cf9a4f628fe81c97fe4fce4c00dc816024f1b2762ed9683f8265783bb7985999a6f6f5174903dbac6e59a8a68fecc2cf1bf6e837feadfbb

data/CHANGELOG.md

@@ -36,4 +36,13 @@
     - IMPROVEMENT: Testing
         - `test/` renamed to `spec/`
         - Add `.rspec` and `spec/spec_helper.rb`
-    - Improve documentation further.
+    - Improve documentation further.
+
+## 0.3.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

data/README.md

@@ -11,6 +11,10 @@ Allows you to specify a "cushion" for various instance variables—effectively a
 
 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).
 
+### The Latest
+
+I try to keep all of this up-to-date, but the latest information can always be found in CHANGELOG.md.
+
 ## Why Should I Care?
 
 1. Don't Repeat Yourself (DRY): Gather your defaults in one place, and specify them only once.
@@ -80,32 +84,8 @@ As soon as we do this, all Plants that do not have a color explicitly assigned w
 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.
@@ -151,6 +131,7 @@ z.second # 'totally new value'
 ```
 
 ### Adding and Removing Readers and Writers
+
 Now, if we were to later add a new default to Plant
 
 ```ruby
@@ -225,12 +206,71 @@ update_readers: true
 update_writers: true
 ```
 
+### Freezing and Thawing Defaults
+
+You may wish to prevent a default from further modification, either permanently or temporarily. This can prevent silly mistakes that are otherwise difficult to track down. CushionDefaults makes this possible via a freezing and thawing API.  The key methods here are `#freeze_default` and `#thaw_default`.
+
+```ruby
+class BuffaloNY
+    include CushionDefaults
+    self.defaults = {temperature: -10}
+    freeze_default :temperature
+end
+
+# Raises CushionDefaults::FrozenDefaultError (< RunTimeError)
+BuffaloNY.defaults[:temperature] = 60
+
+# Assuming we caught the above error...
+BuffaloNY.defaults[:temperature] == -10 # true
+
+# Come summer, we can thaw the default
+BuffaloNY.thaw_default :temperature
+
+#And we can reset it without error
+BuffaloNY.defaults[:temperature] = 60
+```
+
+Frozen defaults can still have their values overridden by child classes.
+
+```ruby
+class NaturalLog
+    include CushionDefaults
+    self.defaults = {base: Math::E}
+    freeze_default :base
+end
+
+class UnnaturalLog < NaturalLog; end
+
+# Raises CushionDefaults::FrozenDefaultError
+NaturalLog.defaults[:base] = 1i
+
+# Works
+UnnaturalLog.defaults[:base] = 1i
+```
+
+Note that frozen defaults can still have their values modified if those values are themselves mutable. To prevent this, we need to use  `#deep_freeze`—but this should be done with caution.
+
+(In some situations, even this can can fail to "fully" freeze an object. Check out [ice_nine](https://github.com/dkubb/ice_nine) for a fuller solution.)
+
+Finally, to freeze or thaw all defaults en masse, the API makes available `#freeze_defaults` and `#thaw_defaults`.
+
 ### 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`.
 
+These YAML files are completely unremarkable in form. Note that all defaults should be specified at root (not in `defaults:`, and currently only simple types are processed.  For the above Chair class, we could place the defaults in a YAML class file like the following:
+
+```yaml
+# config/cushion_defaults/chair.yaml
+material: 'wood'
+comfort_factor: 5
+number_accomodated: 1
+```
+
+For an example of all of this in action, look at `examples/example3/example3.rb` and its class default files in `examples/example3/config/cushion_defaults/`.
+
 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)`.
@@ -243,31 +283,76 @@ These YAML files are loaded automatically (unless `config.auto_load_from_yaml` h
 
 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.
 
+Assume we have four YAML class defaults files as follows:
+
+```yaml
+# config/cushion_defaults/spr/user.yaml
+weather_judgment: 'how nice'
+```
+
+```yaml
+# config/cushion_defaults/sum/user.yaml
+weather_judgment: 'is it hot in here or is it just me?'
+```
+
+```yaml
+# config/cushion_defaults/fal/user.yaml
+weather_judgment: "if only it weren\'t for the leaves"
+```
+
+```yaml
+# config/cushion_defaults/win/user.yaml
+weather_judgment: "baby it\'s cold outside"
+```
+
+Combine this with the following Ruby, and we can get different defaults depending on the current meteorological season.
+
 ```ruby
 class Season
-  # Obviously this is only meteorological seasons, and only valid for the Northern hemisphere
+  # Obviously this is 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 following will set the root directory for all class defaults, depending on the current season.
+# Possible resulting config paths:
+#   - `config/cushion_defaults/spr/`
+#   - `config/cushion_defaults/sum/`
+#   - `config/cushion_defaults/fal/`
+#   - `config/cushion_defaults/win/`
+CushionDefaults.configure do |conf|
+  conf.yaml_source_path = current_season.yaml_source_path
+end
+
+class User
+  # Automatically loads in defaults from the above-selected path
+  cushion :weather_judgment
+end
+
+# Returns one of the messages from the above YAML files, depending on the current meteorological season
+User.new.weather_judgment
 ```
 
-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
 
@@ -283,7 +368,35 @@ class Person
 end
 ```
 
-In this example, we load (randomly) either `person_en.yaml`, `person_fr.yaml`, or `person_de.yaml`.
+In this example, we load (randomly) either `person_en.yaml`, `person_fr.yaml`, or `person_de.yaml`.  For a fuller example along these lines, see `examples/example4/example4.rb`.
+
+### Crystallizing Defaults
+
+You can prevent auto-updating of default values, 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'
+```
+
+(Crystallizing defaults should be carefully distinguished from freezing defaults: crystallizing defaults applies to specific instances, whereas freezing defaults applies to the class itself.)
 
 ### Pushy and Polite Defaults
 
@@ -308,21 +421,21 @@ If you need more than CushionDefaults offers right now, you've got a couple diff
 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
+## Well, If You Ask Me...
 
 Any feedback is very much appreciated!
 
-###Bugs
+### For the Entomologists
 
 Run into any bugs or issues? Please report them on the [GitHub issue tracker](https://github.com/posgarou/cushion_defaults/issues).
 
-###Like It?
+### 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?
+### Not Sold?
 
 If you have the time, tell me why.
 

data/lib/cushion_defaults/class_methods.rb

@@ -5,17 +5,6 @@ module CushionDefaults
     # Reader for the +defaults+ +DefaultsHash+.
     attr_reader :defaults
 
-    # Either set up or wipe @defaults. Should not usually be called directly.
-    # @api private
-    def initialize_defaults_hash
-      if @defaults
-        # We need to maintain the identity of the hash, as child classes may have stored a reference to it
-        @defaults.clear
-      else
-        @defaults = DefaultsHash.new(self)
-      end
-    end
-
     # @!attribute [w] defaults
     # Wipe @defaults and replace it with the keys/vals of +replacement_hash+.
     #
@@ -25,9 +14,9 @@ module CushionDefaults
     def defaults=(replacement_hash)
       # Need to copy over keys/vals to ensure @defaults remains a DefaultsHash and retains identity
 
-      CushionDefaults.log("Old defaults deleted for #{self}:#{@defaults.reduce(''){|s,(k,v)| s+"\n\t\t#{k}: #{v}"}}", :info) unless @defaults.empty?
+      CushionDefaults.log("Old defaults deleted for #{self}:#{defaults.empty? ? ' [none]' : @defaults.reduce(''){|s,(k,v)| s+"\n\t\t#{k}: #{v}"}}", :info) unless @defaults.empty?
       @defaults.replace(replacement_hash)
-      CushionDefaults.log("New defaults added for #{self}:#{@defaults.reduce(''){|s,(k,v)| s+"\n\t\t#{k}: #{v}"}}", :info)
+      CushionDefaults.log("New defaults added for #{self}:#{defaults.empty? ? ' [none]' : @defaults.reduce(''){|s,(k,v)| s+"\n\t\t#{k}: #{v}"}}", :info)
       @defaults.keys.each do |key|
         unless key.is_a? Symbol
           @defaults[key.to_sym] = @defaults[key].delete!
@@ -42,6 +31,8 @@ module CushionDefaults
       @defaults[key.to_sym] = val
     end
 
+    # @!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+.
@@ -62,7 +53,7 @@ module CushionDefaults
       end
 
       initialize_defaults_hash
-      log_str = "New defaults added for #{self}:"
+      log_str = "New defaults added for #{self}:#{' [none]' if yaml.empty?}"
       # If automatic readers and writers are enabled, this will set them up as a consequence.
       yaml.each do |key, val|
         log_str << "\n\t\t#{key}: #{val}"
@@ -71,6 +62,19 @@ module CushionDefaults
       CushionDefaults.log(log_str, :info)
     end
 
+    # Either set up or wipe @defaults. Should not usually be called directly.
+    # @api private
+    def initialize_defaults_hash
+      if @defaults
+        # We need to maintain the identity of the hash, as child classes may have stored a reference to it
+        @defaults.clear
+      else
+        @defaults = DefaultsHash.new(self)
+      end
+    end
+
+    # @!group Reader/Writer
+
     # 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
@@ -204,6 +208,88 @@ module CushionDefaults
       CushionDefaults.log("cushions established for #{self}'s defaults': #{defaults.keys.join(', ')}", :info)
     end
 
+    # @!group Freeze/Thaw Defaults
+
+    # Prevents a default from being set to a new value. Freezing a default is permanent in the life of the program.
+    #
+    # Note that while a frozen default is guaranteed to maintain its identity, its attributes can still be modified
+    # (e.g., by bang! methods). To prevent any modification to a default value, call {#deep_freeze_default}.
+    #
+    # Does not throw an error when you attempt to freeze an already-frozen default, but it does log at warning level.
+    #
+    # @note A frozen default can still be overridden lower in the class hierarchy.
+    # @see #thaw_default(sym)
+    #
+    # @api freeze
+    def freeze_default(*syms)
+      syms.each do |sym|
+        sym = sym.to_sym
+        unless defaults.freeze_default! sym
+          # It returns nil if the key was already present in the Set
+          CushionDefaults.log("Cannot freeze #{sym}: it was already frozen for #{self}", :warn)
+        end
+      end
+    end
+
+    # Calls {#freeze_default} for all defaults.
+    #
+    # @api freeze
+    def freeze_defaults
+      freeze_default *defaults
+    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.
+    #
+    # 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+
+    #
+    # @api freeze
+    def deep_freeze_default(*syms)
+      syms.each do |sym|
+        sym = sym.to_sym
+        freeze_default sym
+        defaults[sym].freeze
+      end
+    end
+
+    # Calls {#deep_freeze_default} for all defaults.
+    #
+    # @api freeze
+    def deep_freeze_defaults
+      deep_freeze_default *defaults
+    end
+
+    # 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.
+    #
+    # Does not throw an error when you attempt to thaw a non-frozen default, but it does log at warning level.
+    #
+    # @api freeze
+    def thaw_default(*syms)
+      syms.each do |sym|
+        sym = sym.to_sym
+        unless defaults.thaw_default! sym
+          # It returns nil if the key was not present in the Set
+          CushionDefaults.log("Cannot thaw #{sym}: it was already thawed for #{self}", :warn)
+        end
+        puts "After thawing, currently frozen defaults are #{defaults.frozen_defaults.to_a.join(', ')}"
+      end
+    end
+
+    # Calls {#thaw_default} for all defaults.
+    #
+    # @api freeze
+    def thaw_defaults
+      thaw_default *defaults
+    end
+
+    # @!group Pushy/Polite Defaults
+
     # Declare each sym to be pushy. Pushy defaults will be returned by {#cushion_reader}s regardless of what the
     # instance variables are set to.
     def make_pushy(*syms)
@@ -216,6 +302,8 @@ module CushionDefaults
       syms.each { |sym| @defaults.not_pushy!(sym) }
     end
 
+    # @!endgroup
+
     # Ensure that if class +Klass+ includes +CushionDefaults+, then any class that subclasses +Klass+ will include it as
     # well.
     #

data/lib/cushion_defaults/configuration.rb

@@ -10,6 +10,8 @@ module CushionDefaults
   class Configuration
     # adapted from http://brandonhilkert.com/blog/ruby-gem-configuration-patterns/
 
+    # @!group Option Reader/Writers
+
     # @return [boolean] true if readers should automatically be added, false otherwise. Def. false.
     attr_accessor :update_readers
 
@@ -55,17 +57,35 @@ module CushionDefaults
     #   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
+    # @!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
+        else
+          CushionDefaults.log("config.logger not set to #{new_logger}, as it does not appear to implement standard logging methods.", :error)
+        end
+      end
+    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
+      end
     end
 
     # @!attribute [r] yaml_source_full_path
@@ -75,6 +95,14 @@ module CushionDefaults
       @yaml_source_full_path || CushionDefaults::CALLING_PATH + yaml_source_folder
     end
 
+    # @!endgroup
+
+    # Initializes with the values specified in {#defaults!}
+    def initialize
+      defaults!
+      @we_have_a_pushy = false
+    end
+
     # Update configuration options with those values contained within +loaded_config+.
     #
     # @param loaded_config [Hash] hash of config options and settings
@@ -90,6 +118,8 @@ module CushionDefaults
       CushionDefaults.log(log_str, :info)
     end
 
+    # @!group Mass Setter Methods
+
     # Sets or resets configuration object to default configuration settings.
     def defaults!
       self.update_readers = false
@@ -114,25 +144,7 @@ module CushionDefaults
       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
-        else
-          CushionDefaults.log("config.logger not set to #{new_logger}, as it does not appear to implement standard logging methods.", :error)
-        end
-      end
-    end
+    # @!endgroup
 
     # CamelCase to underscores
     # @param s [String] CamelCase
@@ -152,13 +164,9 @@ module CushionDefaults
       "#{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
-      end
-    end
+
+
+    # @!group Deprecated/Untrustworthy Methods
 
     # @!attribute [r] we_have_a_pushy
     # Denotes whether (over the life of the program) any defaults have been marked pushy.
@@ -186,6 +194,12 @@ module CushionDefaults
       @we_have_a_pushy = true
     end
 
+    # Has no effect.
+    # @deprecated
+    attr_accessor :cushion_child_defaults_in_parent
+
+    # @!endgroup
+
     protected
 
     # Specifies the formatter for logger. Will not be called if a logger is assigned with +should_assign_formatter+ set to

data/lib/cushion_defaults/defaults_hash.rb

@@ -16,6 +16,8 @@ module CushionDefaults
     attr_reader :pushy_defaults
     # Set of defaults marked as polite.
     attr_reader :polite_defaults
+    # Set of defaults frozen
+    attr_reader :frozen_defaults
 
     # @param owner [Class] class for which this DefaultsHash holds the defaults.
     def initialize(owner)
@@ -24,8 +26,11 @@ module CushionDefaults
       @owner = owner
       @pushy_defaults = Set.new
       @polite_defaults = Set.new
+      @frozen_defaults = Set.new
     end
 
+    # @!group Custom/New Hash Methods
+
     # Allows addition of hashes. Works as expected.
     #
     # Note that this also enables +=.
@@ -47,35 +52,19 @@ module CushionDefaults
       self
     end
 
-    # Tell owner to add readers and writers for a newly-added key, as configured.
-    # @param key [#to_sym] name of new default
-    # @see Configuration#update_readers
-    # @see Configuration#update_writers
-    # @see ClassMethods#cushion
-    def add_methods_as_needed(key)
-      @owner.cushion_reader key.to_sym if CushionDefaults.conf.update_readers
-      @owner.cushion_writer key.to_sym if CushionDefaults.conf.update_writers
-    end
-
-    # Tell owner to remove methods for a newly-deleted key, as configured.
-    # @param key [#to_sym] name of deleted default
-    # @see Configuration#update_readers
-    # @see Configuration#update_writers
-    # @see ClassMethods#remove_reader
-    # @see ClassMethods#remove_writer
-    def remove_methods_as_needed(key)
-      @owner.remove_reader key.to_sym if CushionDefaults.conf.update_readers
-      @owner.remove_writer key.to_sym if CushionDefaults.conf.update_writers
-    end
-
     # Custom key/value set method. Prevents writing a default when a parent has it marked as pushy (and it is not
     # otherwise marked as polite), and it also tells @owner to add methods as needed (if writers or readers are to be
     # automatically added).
+    #
+    # @raise [FrozenDefaultError] if key is frozen
     def []=(key,val)
       key = key.to_sym
       if !@polite_defaults.include?(key) && pushy_in_parent?(key)
         raise ArgumentError, 'You cannot set a default value marked as pushy in a parent class without first marking it as polite.'
       end
+      if has_key?(key) && default_frozen?(key)
+        raise FrozenDefaultError.new(@owner, key), "#{@owner}.defaults[:#{key} is frozen!"
+      end
       unless has_ish_key?(key)
         add_methods_as_needed(key)
       end
@@ -86,9 +75,11 @@ module CushionDefaults
     # need to remove the key from @pushy_defaults and @polite_defaults if it exists.
     def delete(key)
       key = key.to_sym
+      return unless has_key? key
       remove_methods_as_needed(key)
       @pushy_defaults.delete(key)
       @polite_defaults.delete(key)
+      @frozen_defaults.delete(key)
       super(key)
       CushionDefaults.log("Default for #{key} in #{@owner} deleted.")
     end
@@ -101,6 +92,7 @@ module CushionDefaults
       end
       @pushy_defaults.clear
       @polite_defaults.clear
+      @frozen_defaults.clear
       super
       CushionDefaults.log("All defaults cleared for #{@owner}.", :info)
     end
@@ -137,6 +129,35 @@ module CushionDefaults
       end
     end
 
+    # @!group Frozen Defaults
+
+    # @return [boolean] true if the current default (not its value) is frozen, false otherwise.
+    def default_frozen? key
+      key = key.to_sym
+      @frozen_defaults.include? key
+    end
+
+    # Freezes the specified default (not its value).
+    #
+    # @see {#thaw_default!}
+    # @see {ClassMethods#freeze_default}
+    # @see {ClassMethods#deep_freeze_default}
+    # @return [Set] @frozen_defaults if key was not already present, nil otherwise
+    def freeze_default! key
+      @frozen_defaults.add? key
+    end
+
+    # Thaws the specified default (not its value).
+    #
+    # @see {#freeze_default!}
+    # @see {ClassMethods#thaw_default}
+    # @return [Set] @frozen_defaults if key was present, nil otherwise
+    def thaw_default! key
+      @frozen_defaults.delete? key
+    end
+
+    # @!group Pushy Defaults
+
     # Mark sym as pushy
     def pushy!(sym)
       CushionDefaults.conf.we_have_a_pushy!
@@ -178,6 +199,8 @@ module CushionDefaults
       !pushy?(sym)
     end
 
+    # @!group Debug
+
     # Returns the nearest class that has a default set for sym, or nil if no default is set for it.
     def where_is_that_default_again(sym)
       if has_key? sym
@@ -189,6 +212,29 @@ module CushionDefaults
       end
     end
 
+    # @!endgroup
+
+    # Tell owner to add readers and writers for a newly-added key, as configured.
+    # @param key [#to_sym] name of new default
+    # @see Configuration#update_readers
+    # @see Configuration#update_writers
+    # @see ClassMethods#cushion
+    def add_methods_as_needed(key)
+      @owner.cushion_reader key.to_sym if CushionDefaults.conf.update_readers
+      @owner.cushion_writer key.to_sym if CushionDefaults.conf.update_writers
+    end
+
+    # Tell owner to remove methods for a newly-deleted key, as configured.
+    # @param key [#to_sym] name of deleted default
+    # @see Configuration#update_readers
+    # @see Configuration#update_writers
+    # @see ClassMethods#remove_reader
+    # @see ClassMethods#remove_writer
+    def remove_methods_as_needed(key)
+      @owner.remove_reader key.to_sym if CushionDefaults.conf.update_readers
+      @owner.remove_writer key.to_sym if CushionDefaults.conf.update_writers
+    end
+
     protected
 
     # Return (unless cached) a reference to the superclass' +defaults+ hash.

data/lib/cushion_defaults/errors.rb

@@ -0,0 +1,20 @@
+module CushionDefaults
+  # Raised when a program attempts to overwrite a frozen default value.
+  class FrozenDefaultError < RuntimeError
+    # @return [Class] whose frozen default {#frozen_default_name} the program tried to override
+    attr_reader :originating_class
+    # @return [symbol] the frozen default in {#originating_class} that the program attempted to override
+    attr_reader :frozen_default_name
+
+    def initialize(orignating_class, frozen_default_name)
+      @originating_class = orignating_class
+      @frozen_default_name = frozen_default_name
+    end
+
+    # Include {#originating_class} and {#frozen_default_name} in #to_s
+    # @return [String]
+    def to_s
+      "#{@originating_class}.defaults[:#{@frozen_default_name} is frozen!"
+    end
+  end
+end

data/lib/cushion_defaults.rb

@@ -3,6 +3,7 @@ require 'set' # :nodoc:
 require 'cushion_defaults/configuration'
 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}.
@@ -27,7 +28,7 @@ require 'cushion_defaults/defaults_hash'
 module CushionDefaults
 
   # Version constant
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 
   # The path of the first file that +includes+ CushionDefaults.
   CALLING_PATH = File.expand_path(File.dirname($0)) + '/'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cushion_defaults
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Ryan Mitchell
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.11'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.11'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -54,6 +54,7 @@ files:
 - lib/cushion_defaults/class_methods.rb
 - lib/cushion_defaults/configuration.rb
 - lib/cushion_defaults/defaults_hash.rb
+- lib/cushion_defaults/errors.rb
 homepage: https://github.com/posgarou/cushion_defaults
 licenses:
 - MIT