class Net::IMAP::Config

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

When creating a new client, all unhandled keyword arguments to Net::IMAP.new are delegated to Config.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 Config.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 Net::IMAP.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 Config.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.

Attributes

debug [RW]

The debug mode (boolean). The default value is false.

When debug is true:

Data sent to and received from the server will be logged.
ResponseParser will print warnings with extra detail for parse errors. _This may include recoverable errors._
ResponseParser makes extra assertions.

NOTE: Versioned default configs inherit debug from Config.global, and load_defaults will not override debug.

enforce_logindisabled [RW]

Controls the behavior of Net::IMAP#login when the LOGINDISABLED capability is present. When enforced, Net::IMAP will raise a LoginDisabledError when that capability is present.

(Support for LOGINDISABLED was added in v0.5.0.)

Valid options¶ ↑

false (original behavior, before support was added): Send the LOGIN command without checking for LOGINDISABLED.
:when_capabilities_cached: Enforce the requirement when Net::IMAP#capabilities_cached? is true, but do not send a CAPABILITY command to discover the capabilities.
true (default since v0.5): Only send the LOGIN command if the LOGINDISABLED capability is not present. When capabilities are unknown, Net::IMAP will automatically send a CAPABILITY command first before sending LOGIN.

idle_response_timeout [RW]

Seconds to wait until an IDLE response is received, after the client asks to leave the IDLE state.

See Net::IMAP#idle and Net::IMAP#idle_done.

The default value is 5 seconds.

open_timeout [RW]

Seconds to wait until a connection is opened.

If the IMAP object cannot open a connection within this time, it raises a Net::OpenTimeout exception.

See Net::IMAP.new.

The default value is 30 seconds.

responses_without_args [RW]

Alias for responses_without_block

responses_without_block [RW]

Controls the behavior of Net::IMAP#responses when called without any arguments (type or block).

Valid options¶ ↑

:silence_deprecation_warning (original behavior)

Returns the mutable responses hash (without any warnings). This is not thread-safe.

:warn (default since v0.5)

Prints a warning and returns the mutable responses hash. This is not thread-safe.

:frozen_dup (planned default for v0.6)

Returns a frozen copy of the unhandled responses hash, with frozen array values.

Note that calling IMAP#responses with a type and without a block is not configurable and always behaves like :frozen_dup.

(:frozen_dup config option was added in v0.4.17)

:raise

Raise an ArgumentError with the deprecation warning.

Note: responses_without_args is an alias for responses_without_block.

sasl_ir [RW]

Whether to use the SASL-IR extension when the server and SASL mechanism both support it. Can be overridden by the sasl_ir keyword parameter to Net::IMAP#authenticate.

(Support for SASL-IR was added in v0.4.0.)

Valid options¶ ↑

false (original behavior, before support was added): Do not use SASL-IR, even when it is supported by the server and the mechanism.
true (default since v0.4): Use SASL-IR when it is supported by the server and the mechanism.

Public Class Methods

Net::IMAP::Config[number] → versioned config

Net::IMAP::Config[symbol] → named config

Net::IMAP::Config[hash] → new frozen config

Net::IMAP::Config[config] → same config

Source

# File lib/net/imap/config.rb, line 153
def self.[](config)
  if    config.is_a?(Config)         then config
  elsif config.nil? && global.nil?   then nil
  elsif config.respond_to?(:to_hash) then new(global, **config).freeze
  else
    version_defaults.fetch(config) do
      case config
      when Numeric
        raise RangeError, "unknown config version: %p" % [config]
      when Symbol
        raise KeyError, "unknown config name: %p" % [config]
      else
        raise TypeError, "no implicit conversion of %s to %s" % [
          config.class, Config
        ]
      end
    end
  end
end

Given a version number, returns the default configuration for the target version. See Versioned defaults at Config.

Given a version name, returns the default configuration for the target version. See Named defaults at Config.

Given a Hash, creates a new frozen config which inherits from Config.global. Use Config.new for an unfrozen config.

Given a config, returns that same config.

default

Source

# File lib/net/imap/config.rb, line 128
def self.default; @default end

The default config, which is hardcoded and frozen.

global

Source

# File lib/net/imap/config.rb, line 131
def self.global; @global if defined?(@global) end

The global config object. Also available from Net::IMAP.config.

new (parent = Config.global, **attrs) { |self| ... }

Source

# File lib/net/imap/config.rb, line 295
def initialize(parent = Config.global, **attrs)
  super(parent)
  update(**attrs)
  yield self if block_given?
end

Creates a new config object and initialize its attribute with attrs.

If parent is not given, the global config is used by default.

If a block is given, the new config object is yielded to it.

Calls superclass method Net::IMAP::Config::AttrInheritance#new

version_defaults

Source

# File lib/net/imap/config.rb, line 134
def self.version_defaults; @version_defaults end

A hash of hard-coded configurations, indexed by version number or name.

Public Instance Methods

debug? → boolean

Source

# File lib/net/imap/config.rb, line 189

Alias for debug

load_defaults(version) → self

Source

# File lib/net/imap/config.rb, line 346
def load_defaults(version)
  [Numeric, Symbol, String].any? { _1 === version } or
    raise ArgumentError, "expected number or symbol, got %p" % [version]
  update(**Config[version].defaults_hash)
end

Resets the current config to behave like the versioned default configuration for version. parent will not be changed.

Some config attributes default to inheriting from their parent (which is usually Config.global) and are left unchanged, for example: debug.

See Versioned defaults at Config and Named defaults at Config.

to_h → hash

Source

# File lib/net/imap/config.rb, line 355
def to_h; data.members.to_h { [_1, send(_1)] } end

Returns all config attributes in a hash.

update(**attrs) → self

Source

# File lib/net/imap/config.rb, line 311
def update(**attrs)
  unless (bad = attrs.keys.reject { respond_to?(:"#{_1}=") }).empty?
    raise ArgumentError, "invalid config options: #{bad.join(", ")}"
  end
  attrs.each do send(:"#{_1}=", _2) end
  self
end

Assigns all of the provided attrs to this config, and returns self.

An ArgumentError is raised unless every key in attrs matches an assignment method on Config.

NOTE: update is not atomic. If an exception is raised due to an invalid attribute value, attrs may be partially applied.

with(**attrs) → config

with(**attrs) {|config| } → result

Source

# File lib/net/imap/config.rb, line 329
def with(**attrs)
  attrs.empty? and
    raise ArgumentError, "expected keyword arguments, none given"
  copy = new(**attrs)
  copy.freeze if frozen?
  block_given? ? yield(copy) : copy
end

Without a block, returns a new config which inherits from self. With a block, yields the new config and returns the block’s result.

If no keyword arguments are given, an ArgumentError will be raised.

If self is frozen, the copy will also be frozen.

Protected Instance Methods

defaults_hash

Source

# File lib/net/imap/config.rb, line 359
def defaults_hash
  to_h.reject {|k,v| DEFAULT_TO_INHERIT.include?(k) }
end