cushion_defaults 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a81419a81ff0cdcd46f6c56967342aa8c0663853
+  data.tar.gz: 32731179906c9bbe94c7e56a1e5716409214c548
+SHA512:
+  metadata.gz: 5f2c6ef61d48aa83e0ff9723c68e807a159926c5a74e10109b1f0354a9d4b877f7525b6f518add68e7668d0eb01f8d95c9e480fb434d01634b310defab80e180
+  data.tar.gz: 364a9f1df425222db45df3ee27c703ecb8401a4a075c53bb8e648ec8526fc7452f7ae8955c5437a87250cb04e1680775b753803d5388dacb4688c9996e3b64bd

data/lib/cushion_defaults/class_methods.rb

@@ -0,0 +1,189 @@
+module CushionDefaults
+  # A series of class methods to be plopped into any class that includes CushionDefaults.
+  module ClassMethods
+
+    # Getter-method for the +defaults+ +DefaultsHash+.
+    attr_reader :defaults
+
+    # Either set up or wipe @defaults. Should not usually be called directly.
+    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.delete_if { true }
+      else
+        @defaults = DefaultsHash.new(self)
+      end
+    end
+
+    # 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+.
+    # +replacement_hash+ :: a hash (of any length) whose keys/values are to be replace those in +defaults+.
+    def defaults=(replacement_hash)
+      # Need to copy over keys/vals to ensure @defaults remains a DefaultsHash and retains identity
+
+      @defaults.replace(replacement_hash)
+      @defaults.keys.each do |key|
+        unless key.is_a? Symbol
+          @defaults[key.to_sym] = @defaults[key].delete!
+        end
+      end
+    end
+
+    # Convenience method equivalent to +@defaults[key] = val+
+    # +key+ :: Key for new default. Is coerced into a +Symbol+.
+    # +val+ :: Default value for +key+.
+    def set_default(key, val)
+      @defaults[key.to_sym] = val
+    end
+
+    # Load in the defaults for this class from a yaml file.
+    # If +source_path+ is specified, yaml file is loaded from there.
+    # Otherwise, *CushionDefaults::YAML_PATH* is evaluated for the current class.
+    # By default, the yaml file for +Klass+ is expected to be at +config/klass.yaml+.
+    # +source_path+ :: File path to the yaml configuration file for this class
+    def defaults_from_yaml(source_path = nil)
+      if source_path
+        yaml_path = "#{CushionDefaults::configuration.yaml_source_full_path}#{source_path}.yaml"
+      else
+        yaml_path = CushionDefaults.conf.yaml_file_for(self)
+      end
+
+      yaml = YAML::load(File.open(yaml_path)) rescue {}
+
+      if yaml.empty? && CushionDefaults::configuration.whiny_yaml
+        warn "No YAML configuration for class #{self} found at #{yaml_path}"
+      end
+
+      initialize_defaults_hash
+      # If automatic readers and writers are enabled, this will set them up as a consequence.
+      yaml.each do |key, val|
+        @defaults[key.to_sym] = val
+      end
+    end
+
+    # Sets up a conditional getter method for each :sym in +syms+.
+    #
+    # Each getter method checks if its instance variable (:sym) is defined.  If it is, it returns that.  If not, it
+    # returns the default value.
+    #
+    # The getters are named according to the same format as +attr_reader+.
+    # +syms+ :: One or more +Symbol+s representing those instance variables that should have +conditional_getters+
+    def cushion_reader(*syms)
+      syms.each do |sym|
+        sym = sym.to_sym
+        sym_str = sym.to_s
+        if self_or_parent_instance_method?(sym)
+          warn "#{self} or a parent class already has what looks like a getter method for #{sym_str}"
+        end
+        define_method(sym) do
+          instance_variable_string = "@#{sym_str}"
+          if defaults.not_pushy?(sym) && instance_variable_defined?(instance_variable_string)
+            instance_variable_get(instance_variable_string)
+          else
+            defaults[sym]
+          end
+        end
+      end
+    end
+
+    def cushion_writer(*syms)
+      syms.each do |sym|
+        method_name = "#{sym}="
+        if self_or_parent_instance_method?(method_name)
+          warn "#{self} or a parent class already has what looks like a setter method for #{sym}"
+        end
+
+        instance_variable_string = "@#{sym}"
+
+        define_method(method_name) do |y|
+          if CushionDefaults.nilish? y
+            if CushionDefaults.conf.whiny_ignores
+              warn "You are attempting to set a nilish value for #{sym}. This will not be recorded, and any value set will be deleted."
+            end
+            remove_instance_variable(instance_variable_string) if instance_variable_defined?(instance_variable_string)
+          else
+            if defaults.pushy?(sym)
+              warn "You are setting a value for #{sym}, but this is a pushy default and this value will not be returned by any cushion_readers."
+            end
+            instance_variable_set(instance_variable_string, y)
+          end
+        end
+      end
+    end
+
+    def remove_reader(sym)
+      undef_method(sym) if self_has_method?(sym)
+    end
+
+    def remove_writer(sym)
+      write_sym = "#{sym}=".to_sym
+      undef_method(write_sym) if self_has_method?(write_sym)
+    end
+
+    # Sets up both +conditional_getters+ and normal +attr_writer+ for +syms+.
+    # +syms+ :: One or more symbols representing those instance variables that should have +conditional_getters+ and normal +attr_writers+.
+    def cushion(*syms)
+      cushion_reader(*syms)
+
+      cushion_writer(*syms)
+    end
+
+    # Defines +conditional_getters+ for all of this class' +defaults+.
+    #
+    # Only defines +conditional_getters+ for defaults for this class. 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+.
+    def cushion_readers_for_defaults
+      cushion_reader *defaults.keys
+    end
+
+    # Defines +conditional_getters+ and +attr_writers+ for all of this class' +defaults+.
+    #
+    # Only defines +conditional_getters+ 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+.
+    #
+    # See also:
+    # - #cushion
+    # - #cushion_readers_for_defaults
+    def cushion_defaults
+      cushion *defaults.keys
+    end
+
+    def make_pushy(*syms)
+      syms.each { |sym| @defaults.pushy!(sym) }
+    end
+
+    def make_polite(*syms)
+      syms.each { |sym| @defaults.not_pushy!(sym) }
+    end
+
+    # 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.
+    def inherited(inheritor)
+      inheritor.send :include, CushionDefaults
+    end
+
+    protected
+
+    # Check whether this class or any parent class includes the instance method denoted by +sym+
+    # +sym+ :: Symbol representing the method in question
+    def self_or_parent_instance_method?(sym)
+      instance_methods(true).include?(sym.to_sym)
+    end
+
+    def self_has_method?(sym)
+      instance_methods(false).include?(sym.to_sym)
+    end
+  end
+end

