Module: CushionDefaults

Defined in:
lib/cushion_defaults.rb,
lib/cushion_defaults/errors.rb,
lib/cushion_defaults/class_methods.rb,
lib/cushion_defaults/configuration.rb,
lib/cushion_defaults/defaults_hash.rb

Overview

h2. The Basics

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@.

h2. Automatic Inclusion in Child Classes

When included in a superclass @Klass@, CushionDefaults automatically includes itself in all subclassses that subsequently subclass @Klass@.

Examples:

Inclusion in Child Class

class Klass
  include CushionDefaults
end
class SubKlass < Klass
  # includes CushionDefaults automatically
end

Defined Under Namespace

Modules: ClassMethods Classes: Configuration, DefaultsHash, FrozenDefaultError

Constant Summary collapse

VERSION =

Version constant

'0.6.0'
CALLING_PATH =

The path of the first file that includes CushionDefaults.

File.expand_path(File.dirname($0)) + '/'
CONFIG_LOCATION =

Location CushionDefaults looks here for an (optional) config file, as well as off of the CALLING_PATH.

"#{CALLING_PATH}config/cushion_defaults.yaml"

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.conf ⇒ Configuration

Return CushionDefaults’ Configuration object.

Returns:

See Also:



48
49
50
 
# File 'lib/cushion_defaults.rb', line 48

def self.conf
  @conf
end

.configuration ⇒ Configuration

Return CushionDefaults’ Configuration object.

Returns:

See Also:



55
56
57
 
# File 'lib/cushion_defaults.rb', line 55

def self.configuration
  @conf
end

.configure {|conf| ... } ⇒ Object

Yield the module’s configuration object for manipulation.

Examples:

Automatically add and remove cushion_readers and cushion_writers.

CushionDefaults.configure do |conf|
  conf.update_readers = true
  conf.update_writers = true
end

Configure CushionDefaults for testing or development

CushionDefaults.configure do |conf|
  conf.testing!
end

Yield Parameters:

See Also:



119
120
121
 
# File 'lib/cushion_defaults.rb', line 119

def self.configure
  yield(@conf)
end

.included(base) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Add class methods and set up an @defaults DefaultsHash when the module is included in a class. Called automatically.

If CushionDefaults::Configuration#auto_load_from_yaml, then it also searches for a YAML configuration file for the class in the by calling defaults_from_yaml.

Parameters:

  • base (Class) —

    class in which CushionDefaults is included



132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/cushion_defaults.rb', line 132

def self.included(base)

  log("CushionDefaults has been included in #{base}.")

  base.extend(ClassMethods)

  base.send :_set_up_cushion_method_sets

  if @conf.auto_load_from_yaml
    base.defaults_from_yaml
  else
    base.initialize_defaults_hash
  end
end

.log(str, level = :debug, caller_method_name = caller[0].to_s) ⇒ Object

Logs a message to the logger at CushionDefaults::Configuration#logger as long as CushionDefaults::Configuration#record_in_log is true.

Parameters:

  • str (String) —

    message to log. will have caller_method_name, level, and time automatically appended.

  • level (Symbol/int) (defaults to: :debug) —

    level to log at. Accepts integers (0 to 5) or one of the following symbols: :debug, :info, :warn, :error, :fatal, :unknown

  • caller_method_name (String) (defaults to: caller[0].to_s) —

    name of the method whose actions are being logged. If nil, the name is determined programmatically.



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/cushion_defaults.rb', line 65

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

  # If caller_method_name is nil, magically get the name of the calling method
  @conf.logger.progname = caller_method_name unless caller_method_name == ''

  case level
    when :debug, 0
      @conf.logger.debug {str}
    when :fatal, 4
      @conf.logger.fatal {str}
    when :error, 3
      @conf.logger.error {str}
    when :warn, 2
      @conf.logger.warn {str}
    when :info, 1
      @conf.logger.info {str}
    else
      @conf.logger.unknown {str}
  end
end

.nilish?(value) ⇒ boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Determine whether a value should be treated as nil or nil-like. If CushionDefaults::Configuration#ignore_attempts_to_set_nil is false, this method always returns false. If that setting is true, then it examines CushionDefaults::Configuration#blank_str_is_nil. If that setting is true, it returns true if value is nil or ” (like ActiveSupport’s @#blank?@)

Parameters:

  • value (Object) —

    value to examine

Returns:

  • (boolean) —

    as specified above



96
97
98
99
100
101
 
# File 'lib/cushion_defaults.rb', line 96

def self.nilish?(value)
  # @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

Instance Method Details

#crystallize_default(default_key, act_if_nilish = true) ⇒ Object

‘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.

Parameters:

  • default_key (#to_sym) —

    default to crystallize for this object

  • act_if_nilish (boolean) (defaults to: true) —

    if true, allows for nilish? checks. If false, #nilish? is not called at all.



178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/cushion_defaults.rb', line 178

def crystallize_default(default_key, act_if_nilish=true)
  default_key = default_key.to_sym
  # crystallize if either (1) there is no value specified for :default_key, or (2) there is a value specified, but we are
  # acting if a nilish value is specified and the value for :default_key is nilish.
  if !has_specified? default_key || (act_if_nilish && CushionDefaults.nilish?(instance_variable_get("@#{default_key}")))
    default_value = default(default_key)
    instance_variable_set("@#{default_key}", default_value.respond_to?(:call) ? default_value.call(self, default_key) : default_value)
  else
    log("Did not update #{default_key}")
  end
end

#default(sym) ⇒ Object

Returns the default value for sym, going up the chain of cascaded defaults.

Examples:

Default for :first

Klass.new.default(:first) == Klass.defaults[:first] # true

Parameters:

  • sym (Symbol) —

    the variable whose default value is desired.

Returns:

  • (Object) —

    the default specified for sym in self.class



158
159
160
 
# File 'lib/cushion_defaults.rb', line 158

def default(sym)
  defaults[sym]
end

#defaults ⇒ DefaultsHash

Get class DefaultsHash. If @x@ is a @Klass@, then @x#defaults@ returns @Klass.defaults@.

Returns:



149
150
151
 
# File 'lib/cushion_defaults.rb', line 149

def defaults
  self.class.defaults
end

#has_specified?(sym) ⇒ boolean

Wraps (in somewhat more convenient form) @Object#instance_variable_defined?@.

Parameters:

  • sym (#to_s) —

    String or coercable object that denotes the instance variable in question

Returns:

  • (boolean) —

    true if the instance variable denoted by sym is defined, false otherwise



165
166
167
 
# File 'lib/cushion_defaults.rb', line 165

def has_specified?(sym)
  instance_variable_defined?("@#{sym}")
end