1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
# Mixlib::Config
[](https://travis-ci.org/chef/mixlib-config)[](https://badge.fury.io/rb/mixlib-config)
Mixlib::Config provides a class-based configuration object, as used in Chef. To use in your project:
```ruby
require 'mixlib/config'
module MyConfig
extend Mixlib::Config
config_strict_mode true
default :first_value, 'something'
default :other_value, 'something_else'
end
```
You can use this to provide a configuration file for a user. For example, if you do this:
```ruby
MyConfig.from_file('~/.myconfig.rb')
```
A user could write a Ruby config file that looked like this:
```ruby
first_value 'hi'
second_value "#{first_value}! 10 times 10 is #{10*10}!"
```
Inside your app, you can check configuration values with this syntax:
```ruby
MyConfig.first_value # returns 'something'
MyConfig[:first_value] # returns 'something'
```
And you can modify configuration values with this syntax:
```ruby
MyConfig.first_value('foobar') # sets first_value to 'foobar'
MyConfig.first_value = 'foobar' # sets first_value to 'foobar'
MyConfig[:first_value] = 'foobar' # sets first_value to 'foobar'
```
## Nested Configuration
Often you want to be able to group configuration options to provide a common context. Mixlib::Config supports this thus:
```ruby
require 'mixlib/config'
module MyConfig
extend Mixlib::Config
config_context :logging do
default :base_filename, 'mylog'
default :max_log_files, 10
end
end
```
The user can write their config file in one of three formats:
### Method Style
```ruby
logging.base_filename 'superlog'
logging.max_log_files 2
```
### Block Style
Using this format the block is executed in the context, so all configurables on that context is directly accessible
```ruby
logging do
base_filename 'superlog'
max_log_files 2
end
```
### Block with Argument Style
Using this format the context is given to the block as an argument
```ruby
logging do |l|
l.base_filename = 'superlog'
l.max_log_files = 2
end
```
You can access these variables thus:
```ruby
MyConfig.logging.base_filename
MyConfig[:logging][:max_log_files]
```
## 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.
```ruby
require 'mixlib/config'
module MyConfig
extend Mixlib::Config
config_strict_mode true
default :verbosity, 1
default(:print_network_requests) { verbosity >= 2 }
default(:print_ridiculously_unimportant_stuff) { verbosity >= 10 }
end
```
This allows the user to quickly specify a number of values with one default, while still allowing them to override anything:
```ruby
verbosity 5
print_network_requests false
```
## 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`.
```ruby
require 'mixlib/config'
module MyConfig
extend Mixlib::Config
config_strict_mode true
default :filename, '~/output.txt'
configurable :server_url # configurable declares an option with no default value
config_context :logging do
default :base_name, 'log'
default :max_files, 20
end
end
```
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.
Enjoy!
## Contributing
For information on contributing to this project see <https://github.com/chef/chef/blob/master/CONTRIBUTING.md>
## License
- Copyright:: Copyright (c) 2009-2016 Chef Software, Inc.
- License:: Apache License, Version 2.0
```text
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.
|