data/lib/cushion_defaults/configuration.rb

@@ -0,0 +1,56 @@
+# Effectively a singleton class, +Configuration+ keeps track of various configuration options for +CushionDefaults+.
+class Configuration # :nodoc:
+  # adapted from http://brandonhilkert.com/blog/ruby-gem-configuration-patterns/
+
+  attr_accessor :update_readers, :update_writers, :auto_load_from_yaml, :yaml_source_folder, :yaml_source_full_path, :whiny_yaml, :whiny_ignores, :cushion_child_defaults_in_parent, :ignore_attempts_to_set_nil, :blank_str_is_nil
+
+  # Initializes with +#defaults+
+  def initialize
+    defaults!
+  end
+
+  # Returns or computes the folder where class-specific yaml files are expected to reside.
+  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+.
+  #
+  # +loaded_config+ :: hash from which options will be derived
+  def from_hash(loaded_config)
+    loaded_config.each do |key, val|
+      instance_variable_set(key.to_sym, val) if instance_variable_defined? key.to_sym
+    end
+  end
+
+  # Defines 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.whiny_yaml = false
+    self.whiny_ignores = false
+    self.ignore_attempts_to_set_nil = true
+    self.blank_str_is_nil = true
+  end
+
+  def test_settings!
+    defaults!
+    self.whiny_yaml = true
+    self.whiny_ignores = true
+  end
+
+  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
+
+  def yaml_file_for(klass)
+    "#{CushionDefaults::configuration.yaml_source_full_path}#{underscore(klass.to_s)+'.yaml'}"
+  end
+end

data/lib/cushion_defaults/defaults_hash.rb

