google-cloud-core - Class Google::Cloud::Config (v1.6.1)

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.

Returns
  • (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!.

Parameter
  • show_warnings (boolean) (defaults to: true) — Whether to print warnings when a validation fails. Defaults to true.
Yields
  • (config)
Returns
  • (Config) — The constructed Config object.

#[]

def [](key) -> Object

Get the option or subconfig with the given name.

Parameter
  • key (Symbol, String) — The option or subconfig name
Returns
  • (Object) — The option value or subconfig object

#[]=

def []=(key, value)

Assign an option with the given name to the given value.

Parameters
  • 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.

Parameters
  • key (String, Symbol) — The name of the subconfig
  • config (Config) — A config object to attach here. If not provided, creates a new config.
Returns
  • (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 return true or false 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 an Enumerable. 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 or false, then either boolean value is considered valid. This is the same as enum: [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.
  • You may also provide the :allow_nil option, which, if set to true, alters any of the above validators to allow nil 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.

Parameters
  • key (String, Symbol) — The name of the option
  • initial (Object) — Initial value (defaults to nil)
  • opts (Hash) — Validation options
Returns
  • (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.

Parameter
  • key (Symbol) — The key to check for.
Returns
  • (Symbol, nil) — The alias target, or nil if not an alias.

#aliases!

def aliases!() -> Array<Symbol>

Return a list of alias names.

Returns
  • (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.

Parameter
  • key (Symbol, nil) — The key to delete. If omitted or nil, delete all fields and subconfigs.

#field?

def field?(key) -> boolean
Aliases

Check if the given key has been explicitly added as a field name.

Parameter
  • key (Symbol) — The key to check for.
Returns
  • (boolean)

#fields!

def fields!() -> Array<Symbol>

Return a list of explicitly added field names.

Returns
  • (Array<Symbol>) — a list of field names as symbols.

#inspect

def inspect() -> String
Alias Of: #to_s!

Returns a string representation of this configuration state, including subconfigs. Only explicitly added fields and subconfigs are included.

Returns
  • (String)

#option?

def option?(key) -> boolean
Alias Of: #value_set?

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.

Parameter
  • key (Symbol) — The key to check for.
Returns
  • (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.

Parameter
  • key (Symbol, nil) — The key to reset. If omitted or nil, recursively reset all fields and subconfigs.

#respond_to?

def respond_to?(key) -> boolean
Alias Of: #field?

Check if the given key has been explicitly added as a field name.

Parameter
  • key (Symbol) — The key to check for.
Returns
  • (boolean)

#subconfig?

def subconfig?(key) -> boolean

Check if the given key has been explicitly added as a subconfig name.

Parameter
  • key (Symbol) — The key to check for.
Returns
  • (boolean)

#subconfigs!

def subconfigs!() -> Array<Symbol>

Return a list of explicitly added subconfig names.

Returns
  • (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.

Returns
  • (Hash)

#to_s!

def to_s!() -> String
Aliases

Returns a string representation of this configuration state, including subconfigs. Only explicitly added fields and subconfigs are included.

Returns
  • (String)

#value_set?

def value_set?(key) -> boolean
Aliases

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.

Parameter
  • key (Symbol) — The key to check for.
Returns
  • (boolean)