Class: Net::IMAP::Config

Config (available since v0.4.13) stores configuration options for ::Net::IMAP clients. The global configuration can be seen at either config or .global, and the client-specific configuration can be seen at #config.

When creating a new client, all unhandled keyword arguments to new are delegated to .new. Every client has its own config.

debug_client = Net::IMAP.new(hostname, debug: true)
quiet_client = Net::IMAP.new(hostname, debug: false)
debug_client.config.debug?  # => true
quiet_client.config.debug?  # => false

Inheritance

Configs have a parent config, and any attributes which have not been set locally will inherit the parent's value. Every client creates its own specific config. By default, client configs inherit from .global.

plain_client = Net::IMAP.new(hostname)
debug_client = Net::IMAP.new(hostname, debug: true)
quiet_client = Net::IMAP.new(hostname, debug: false)

plain_client.config.inherited?(:debug)  # => true
debug_client.config.inherited?(:debug)  # => false
quiet_client.config.inherited?(:debug)  # => false

plain_client.config.debug?  # => false
debug_client.config.debug?  # => true
quiet_client.config.debug?  # => false

# Net::IMAP.debug is delegated to Net::IMAP::Config.global.debug
Net::IMAP.debug = true
plain_client.config.debug?  # => true
debug_client.config.debug?  # => true
quiet_client.config.debug?  # => false

Net::IMAP.debug = false
plain_client.config.debug = true
plain_client.config.inherited?(:debug)  # => false
plain_client.config.debug?  # => true
plain_client.config.reset(:debug)
plain_client.config.inherited?(:debug)  # => true
plain_client.config.debug?  # => false

Versioned defaults

The effective default configuration for a specific x.y version of net-imap can be loaded with the config keyword argument to new. Requesting default configurations for previous versions enables extra backward compatibility with those versions:

client = Net::IMAP.new(hostname, config: 0.3)
client.config.sasl_ir                  # => false
client.config.responses_without_block  # => :silence_deprecation_warning

client = Net::IMAP.new(hostname, config: 0.4)
client.config.sasl_ir                  # => true
client.config.responses_without_block  # => :silence_deprecation_warning

client = Net::IMAP.new(hostname, config: 0.5)
client.config.sasl_ir                  # => true
client.config.responses_without_block  # => :warn

client = Net::IMAP.new(hostname, config: :future)
client.config.sasl_ir                  # => true
client.config.responses_without_block  # => :frozen_dup

The versioned default configs inherit certain specific config options from .global, for example #debug:

client = Net::IMAP.new(hostname, config: 0.4)
Net::IMAP.debug = false
client.config.debug?  # => false

Net::IMAP.debug = true
client.config.debug?  # => true

Use #load_defaults to globally behave like a specific version:

client = Net::IMAP.new(hostname)
client.config.sasl_ir              # => true
Net::IMAP.config.load_defaults 0.3
client.config.sasl_ir              # => false

Named defaults

In addition to x.y version numbers, the following aliases are supported:

[+:default+] An alias for :current.

>>>
*NOTE*: This is _not_ the same as Config.default.  It inherits some
attributes from Config.global, for example: #debug.

[+:current+] An alias for the current x.y version's defaults. [+:next+] The planned config for the next x.y version. [+:future+] The planned eventual config for some future x.y version.

For example, to disable all currently deprecated behavior:

client = Net::IMAP.new(hostname, config: :future)
client.config.response_without_args     # => :frozen_dup
client.responses.frozen?                # => true
client.responses.values.all?(&:frozen?) # => true

Thread Safety

NOTE: Updates to config objects are not synchronized for thread-safety.

What's here?

Config attributes

Timeouts and other limits

• #open_timeout: seconds to wait for connection to open or start TLS
• #idle_response_timeout: seconds to wait for IDLE command to complete
• max_response_size: Maximum allowed server response size.

Server capabilities

• #sasl_ir: Controls SASL-IR behavior for #authenticate.
• #enforce_logindisabled: Controls LOGINDISABLED behavior in Net::IMAP#login.
• max_non_synchronizing_literal: maximum bytesize for LITERAL / LITERAL- non-synchronizing literals.

Inherited defaults

Versioned defaults inherit these from {.global} and {#load_defaults} doesn't update them.

• {#debug} (aliased as {#debug?}): whether debug mode is enabled

Backward compatibility

These attributes will be removed by some future release.

• {#responses_without_block}: Controls the behavior of {Net::IMAP#responses} when called without any arguments (+type+ or {block}).
• {#parser_use_deprecated_uidplus_data}: Ignored since {v0.6.0}.
• {#parser_max_deprecated_uidplus_data_size}: Ignored since {v0.6.0}.

Getting a new or existing config

• {.global}: The global config, used as the default {#parent}.
• {.default}: The hardcoded frozen default config, and parent of {.global}.
• {.version_defaults}: Hard-coded frozen default configurations, indexed by version.
• {.[]}: Returns a config from {.version_defaults} or created by {.new}.
• {.new}: Return a new Config which inherits from a given {parent}.
• {#new}: Return a new Config which inherits from {self}.

Updating multiple attributes

• {#load_defaults}: Sets attributes to a given {version}'s default values.
• {#update}: Assigns multiple attribute values to {self}.
• {#reset}: Resets attributes to inherit from {#parent}.

Exporting multiple attributes

• {#to_h}: Return a hash with all attributes.
• {#inspect} (aliased as {#to_s}): Returns a string representation of overriden config attributes and the config inheritance chain.
• {#pretty_print}: Used by PP to create a string representation of all config attributes and the inheritance chain.

Inheritance inspection

• {#parent}: Returns the parent config object.
• {#inherited?}: Returns whether all attributes inherit from {#parent}.
• {#inherits_defaults?}: Returns whether all attributes inherit from a default config.
• {#overrides?}: Returns whether any attributes override the {#parent} value.