Class: OpenCensus::Common::Config
- Inherits:
-
Object
- Object
- OpenCensus::Common::Config
- Defined in:
- lib/opencensus/common/config.rb
Overview
OpenCensus configuration class.
Configuration mechanism for OpenCensus libraries. A Config object contains a list of predefined keys, some of which are values and others of which are subconfigurations, i.e. categories. Option values are generally validated to ensure they are the correct type.
You generally access fields and subconfigs by calling accessor methods. Only explicitly defined fields have these accessor methods defined. Methods meant for "administration" such as adding options, are always named with a trailing "!" or "?" so they don't pollute the method namespace.
Example:
config = OpenCensus::Common::Config.new do |c|
c.add_option! :opt1, 10
c.add_option! :opt2, :one, enum: [:one, :two, :three]
c.add_option! :opt3, "hi", match: [String, Symbol]
c.add_option! :opt4, "hi", match: /^[a-z]+$/, allow_nil: true
c.add_config! :sub do |c2|
c2.add_option! :opt5, false
end
end
config.opt1 #=> 10
config.opt1 = 20 #=> 20
config.opt1 #=> 20
config.opt1 = "hi" #=> exception (only Integer allowed)
config.opt1 = nil #=> exception (nil not allowed)
config.opt2 #=> :one
config.opt2 = :two #=> :two
config.opt2 #=> :two
config.opt2 = :four #=> exception (not in allowed enum)
config.opt2 = nil #=> exception (nil not allowed)
config.opt3 #=> "hi"
config.opt3 = "hiho" #=> "hiho"
config.opt3 #=> "hiho"
config.opt3 = "HI" #=> exception (regexp check failed)
config.opt3 = nil #=> exception (nil not allowed)
config.opt4 #=> "yo"
config.opt4 = :yo #=> :yo (Strings and Symbols allowed)
config.opt4 #=> :yo
config.opt4 = 3.14 #=> exception (not in allowed types)
config.opt4 = nil #=> nil (nil explicitly allowed)
config.sub #=> <OpenCensus::Common::Config>
config.sub.opt5 #=> false
config.sub.opt5 = true #=> true (true and false allowed)
config.sub.opt5 #=> true
config.sub.opt5 = nil #=> exception (nil not allowed)
config.opt9 #=> exception (unknown key)
config.sub.opt9 #=> exception (unknown key)
Instance Method Summary collapse
-
#[](key) ⇒ Object
Get the option or subconfig with the given name.
-
#[]=(key, value) ⇒ Object
Assign an option with the given name to the given value.
-
#add_alias!(new_key, config: nil, key: nil) ⇒ Config
Add a field to this configuration that is an alias of some other object, which may be another field or another configuration.
-
#add_config!(key, &block) ⇒ Config
Add a subconfiguration field to this configuration.
-
#add_option!(key, initial = nil, opts = {}, &block) ⇒ Config
Add an option field to this configuration.
-
#delete!(key = nil) ⇒ Object
Remove the given key from the configuration.
-
#initialize {|_self| ... } ⇒ Config
constructor
Constructs a Configuration object.
-
#key?(key) ⇒ boolean
Check if this Config object has a key of the given name, regardless of whether it is an option or a subconfig.
-
#keys! ⇒ Array<Symbol>
Return a list of valid keys, including both options and subconfigs.
-
#option?(key) ⇒ boolean
Check if this Config object has an option of the given name.
-
#options! ⇒ Array<Symbol>
Return a list of valid option names.
-
#reset!(key = nil) ⇒ Object
Restore the original default value of the given key.
-
#subconfig?(key) ⇒ boolean
Check if this Config object has a subconfig of the given name.
-
#subconfigs! ⇒ Array<Symbol>
Return a list of valid subconfig names.
-
#to_h! ⇒ Hash
Returns a nested hash representation of this configuration state, including subconfigurations.
-
#to_s! ⇒ String
Returns a string representation of this configuration state.
Constructor Details
#initialize {|_self| ... } ⇒ Config
Constructs a Configuration object. If a block is given, yields self
to the block, which makes it convenient to initialize the structure by
making calls to #add_option!, #add_config!, and
#add_alias!.
85 86 87 88 |
# File 'lib/opencensus/common/config.rb', line 85 def initialize @fields = {} yield self if block_given? end |
Instance Method Details
#[](key) ⇒ Object
Get the option or subconfig with the given name.
289 290 291 292 293 294 295 296 297 298 299 300 |
# File 'lib/opencensus/common/config.rb', line 289 def [] key key = key.to_sym unless @fields.key? key raise ArgumentError, "Key #{key.inspect} does not exist" end field = @fields[key] if field.is_a? Config field else field.value end end |
#[]=(key, value) ⇒ Object
Assign an option with the given name to the given value.
270 271 272 273 274 275 276 277 278 279 280 281 |
# File 'lib/opencensus/common/config.rb', line 270 def []= key, value key = key.to_sym unless @fields.key? key raise ArgumentError, "Key #{key.inspect} does not exist" end field = @fields[key] if field.is_a? Config raise ArgumentError, "Key #{key.inspect} is a subconfig" end validate_value! key, field.validator, value field.value = value end |
#add_alias!(new_key, config: nil, key: nil) ⇒ Config
Add a field to this configuration that is an alias of some other object, which may be another field or another configuration. This will effectively become an alternate "path" to that same object.
The following cases are supported:
- Alias another configuration at this key by providing a
config
parameter but not akey
. The given configuration is effectively "attached" as a subconfiguration; both the original configuration path, and this new key, point to the same configuration object and share configuration data. - Alias another field of this current configuration by providing a
key
parameter but not aconfig
. The new key simply refers to the same object (which may be an option or a subconfig) as the original key, and shares the same data. - Alias another field or another configuration, by providing both a
config
parameter and akey
parameter.
193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 |
# File 'lib/opencensus/common/config.rb', line 193 def add_alias! new_key, config: nil, key: nil new_key = validate_new_key! new_key if config.nil? && key.nil? raise ArgumentError, "You must provide a config and/or key." end field = if key.nil? config else (config || self).raw_field! key end @fields[new_key] = field define_getter_method! new_key define_setter_method! new_key if field.is_a? Option self end |
#add_config!(key, &block) ⇒ Config
Add a subconfiguration field to this configuration.
You must provide a key, which becomes the method name that you use to navigate to the subconfig. Names may comprise only letters, numerals, and underscores, and must begin with a letter.
If you provide a block, the subconfig object is passed to the block, so you can easily add fields.
161 162 163 164 165 166 |
# File 'lib/opencensus/common/config.rb', line 161 def add_config! key, &block key = validate_new_key! key @fields[key] = Config.new(&block) define_getter_method! key self end |
#add_option!(key, initial = nil, opts = {}, &block) ⇒ Config
Add an option field to this configuration.
You must provide a key, which becomes the field name in this config. Field names may comprise only letters, numerals, and underscores, and must begin with a letter. This will create accessor methods for the new configuration key.
You may pass an initial value (which defaults to nil if not provided).
You may also specify how values are validated. Validation is defined as follows:
- If you provide a block or a
:validator
option, it is used as the validator. A proposed value is passed to the proc, and it should return true or false to indicate whether the value is acceptable. - If you provide a
:match
option, it is compared to the proposed value using the===
operator. You may, for example, provide a class, a regular expression, or a range. If you pass an array, the value is accepted if any of the elements match. - If you provide an
:enum
option, it should be anEnumerable
. A proposed value is accepted if it is included. - Otherwise if you do not provide any of the above options, then a
default validation strategy is inferred from the initial value:
- If the initial is
true
orfalse
, then either boolean value is considered valid. This is the same asenum: [true, false]
. - If the initial is
nil
, then any object is considered valid. - Otherwise, any object of the same class as the initial value is
considered valid. This is effectively the same as
match: initial.class
.
- If the initial is
- You may also provide the
:allow_nil
option, which, if set to true, alters any of the above validators to allownil
values. If the initial value isnil
but a specific validator is provided via:match
or:enum
, then:allow_nil
defaults to true, otherwise it defaults to false.
In many cases, you may find that the default validation behavior
(interpreted from the initial value) is sufficient. If you want to
accept any value, use match: Object
.
136 137 138 139 140 141 142 143 144 145 |
# File 'lib/opencensus/common/config.rb', line 136 def add_option! key, initial = nil, opts = {}, &block key = validate_new_key! key opts[:validator] = block if block validator = resolve_validator! initial, opts validate_value! key, validator, initial @fields[key] = Option.new initial, initial, validator define_getter_method! key define_setter_method! key self end |
#delete!(key = nil) ⇒ Object
Remove the given key from the configuration. If the key is omitted, deletes all keys.
Note the actual object being referenced is not touched. So if a deleted option is an alias of some other option, the other option will remain and retain the setting. Similarly, if a subconfig is referenced elsewhere, it will remain accessible from that other location.
249 250 251 252 253 254 255 256 257 258 259 260 261 262 |
# File 'lib/opencensus/common/config.rb', line 249 def delete! key = nil if key.nil? @fields.clear else key = key.to_sym unless @fields.key? key raise ArgumentError, "Key #{key.inspect} does not exist" end field = @fields.delete key singleton_class.send :remove_method, :"#{key}" singleton_class.send :remove_method, :"#{key}=" if field.is_a? Option end self end |
#key?(key) ⇒ boolean
Check if this Config object has a key of the given name, regardless of whether it is an option or a subconfig.
331 332 333 |
# File 'lib/opencensus/common/config.rb', line 331 def key? key @fields.key? key.to_sym end |
#keys! ⇒ Array<Symbol>
Return a list of valid keys, including both options and subconfigs.
358 359 360 |
# File 'lib/opencensus/common/config.rb', line 358 def keys! @fields.keys end |
#option?(key) ⇒ boolean
Check if this Config object has an option of the given name.
309 310 311 |
# File 'lib/opencensus/common/config.rb', line 309 def option? key @fields[key.to_sym].is_a? Option end |
#options! ⇒ Array<Symbol>
Return a list of valid option names.
340 341 342 |
# File 'lib/opencensus/common/config.rb', line 340 def @fields.keys.find_all { |key| @fields[key].is_a? Option } end |
#reset!(key = nil) ⇒ Object
Restore the original default value of the given key. If the key refers to a subconfiguration, restore its contents, recursively. If the key is omitted, restore the original defaults for all keys, including subconfigurations recursively.
219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 |
# File 'lib/opencensus/common/config.rb', line 219 def reset! key = nil if key.nil? @fields.each_key { |k| reset! k } else key = key.to_sym unless @fields.key? key raise ArgumentError, "Key #{key.inspect} does not exist" end field = @fields[key] if field.is_a? Config field.reset! else field.value = field.default end end self end |
#subconfig?(key) ⇒ boolean
Check if this Config object has a subconfig of the given name.
320 321 322 |
# File 'lib/opencensus/common/config.rb', line 320 def subconfig? key @fields[key.to_sym].is_a? Config end |
#subconfigs! ⇒ Array<Symbol>
Return a list of valid subconfig names.
349 350 351 |
# File 'lib/opencensus/common/config.rb', line 349 def subconfigs! @fields.keys.find_all { |key| @fields[key].is_a? Config } end |
#to_h! ⇒ Hash
Returns a nested hash representation of this configuration state, including subconfigurations.
386 387 388 389 390 391 392 |
# File 'lib/opencensus/common/config.rb', line 386 def to_h! result = {} @fields.each do |k, v| result[k] = v.is_a?(Config) ? v.to_h! : v.value end result end |
#to_s! ⇒ String
Returns a string representation of this configuration state.
367 368 369 370 371 372 373 374 375 376 377 378 |
# File 'lib/opencensus/common/config.rb', line 367 def to_s! elems = @fields.map do |k, v| vstr = if v.is_a? Config v.to_s! else v.value.inspect end " #{k}=#{vstr}" end "<Config#{elems.join}>" end |