Module: Configurable

Extended by:
ModuleMethods
Defined in:
lib/configurable.rb,
lib/configurable/utils.rb,
lib/configurable/delegate.rb,
lib/configurable/validation.rb,
lib/configurable/class_methods.rb,
lib/configurable/class_methods.rb,
lib/configurable/delegate_hash.rb,
lib/configurable/module_methods.rb,
lib/configurable/indifferent_access.rb

Overview

Configurable enables the specification of configurations within a class definition.

class ConfigClass
  include Configurable

  config :one, 'one'
  config :two, 'two'
  config :three, 'three'

end

c = ConfigClass.new
c.config.class         # => Configurable::DelegateHash
c.config               # => {:one => 'one', :two => 'two', :three => 'three'}

Instances have a config object that acts like a forwarding hash; configuration keys delegate to accessors while undeclared key-value pairs are stored internally:

c.config[:one] = 'ONE'
c.one                  # => 'ONE'

c.one = 1           
c.config               # => {:one => 1, :two => 'two', :three => 'three'}

c.config[:undeclared] = 'value'
c.config.store         # => {:undeclared => 'value'}

The writer for a configuration can be defined by providing a block to config.

The Validation module provides a number of common validation/transform blocks accessible through the class method ‘c’:

class SubClass < ConfigClass
  config(:one, 'one') {|v| v.upcase }
  config :two, 2, &c.integer
end

s = SubClass.new
s.config               # => {:one => 'ONE', :two => 2, :three => 'three'}

s.one = 'aNothER'             
s.one                  # => 'ANOTHER'

s.two = -2
s.two                  # => -2
s.two = "3"
s.two                  # => 3
s.two = nil            # !> ValidationError
s.two = 'str'          # !> ValidationError

Note that config blocks are defined in class-context and will have access to variables outside the block (as you would expect). For instance, these are analagous declarations:

class ClassConfig
  config :key, 'value' do |input|
    input.upcase
  end
end

class AnalagousClass
  block = lambda {|input| input.upcase}

  define_method(:key=) do |input|
    @key = block.call(input)
  end
end

To have the block literally define the writer, use the config_attr method. Blocks provided to config_attr will have instance context and must set the instance variable themselves.

class ConfigClass
  config_attr :key, 'value' do |input|
    @key = input.upcase
  end
end

Configurations are inherited and may be overridden in subclasses.

Attributes

Alternative reader and writer methods may be specified as config attributes. When alternate methods are specified, Configurable assumes the methods are declared elsewhere and will not define accessors.

class AlternativeClass
  include Configurable

  config_attr :sym, 'value', :reader => :get_sym, :writer => :set_sym

  def get_sym
    @sym
  end

  def set_sym(input)
    @sym = input.to_sym
  end
end

alt = AlternativeClass.new
alt.respond_to?(:sym)     # => false
alt.respond_to?(:sym=)    # => false

alt.config[:sym] = 'one'
alt.get_sym               # => :one

alt.set_sym('two')
alt.config[:sym]          # => :two

Idiosyncratically, true and false may also be provided as reader/writer values.

true

Same as using the defaults, accessors are defined.

false

Sets the default reader/writer but does not define the accessors (think ‘define reader/writer’ => false).

Nil is not allowed as a value.

Non-reader/writer attributes

Attributes provide metadata for how to use configurations in various contexts. In general, attributes can be used to set any metadata an application needs. A few attributes are used internally by Configurable.

Attribute
Use
set_default

When set to false, the delegate will not map a default value during bind. Specify when you manually initialize a config variable.

type

Specifies the type of option ConfigParser generates for this Delegate (ex: :switch, :flag, :list, :hidden)

desc

The description string used in the ConfigParser help

long

The long option (default: key)

short

The short option.

Defined Under Namespace

Modules: ClassMethods, IndifferentAccess, ModuleMethods, Utils, Validation Classes: Delegate, DelegateHash, OrderedHashPatch

Constant Summary collapse

DEFAULT_ATTRIBUTES =

A hash of (block, default attributes) for config blocks. The attributes for nil will be merged with those for the block.

Hash.new({})

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from ModuleMethods

included

Instance Attribute Details

#config ⇒ Object (readonly)

A DelegateHash bound to self



143
144
145
 
# File 'lib/configurable.rb', line 143

def config
  @config
end

Instance Method Details

#initialize(*args) ⇒ Object

Initializes config, if necessary, and then calls super. If initialize is overridden without calling super, be sure to call initialize_config manually within the new initialize method.



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

def initialize(*args)
  initialize_config unless instance_variable_defined?(:@config)
  super
end

#initialize_copy(orig) ⇒ Object

Reinitializes configurations in the copy such that the new object has it’s own set of configurations, separate from the original object.



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

def initialize_copy(orig)
  super
  initialize_config(orig.config.dup)
end

#reconfigure(overrides = {}) ⇒ Object

Reconfigures self with the given overrides. Only the specified configs are modified.

Returns self.



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

def reconfigure(overrides={})
  config.merge!(overrides)
  self
end