You are viewing documentation for version 2 of the AWS SDK for Ruby. Version 3 documentation can be found here.

Class: Seahorse::Client::Configuration

Inherits:
Object
  • Object
show all
Defined in:
aws-sdk-core/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

Instance Method Summary collapse

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 'aws-sdk-core/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 'aws-sdk-core/lib/seahorse/client/configuration.rb', line 147

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