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.

 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) 

  def 
  
 self 
 . 
 config? 
 ( 
 obj 
 ) 
  
 - 
>  
 boolean 
 

Determines if the given object is a config. Useful because Config does not define the is_a? method.

  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! .

  def 
  
 [] 
 ( 
 key 
 ) 
  
 - 
>  
 Object 
 

Get the option or subconfig with the given name.

  def 
  
 []= 
 ( 
 key 
 , 
  
 value 
 ) 
 

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

  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.

  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.

  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 .

  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.

  def 
  
 aliases! 
 () 
  
 - 
>  
 Array<Symbol> 
 

Return a list of alias names.

  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.

  def 
  
 field? 
 ( 
 key 
 ) 
  
 - 
>  
 boolean 
 

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

  def 
  
 fields! 
 () 
  
 - 
>  
 Array<Symbol> 
 

Return a list of explicitly added field names.

  def 
  
 inspect 
 () 
  
 - 
>  
 String 
 

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

  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.

  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.

  def 
  
 respond_to? 
 ( 
 key 
 ) 
  
 - 
>  
 boolean 
 

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

  def 
  
 subconfig? 
 ( 
 key 
 ) 
  
 - 
>  
 boolean 
 

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

  def 
  
 subconfigs! 
 () 
  
 - 
>  
 Array<Symbol> 
 

Return a list of explicitly added subconfig names.

  def 
  
 to_h! 
 () 
  
 - 
>  
 Hash 
 

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

  def 
  
 to_s! 
 () 
  
 - 
>  
 String 
 

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

  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.