Class: Seahorse::Client::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/seahorse/client/configuration.rb

Overview

Configuration is used to define possible configuration options and then build read-only structures with user-supplied data.

## Adding Configuration Options

Add configuration options with optional default values. These are used when building configuration objects.

configuration = Configuration.new

configuration.add_option(:max_retries, 3)
configuration.add_option(:use_ssl, true)

cfg = configuration.build!
#=> #<struct max_retires=3 use_ssl=true>

## Building Configuration Objects

Calling #build! on a Configuration object causes it to return a read-only (frozen) struct. Options passed to #build! are merged on top of any default options.

configuration = Configuration.new
configuration.add_option(:color, 'red')

# default
cfg1 = configuration.build!
cfg1.color #=> 'red'

# supplied color
cfg2 = configuration.build!(color: 'blue')
cfg2.color #=> 'blue'

## Accepted Options

If you try to #build! a Configuration object with an unknown option, an ‘ArgumentError` is raised.

configuration = Configuration.new
configuration.add_option(:color)
configuration.add_option(:size)
configuration.add_option(:category)

configuration.build!(price: 100)
#=> raises an ArgumentError, :price was not added as an option

Defined Under Namespace

Classes: DefaultResolver, DynamicDefault

Constant Summary collapse

Defaults =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

Class.new(Array) do
  def each(&block)
    reverse.to_a.each(&block)
  end
end

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Configuration.



75
76
77
 
# File 'lib/seahorse/client/configuration.rb', line 75

def initialize
  @defaults = Hash.new { |h,k| h[k] = Defaults.new }
end

Instance Method Details

#add_option(name, default = nil, &block) ⇒ self

Adds a getter method that returns the named option or a default value. Default values can be passed as a static positional argument or via a block.

# defaults to nil
configuration.add_option(:name)

# with a string default
configuration.add_option(:name, 'John Doe')

# with a dynamic default value, evaluated once when calling #build!
configuration.add_option(:name, 'John Doe')
configuration.add_option(:username) do |config|
   config.name.gsub(/\W+/, '').downcase
end
cfg = configuration.build!
cfg.name #=> 'John Doe'
cfg.username #=> 'johndoe'

Parameters:

  • name (Symbol) —

    The name of the configuration option. This will be used to define a getter by the same name.

  • default (defaults to: nil) —

    The default value for this option. You can specify a default by passing a value, a ‘Proc` object or a block argument. Procs and blocks are evaluated when #build! is called.

Returns:

  • (self) 


106
107
108
109
110
 
# File 'lib/seahorse/client/configuration.rb', line 106

def add_option(name, default = nil, &block)
  default = DynamicDefault.new(Proc.new) if block_given?
  @defaults[name.to_sym] << default
  self
end

#build!(options = {}) ⇒ Struct

Constructs and returns a configuration structure. Values not present in ‘options` will default to those supplied via add option.

configuration = Configuration.new
configuration.add_option(:enabled, true)

cfg1 = configuration.build!
cfg1.enabled #=> true

cfg2 = configuration.build!(enabled: false)
cfg2.enabled #=> false

If you pass in options to ‘#build!` that have not been defined, then an `ArgumentError` will be raised.

configuration = Configuration.new
configuration.add_option(:enabled, true)

# oops, spelling error for :enabled
cfg = configuration.build!(enabld: true)
#=> raises ArgumentError

The object returned is a frozen ‘Struct`.

configuration = Configuration.new
configuration.add_option(:enabled, true)

cfg = configuration.build!
cfg.enabled #=> true
cfg[:enabled] #=> true
cfg['enabled'] #=> true

Parameters:

  • options (Hash) (defaults to: {}) —

    ({}) A hash of configuration options.

Returns:

  • (Struct) —

    Returns a frozen configuration ‘Struct`.



147
148
149
150
151
152
 
# File 'lib/seahorse/client/configuration.rb', line 147

def build!(options = {})
  struct = empty_struct
  apply_options(struct, options)
  apply_defaults(struct, options)
  struct
end