@@ -0,0 +1,165 @@
+module CushionDefaults
+  # 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.
+  class DefaultsHash < Hash
+    # +default_proc+ does most of the work.
+
+    # Must be initialized with an +owner+ class.
+
+    attr_reader :pushy_defaults, :polite_defaults
+
+    # +owner+ :: Class for which this +DefaultsHash+ contains 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
+      @owner = owner
+      @pushy_defaults = Set.new
+      @polite_defaults = Set.new
+    end
+
+    # Allow addition of hashes. Works as expected.
+    #
+    # 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+.
+    # +y+ :: Hash (of any length) whose key/values will be added to this +DefaultsHash+.
+    def +(y)
+      y.each {|key, val| self[key] = val}
+      self
+    end
+
+    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
+
+    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).
+    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
+      unless has_ish_key?(key)
+        add_methods_as_needed(key)
+      end
+      super(key, val)
+    end
+
+    # Custom delete method. We need to check whether or not we should delete the methods associated with the key, and we
+    # need to remove the key from @pushy_defaults and @polite_defaults if it exists.
+    def delete(key)
+      key = key.to_sym
+      remove_methods_as_needed(key)
+      @pushy_defaults.delete(key)
+      @polite_defaults.delete(key)
+      super(key)
+    end
+
+    # Custom clear method. We need to check whether or not we should delete the methods associated with the keys, and we
+    # need to wipe @pushy_defaults and @polite_defaults.
+    def clear
+      keys.each do |key|
+        remove_methods_as_needed(key.to_sym)
+      end
+      @pushy_defaults.clear
+      @polite_defaults.clear
+      super
+    end
+
+    # Custom clear method. We need to check whether or not we should delete the methods associated with the 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 also:
+    # - #ish_keys
+    def has_ish_key?(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
+        if super_defaults.respond_to? :has_ish_key?
+          super_defaults.has_ish_key?(key)
+        else
+          super_defaults.has_key?(key)
+        end
+      else
+        false
+      end
+    end
+
+    # Returns the keys of this class' +defaults+ as well as those of parent classes (if extant).
+    #
+    # See also:
+    # - #has_ish_key?
+    def ish_keys
+      if super_defaults
+        # super_defaults could be either a DefaultsHash or a regular Hash
+        (keys + (super_defaults.respond_to?(:ish_keys) ? super_defaults.ish_keys : super_defaults.keys)).uniq
+      else
+        keys
+      end
+    end
+
+    def pushy!(sym)
+      @pushy_defaults.add(sym)
+      @polite_defaults.delete(sym)
+    end
+
+    def not_pushy!(sym)
+      @pushy_defaults.delete(sym)
+      @polite_defaults.add(sym)
+    end
+
+    def pushy?(sym)
+      if @polite_defaults.include?(sym)
+        # white list has priority
+        false
+      elsif @pushy_defaults.include?(sym)
+        true
+      else
+        pushy_in_parent?(sym)
+      end
+    end
+
+    def pushy_in_parent?(sym)
+      if super_defaults.respond_to? :pushy?
+        super_defaults.pushy?(sym)
+      else
+        false
+      end
+    end
+
+    def not_pushy?(sym)
+      !pushy?(sym)
+    end
+
+
+    def where_is_that_default_again(sym)
+      if has_key? sym
+        @owner
+      elsif super_defaults.respond_to? :where_is_that_default_again
+        super_defaults.where_is_that_default_again sym
+      else
+        nil
+      end
+    end
+
+    protected
+
+    # Return (unless cached) a reference to the superclass' +defaults+ hash.
+    def super_defaults
+      @super_defaults ||= @owner.superclass.respond_to?(:defaults) ? @owner.superclass.defaults : {}
+    end
+  end
+end

data/lib/cushion_defaults.rb

@@ -0,0 +1,120 @@
+require 'YAML' # :nodoc:
+require 'set' # :nodoc:
+require 'cushion_defaults/configuration'
+require 'cushion_defaults/class_methods'
+require 'cushion_defaults/defaults_hash'
+
+# Base module. Should be included in any class that needs the functionality offered by +CushionDefaults+.
+#
+# When included in a superclass +Klass+, it automatically includes itself in all subclassses that subsequently extend
+# +Klass+.
+module CushionDefaults
+
+  VERSION = '0.0.0'
+
+  # CONFIG
+
+  # Location CushionDefaults looks for (optional) config file
+  CONFIG_LOCATION = 'config/cushion_defaults.yaml'
+
+  CALLING_PATH = File.expand_path(File.dirname($0)) + '/'
+
+  # If set to true, will automatically look at +YAML_PATH+ for each class that includes +CushionDefaults+ to try to
+  # load defaults from yaml file located at the result of +YAML_PROC+.  By default, this would be 'config/klass.yaml'.
+
+  # Relative folder path to yaml file used both automatically if +AUTO_LOAD_FROM_YAML+ and with unparam'd manual calls
+  # to +#defaults_from_yaml+.
+
+  # If true, will complain (i.e., throw a warning) if a yaml file cannot be found for a class, whether called because of
+  # AUTO_LOAD_FROM_YAML or via a manual call to +#defaults_from_yaml+.
+
+  # Create or return a cached (singleton) +Configuration+ object.
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.conf
+    self.configuration
+  end
+
+  def self.nilish?(y)
+    if conf.ignore_attempts_to_set_nil
+      y.nil? || (conf.blank_str_is_nil && y.eql?(''))
+    else
+      false
+    end
+  end
+
+  # Yield the configuration object to a block.
+  #
+  # The following configuration methods are available with the returned object:
+  # - #maintain_getters (boolean) :: If true, cushion_getters will be added/removed automatically as defaults are added/removed.
+  # - #maintain_writers (boolean) :: If true, cushion_setters will be added/removed automatically as defaults are added/removed.
+  # - #auto_load_from_yaml (boolean) :: Specifies whether we should attempt to automatically load defaults from class-specific yaml files. Def: true.
+  # - #yaml_source_folder (string)  :: Specifies the folder that contains class-specific yaml files. Def: 'config/cushion_defaults/'.
+  # - #yaml_source_full_path (string) :: Specifies the full path for class-specific yaml files. Def: +nil+.
+  # - #whiny_yaml (boolean) :: If true, a warning will be issued if a class-specific yaml file cannot be found. Def: false.
+  # - #whiny_ignores (boolean) :: If true, a warning will be issued when a variable is not set (or is undefined) due to being nilish. Def: false.
+  # - #cushion_child_defaults_in_parent (boolean) :: If true, then if SubKlass < Klass and getters/setters are added for a default specified in Subklass, then a getter that returns nil will be added to Klass as well. Def: false.
+  # - #ignore_attempts_to_set_nil (boolean) :: If true, then if a cushion_writer has been added for :x, then calling var.x = nil will instead remove_instance_variable(x) on var, effectively making it so that var.x will return the default value for x. Def: true.
+  # - #blank_str_is_nil (boolean) :: If true (and if #ignore_attempts_to_set_nil), the setter works like Rail's #blank method: if it isn't blank, the instance variable is set. Def: true.
+  def self.configure
+    yield(configuration)
+  end
+
+  if File.exists?(CONFIG_LOCATION)
+    t = File.open(CONFIG_LOCATION)
+  elsif File.exists?(configuration.yaml_source_folder + 'cushion_defaults.yaml')
+    t = File.open(configuration.yaml_source_folder + 'cushion_defaults.yaml')
+  else
+    t = nil
+  end
+
+  config.from_hash(YAML::load(t)) if t
+
+  # Add class methods and set up +DefaultsHash+ when the module is included in a class.
+  #
+  # If +AUTO_LOAD_FROM_YAML+, then it also searches for a yaml configuration file for the class in the path specified
+  # in the config variables.
+  def self.included(base)
+
+    base.extend(ClassMethods)
+
+    if configuration.auto_load_from_yaml
+      base.defaults_from_yaml
+    else
+      base.initialize_defaults_hash
+    end
+  end
+
+  # Convenience method.  If +x+ is a +Klass+, then +x#defaults+ returns +Klass.defaults+.
+  def defaults
+    self.class.defaults
+  end
+
+  # Convenience method.  Returns the default value for :sym, going up the chain of cascaded defaults.
+  # *sym* :: Symbol representing the variable whose default value is desired.
+  def default(sym)
+    defaults[sym]
+  end
+
+  # Purely a convenience method.
+  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+
+  # 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
+  # exsiting instances of the class.
+  def crystallize_default(key, act_if_nilish=true)
+    key = key.to_sym
+    # crystallize if either (1) there is no value specified for :key, or (2) there is a value specified, but we are
+    # acting if a nilish value is specified and the value for :key is nilish.
+    if !has_specified? key || (act_if_nilish && CushionDefaults.nilish?(instance_variable_get("@#{key}")))
+      default_value = default(key)
+      instance_variable_set("@#{key}", default_value)
+    end
+  end
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: cushion_defaults
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- Ryan Mitchell
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-12-05 00:00:00.000000000 Z
+dependencies: []
+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: []
+files:
+- lib/cushion_defaults.rb
+- lib/cushion_defaults/class_methods.rb
+- lib/cushion_defaults/configuration.rb
+- lib/cushion_defaults/defaults_hash.rb
+homepage: http://rubygems.org/gems/cushion_defaults
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.3
+signing_key: 
+specification_version: 4
+summary: An easy, flexible, and powerful alternative to hashes of defaults. Can be
+  used both in individual classes and in complex class hierarchies.
+test_files: []