Module: Mixlib::Config

Defined in:
lib/mixlib/config.rb,
lib/mixlib/config/version.rb,
lib/mixlib/config/configurable.rb,
lib/mixlib/config/unknown_config_option_error.rb

Defined Under Namespace

Classes: Configurable, UnknownConfigOptionError

Constant Summary collapse

NOT_PASSED = 
Object.new
VERSION = 
"2.0.0"

Class Method Summary collapse

Instance Method Summary collapse

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method_symbol, *args) ⇒ Object

Allows for simple lookups and setting of config options via method calls on Mixlib::Config. If there any arguments to the method, they are used to set the value of the config option. Otherwise, it’s a simple get operation.

Parameters

method_symbol<Symbol>

The method called. Must match a config option.

*args

Any arguments passed to the method

Returns

value

The value of the config option.

Raises

<UnknownConfigOptionError>

If the config option does not exist and strict mode is on.



290
291
292
293
 
# File 'lib/mixlib/config.rb', line 290

def method_missing(method_symbol, *args)
  method_symbol = $1.to_sym if method_symbol.to_s =~ /(.+)=$/
  internal_get_or_set(method_symbol, *args)
end

Class Method Details

.extended(base) ⇒ Object 



27
28
29
30
31
32
33
34
35
 
# File 'lib/mixlib/config.rb', line 27

def self.extended(base)
  class << base; attr_accessor :configuration; end
  class << base; attr_accessor :configurables; end
  class << base; attr_accessor :config_contexts; end
  class << base; attr_accessor :config_parent; end
  base.configuration = Hash.new
  base.configurables = Hash.new
  base.config_contexts = Array.new
end

Instance Method Details

#[](config_option) ⇒ Object

Get the value of a config option

Parameters

config_option<Symbol>

The config option to return

Returns

value

The value of the config option

Raises

<UnknownConfigOptionError>

If the config option does not exist and strict mode is on.



66
67
68
 
# File 'lib/mixlib/config.rb', line 66

def [](config_option)
  internal_get(config_option.to_sym)
end

#[]=(config_option, value) ⇒ Object

Set the value of a config option

Parameters

config_option<Symbol>

The config option to set (within the [])

value

The value for the config option

Returns

value

The new value of the config option

Raises

<UnknownConfigOptionError>

If the config option does not exist and strict mode is on.



81
82
83
 
# File 'lib/mixlib/config.rb', line 81

def []=(config_option, value)
  internal_set(config_option.to_sym, value)
end

#config_attr_writer(method_symbol, &block) ⇒ Object

metaprogramming to ensure that the slot for method_symbol gets set to value after any other logic is run

Parameters

method_symbol<Symbol>

Name of the method (variable setter)

blk<Block>

logic block to run in setting slot method_symbol to value

value<Object>

Value to be set in config hash



146
147
148
 
# File 'lib/mixlib/config.rb', line 146

def config_attr_writer(method_symbol, &block)
  configurable(method_symbol).writes_value(&block)
end

#config_context(symbol, &block) ⇒ Object

Allows you to create a new config context where you can define new options with default values.

For example:

config_context :server_info do

configurable(:url).defaults_to("http://localhost")

end

Parameters

symbol<Symbol>: the name of the context block<Block>: a block that will be run in the context of this new config class.



209
210
211
212
213
214
215
216
217
218
219
220
 
# File 'lib/mixlib/config.rb', line 209

def config_context(symbol, &block)
  context = Class.new
  context.extend(::Mixlib::Config)
  context.config_parent = self
  config_contexts << context
  if block
    context.instance_eval(&block)
  end
  configurable(symbol).defaults_to(context).writes_value do |value|
    raise "config context #{symbol} cannot be modified"
  end
end

#config_strict_mode(value = NOT_PASSED) ⇒ Object

Gets or sets strict mode. When strict mode is on, only values which were specified with configurable(), default() or writes_with() may be retrieved or set. Getting or setting anything else will cause Mixlib::Config::UnknownConfigOptionError to be thrown.

If this is set to :warn, unknown values may be get or set, but a warning will be printed with Chef::Log.warn if this occurs.

Parameters

value<String>

pass this value to set strict mode [optional]

Returns

Current value of config_strict_mode

Raises

<ArgumentError>

if value is set to something other than true, false, or :warn



241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
 
# File 'lib/mixlib/config.rb', line 241

def config_strict_mode(value = NOT_PASSED)
  if value == NOT_PASSED
    if @config_strict_mode.nil?
      if config_parent
        config_parent.config_strict_mode
      else
        false
      end
    else
      @config_strict_mode
    end
  else
    self.config_strict_mode = value
  end
