This way, a user could write a YAML config file that looked like this:

---
first_value: 'hi'second_value: 'goodbye'

or a JSON file that looks like this:

{
"first_value": "hi",
"second_value": "goodbye"
}

or a TOML file that looks like this:

first_value = "hi"second_value = "goodbye"

Please note: There is an inherent limitation in the logic you can do with YAML and JSON file. At this time, mixlib-config does not support ERB or other logic in YAML or JSON config (read "static content only").

Nested Configuration

Often you want to be able to group configuration options to provide a common context. Mixlib::Config supports this thus:

Method Style

Block Style

Using this format the block is executed in the context, so all configurables on that context is directly accessible

logging do
base_filename 'superlog'
max_log_files 2end

Block with Argument Style

Using this format the context is given to the block as an argument

logging do |l|
l.base_filename ='superlog'
l.max_log_files =2end

You can access these variables thus:

MyConfig.logging.base_filename
MyConfig[:logging][:max_log_files]

Lists of Contexts

For use cases where you need to be able to specify a list of things with identical configuration
you can define a context_config_list like so:

require'mixlib/config'moduleMyConfigextendMixlib::Config# The first argument is the plural word for your item, the second is the singular
config_context_list :apples, :appledo
default :species
default :color, 'red'
default :crispness, 10endend

With this definition everytime the apple is called within the config file it
will create a new item that can be configured with a block like so:

apple do
species 'Royal Gala'end
apple do
species 'Granny Smith'
color 'green'end

You can then iterate over the defined values in code:

MyConfig.apples.each do |apple|
puts"#{apple.species} are #{apple.color}"end# => Royal Gala are red# => Granny Smith are green

Hashes of Contexts

For use cases where you need to be able to specify a list of things with identical configuration
that are keyed to a specific value, you can define a context_config_hash like so:

require'mixlib/config'moduleMyConfigextendMixlib::Config# The first argument is the plural word for your item, the second is the singular
config_context_hash :apples, :appledo
default :species
default :color, 'red'
default :crispness, 10endend

Default Values

Mixlib::Config has a powerful default value facility. In addition to being able to specify explicit default values, you can even specify Ruby code blocks that will run if the config value is not set. This can allow you to build options whose values are based on other options.

Trying to call is_default? on a config context or a config which does not have a declared default is an error and will raise.

Strict Mode

Misspellings are a common configuration problem, and Mixlib::Config has an answer: config_strict_mode. Setting config_strict_mode to true will cause any misspelled or incorrect configuration option references to throw Mixlib::Config::UnknownConfigOptionError.

Now if a user types fielname "~/output-mine.txt" in their configuration file, it will toss an exception telling them that the option "fielname" is unknown. If you do not set config_strict_mode, the fielname option will be merrily set and the application just won't know about it.

Different config_contexts can have different strict modes; but they inherit the strict mode of their parent if you don't explicitly set it. So setting it once at the top level is sufficient. In the above example, logging.base_naem 'mylog' will raise an error.

In conclusion: always set config_strict_mode to true. You know you want to.

Testing and Reset

Testing your application with different sets of arguments can by simplified with reset. Call MyConfig.reset before each test and all configuration will be reset to its default value. There's no need to explicitly unset all your options between each run.

NOTE: if you have arrays of arrays, or other deep nesting, we suggest you use code blocks to set up your default values (default(:option) { [ [ 1, 2 ], [ 3, 4 ] ] }). Deep children will not always be reset to their default values.

Contributing

License

Copyright:: Copyright (c) 2009-2016 Chef Software, Inc.

License:: Apache License, Version 2.0

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.