class Net::IMAP::Config - net-imap: Ruby Standard Library Documentation

# 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  # => :raise

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 raise exceptions for all current deprecations:

    client = Net::IMAP.new(hostname, config: :future)
    client.responses  # raises an ArgumentError

## Thread Safety¶ ↑

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

### Constants

DEFAULT_TO_INHERIT

  Array of attribute names that are not loaded by `load_defaults`.

### 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]

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

responses_without_args=[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`.

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 click to toggle source
Net::IMAP::Config[symbol] → named config
Net::IMAP::Config[hash] → new frozen config
Net::IMAP::Config[config] → same config

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.

    # File net-imap-0.5.4/lib/net/imap/config.rb, line 151
    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

default() click to toggle source

The default config, which is hardcoded and frozen.

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

global() click to toggle source

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

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

new(parent = Config.global, **attrs) { |self| ... } click to toggle source

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`

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

version_defaults() click to toggle source

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

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

### Public Instance Methods

debug? → boolean click to toggle source

Alias for `debug`

    # File net-imap-0.5.4/lib/net/imap/config.rb, line 187

load_defaults(version) → self click to toggle source

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

    # File net-imap-0.5.4/lib/net/imap/config.rb, line 344
    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

to_h → hash click to toggle source

Returns all config attributes in a hash.

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

update(**attrs) → self click to toggle source

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.

    # File net-imap-0.5.4/lib/net/imap/config.rb, line 309
    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

with(**attrs) → config click to toggle source
with(**attrs) {|config| } → result

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.

    # File net-imap-0.5.4/lib/net/imap/config.rb, line 327
    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

### Protected Instance Methods

defaults_hash() click to toggle source

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