end

#config_strict_mode=(value) ⇒ Object

Sets strict mode. When strict mode is on, only values which were specified with configurable(), default() or writes_with() may be retrieved or set. All other values

If this is set to :warn, unknown values may be get or set, but a warning will be printed with Chef::Log.warn if this occurs.

Parameters

value<String>

pass this value to set strict mode [optional]

Raises

<ArgumentError>

if value is set to something other than true, false, or :warn



270
271
272
273
274
275
 
# File 'lib/mixlib/config.rb', line 270

def config_strict_mode=(value)
  if ![ true, false, :warn, nil ].include?(value)
    raise ArgumentError, "config_strict_mode must be true, false, nil or :warn"
  end
  @config_strict_mode = value
end

#configurable(symbol, &block) ⇒ Object

metaprogramming to set information about a config option. This may be used in one of two ways:

  1. Block-based:

configurable(:attr) do

defaults_to 4
writes_value { |value| 10 }

end

  1. Chain-based:

configurable(:attr).defaults_to(4).writes_value { |value| 10 }

Currently supported configuration:

defaults_to(value): value returned when configurable has no explicit value defaults_to BLOCK: block is run when the configurable has no explicit value writes_value BLOCK: block that is run to filter a value when it is being set

Parameters

symbol<Symbol>

Name of the config option

default_value<Object>

Default value [optional]

block<Block>

Logic block that calculates default value [optional]

Returns

The value of the config option.



185
186
187
188
189
190
191
192
193
194
 
# File 'lib/mixlib/config.rb', line 185

def configurable(symbol, &block)
  unless configurables[symbol]
    configurables[symbol] = Configurable.new(symbol)
    define_attr_accessor_methods(symbol)
  end
  if block
    block.call(configurables[symbol])
  end
  configurables[symbol]
end

#configure(&block) ⇒ Object

Pass Mixlib::Config.configure() a block, and it will yield itself

Parameters

block<Block>

A block that is called with self.configuration as the arugment.



52
53
54
 
# File 'lib/mixlib/config.rb', line 52

def configure(&block)
  block.call(self.configuration)
end

#default(symbol, default_value = nil, &block) ⇒ Object

metaprogramming to set the default value for the given config option

Parameters

symbol<Symbol>

Name of the config option

default_value<Object>

Default value (can be unspecified)

block<Block>

Logic block that calculates default value



156
157
158
 
# File 'lib/mixlib/config.rb', line 156

def default(symbol, default_value = nil, &block)
  configurable(symbol).defaults_to(default_value, &block)
end

#delete(symbol) ⇒ Object

Resets a config option to its default.

Parameters

symbol<Symbol>

Name of the config option



101
102
103
 
# File 'lib/mixlib/config.rb', line 101

def delete(symbol)
  self.configuration.delete(symbol)
end

#from_file(filename) ⇒ Object

Loads a given ruby file, and runs instance_eval against it in the context of the current object.

Raises an IOError if the file cannot be found, or is not readable.

Parameters

filename<String>

A filename to read from



44
45
46
 
# File 'lib/mixlib/config.rb', line 44

def from_file(filename)
  self.instance_eval(IO.read(filename), filename, 1)
end

#has_key?(key) ⇒ Boolean

Check if Mixlib::Config has a config option.

Parameters

key<Symbol>

The config option to check for

Returns

<True>

If the config option exists

<False>

If the config option does not exist

Returns:

  • (Boolean) 


93
94
95
 
# File 'lib/mixlib/config.rb', line 93

def has_key?(key)
  self.configuration.has_key?(key.to_sym)
end

#hash_dup ⇒ Object

Creates a shallow copy of the internal hash

Returns

result of Hash#dup



134
135
136
 
# File 'lib/mixlib/config.rb', line 134

def hash_dup
  self.configuration.dup
end

#keys ⇒ Object

Return the set of config hash keys

Returns

result of Hash#keys



126
127
128
 
# File 'lib/mixlib/config.rb', line 126

def keys
  self.configuration.keys
end

#merge!(hash) ⇒ Object

Merge an incoming hash with our config options

Parameters

hash<Hash>

The incoming hash

Returns

result of Hash#merge!



118
119
120
 
# File 'lib/mixlib/config.rb', line 118

def merge!(hash)
  self.configuration.merge!(hash)
end

#reset ⇒ Object

Resets all config options to their defaults.



106
107
108
109
 
# File 'lib/mixlib/config.rb', line 106

def reset
  self.configuration = Hash.new
  self.config_contexts.each { |config_context| config_context.reset }
end