Reference documentation and code samples for the google-cloud-core class Google::Cloud::Config.
Configuration mechanism for Google Cloud libraries. A Config object contains a list of predefined keys, some of which are values and others of which are subconfigurations, i.e. categories. Field access is generally validated to ensure that the field is defined, and when a a value is set, it is validated for the correct type. Warnings are printed when a validation fails.
You generally access fields and subconfigs by calling accessor methods.
Methods meant for "administration" such as adding options, are named
with a trailing "!" or "?" so they don't pollute the method namespace.
It is also possible to access a field using the []
operator.
Note that config objects inherit from BasicObject
. This means it does
not define many methods you might expect to find in most Ruby objects.
For example, to_s
, inspect
, is_a?
, instance_variable_get
, and so
forth.
Inherits
- BasicObject
Example
require "google/cloud/config" config = Google::Cloud::Config.create do |c| c.add_field! :opt1, 10 c.add_field! :opt2, :one, enum: [:one, :two, :three] c.add_field! :opt3, "hi", match: [String, Symbol] c.add_field! :opt4, "hi", match: /^[a-z]+$/, allow_nil: true c.add_config! :sub do |c2| c2.add_field! :opt5, false end end config.opt1 #=> 10 config.opt1 = 20 #=> 20 config.opt1 #=> 20 config.opt1 = "hi" #=> "hi" (but prints a warning) config.opt1 = nil #=> nil (but prints a warning) config.opt2 #=> :one config.opt2 = :two #=> :two config.opt2 #=> :two config.opt2 = :four #=> :four (but prints a warning) config.opt3 #=> "hi" config.opt3 = "hiho" #=> "hiho" config.opt3 #=> "hiho" config.opt3 = "HI" #=> "HI" (but prints a warning) config.opt4 #=> "yo" config.opt4 = :yo #=> :yo (Strings and Symbols allowed) config.opt4 #=> :yo config.opt4 = 3.14 #=> 3.14 (but prints a warning) config.opt4 = nil #=> nil (no warning: nil allowed) config.sub #=> <Google::Cloud::Config> config.sub.opt5 #=> false config.sub.opt5 = true #=> true (true and false allowed) config.sub.opt5 #=> true config.sub.opt5 = nil #=> nil (but prints a warning) config.opt9 = "hi" #=> "hi" (warning about unknown key) config.opt9 #=> "hi" (no warning: key now known) config.sub.opt9 #=> nil (warning about unknown key)
Methods
.config?
def self.config?(obj) -> boolean
Determines if the given object is a config. Useful because Config
does not define the is_a?
method.
- (boolean)
.create
def self.create(show_warnings: true) -> Config
Constructs a Config object. If a block is given, yields self
to the
block, which makes it convenient to initialize the structure by making
calls to add_field!
and add_config!
.
-
show_warnings (boolean) (defaults to: true) — Whether to print warnings when a
validation fails. Defaults to
true
.
- (config)
- (Config) — The constructed Config object.
#[]
def [](key) -> Object
Get the option or subconfig with the given name.
- key (Symbol, String) — The option or subconfig name
- (Object) — The option value or subconfig object
#[]=
def []=(key, value)
Assign an option with the given name to the given value.
- key (Symbol, String) — The option name
- value (Object) — The new option value
#add_alias!
def add_alias!(key, to_key)
Cause a key to be an alias of another key. The two keys will refer to the same field.
#add_config!
def add_config!(key, config = nil, &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 to the subconfig.
You may also pass in a config object that already exists. This will "attach" that configuration in this location.
- key (String, Symbol) — The name of the subconfig
- config (Config) — A config object to attach here. If not provided, creates a new config.
- (Config) — self for chaining
#add_field!
def add_field!(key, initial = nil, opts = {}, &block) -> Config
Add a value 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, which should returntrue
orfalse
to indicate whether the value is valid. - 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 valid 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.
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
.
- key (String, Symbol) — The name of the option
- initial (Object) — Initial value (defaults to nil)
- opts (Hash) — Validation options
- (Config) — self for chaining
#alias?
def alias?(key) -> Symbol, nil
Check if the given key has been explicitly added as an alias. If so, return the target, otherwise return nil.
- key (Symbol) — The key to check for.
- (Symbol, nil) — The alias target, or nil if not an alias.
#aliases!
def aliases!() -> Array<Symbol>
Return a list of alias names.
- (Array<Symbol>) — a list of alias names as symbols.
#delete!
def delete!(key = nil)
Remove the given key from the configuration, deleting any validation and value. If the key is omitted, delete all keys. If the key is an alias, deletes the alias but leaves the original.
-
key (Symbol, nil) — The key to delete. If omitted or
nil
, delete all fields and subconfigs.
#field?
def field?(key) -> boolean
Check if the given key has been explicitly added as a field name.
- key (Symbol) — The key to check for.
- (boolean)
#fields!
def fields!() -> Array<Symbol>
Return a list of explicitly added field names.
- (Array<Symbol>) — a list of field names as symbols.
#inspect
def inspect() -> String
Returns a string representation of this configuration state, including subconfigs. Only explicitly added fields and subconfigs are included.
- (String)
#option?
def option?(key) -> boolean
Check if the given key has been set in this object. Returns true if the key has been added as a normal field, subconfig, or alias, or if it has not been added explicitly but still has a value.
- key (Symbol) — The key to check for.
- (boolean)
#reset!
def reset!(key = nil)
Restore the original default value of the given key. If the key is omitted, restore the original defaults for all keys, and all keys of subconfigs, recursively.
-
key (Symbol, nil) — The key to reset. If omitted or
nil
, recursively reset all fields and subconfigs.
#respond_to?
def respond_to?(key) -> boolean
Check if the given key has been explicitly added as a field name.
- key (Symbol) — The key to check for.
- (boolean)
#subconfig?
def subconfig?(key) -> boolean
Check if the given key has been explicitly added as a subconfig name.
- key (Symbol) — The key to check for.
- (boolean)
#subconfigs!
def subconfigs!() -> Array<Symbol>
Return a list of explicitly added subconfig names.
- (Array<Symbol>) — a list of subconfig names as symbols.
#to_h!
def to_h!() -> Hash
Returns a nested hash representation of this configuration state, including subconfigs. Only explicitly added fields and subconfigs are included.
- (Hash)
#to_s!
def to_s!() -> String
Returns a string representation of this configuration state, including subconfigs. Only explicitly added fields and subconfigs are included.
- (String)
#value_set?
def value_set?(key) -> boolean
Check if the given key has been set in this object. Returns true if the key has been added as a normal field, subconfig, or alias, or if it has not been added explicitly but still has a value.
- key (Symbol) — The key to check for.
- (boolean)