module Net::IMAP::DeprecatedClientOptions - net-imap: Ruby Standard Library Documentation

# module Net::IMAP::DeprecatedClientOptions

This module handles deprecated arguments to various `Net::IMAP` methods.

### Public Class Methods

Net::IMAP.new(host, **options) # standard keyword options click to toggle source
Net::IMAP.new(host, options) # obsolete hash options
Net::IMAP.new(host, port) # obsolete port argument
Net::IMAP.new(host, port, usessl, certs = nil, verify = true) # deprecated SSL arguments

Translates `Net::IMAP.new` arguments for backward compatibility.

#### Obsolete arguments¶ ↑

Use of obsolete arguments does not print a warning. Obsolete arguments will be deprecated by a future release.

If a second positional argument is given and it is a hash (or is convertible via `#to_hash`), it is converted to keyword arguments.

    # Obsolete:
    Net::IMAP.new("imap.example.com", options_hash)
    # Use instead:
    Net::IMAP.new("imap.example.com", **options_hash)

If a second positional argument is given and it is not a hash, it is converted to the `port` keyword argument.

    # Obsolete:
    Net::IMAP.new("imap.example.com", 114433)
    # Use instead:
    Net::IMAP.new("imap.example.com", port: 114433)

#### Deprecated arguments¶ ↑

Using deprecated arguments prints a warning. Convert to keyword arguments to avoid the warning. Deprecated arguments will be removed in a future release.

If `usessl` is false, `certs`, and `verify` are ignored. When it true, all three arguments are converted to the `ssl` keyword argument. Without `certs` or `verify`, it is converted to `ssl: true`.

    # DEPRECATED:
    Net::IMAP.new("imap.example.com", nil, true) # => prints a warning
    # Use instead:
    Net::IMAP.new("imap.example.com", ssl: true)

When `certs` is a path to a directory, it is converted to `ca_path: certs`.

    # DEPRECATED:
    Net::IMAP.new("imap.example.com", nil, true, "/path/to/certs") # => prints a warning
    # Use instead:
    Net::IMAP.new("imap.example.com", ssl: {ca_path: "/path/to/certs"})

When `certs` is a path to a file, it is converted to `ca_file: certs`.

    # DEPRECATED:
    Net::IMAP.new("imap.example.com", nil, true, "/path/to/cert.pem") # => prints a warning
    # Use instead:
    Net::IMAP.new("imap.example.com", ssl: {ca_file: "/path/to/cert.pem"})

When `verify` is `false`, it is converted to `verify_mode: OpenSSL::SSL::VERIFY_NONE`.

    # DEPRECATED:
    Net::IMAP.new("imap.example.com", nil, true, nil, false) # => prints a warning
    # Use instead:
    Net::IMAP.new("imap.example.com", ssl: {verify_mode: OpenSSL::SSL::VERIFY_NONE})

Calls superclass method

    # File net-imap-0.5.4/lib/net/imap/deprecated_client_options.rb, line 72
    def initialize(host, port_or_options = nil, *deprecated, **options)
      if port_or_options.nil? && deprecated.empty?
        super host, **options
      elsif options.any?
        # Net::IMAP.new(host, *__invalid__, **options)
        raise ArgumentError, "Do not combine deprecated and keyword arguments"
      elsif port_or_options.respond_to?(:to_hash) and deprecated.any?
        # Net::IMAP.new(host, options, *__invalid__)
        raise ArgumentError, "Do not use deprecated SSL params with options hash"
      elsif port_or_options.respond_to?(:to_hash)
        super host, **Hash.try_convert(port_or_options)
      elsif deprecated.empty?
        super host, port: port_or_options
      elsif deprecated.shift
        warn("DEPRECATED: Call Net::IMAP.new with keyword options",
             uplevel: 1, category: :deprecated)
        super host, port: port_or_options, ssl: create_ssl_params(*deprecated)
      else
        warn("DEPRECATED: Call Net::IMAP.new with keyword options",
             uplevel: 1, category: :deprecated)
        super host, port: port_or_options, ssl: false
      end
    end

### Public Instance Methods

starttls(**options) # standard click to toggle source
starttls(options = {}) # obsolete
starttls(certs = nil, verify = true) # deprecated

Translates `Net::IMAP#starttls` arguments for backward compatibility.

Support for `certs` and `verify` will be dropped in a future release.

See `::new` for interpretation of `certs` and `verify`.

Calls superclass method

    # File net-imap-0.5.4/lib/net/imap/deprecated_client_options.rb, line 106
    def starttls(*deprecated, **options)
      if deprecated.empty?
        super(**options)
      elsif options.any?
        # starttls(*__invalid__, **options)
        raise ArgumentError, "Do not combine deprecated and keyword options"
      elsif deprecated.first.respond_to?(:to_hash) && deprecated.length > 1
        # starttls(*__invalid__, **options)
        raise ArgumentError, "Do not use deprecated verify param with options hash"
      elsif deprecated.first.respond_to?(:to_hash)
        super(**Hash.try_convert(deprecated.first))
      else
        warn("DEPRECATED: Call Net::IMAP#starttls with keyword options",
             uplevel: 1, category: :deprecated)
        super(**create_ssl_params(*deprecated))
      end
    end

### Private Instance Methods

create_ssl_params(certs = nil, verify = true) click to toggle source

    # File net-imap-0.5.4/lib/net/imap/deprecated_client_options.rb, line 126
    def create_ssl_params(certs = nil, verify = true)
      params = {}
      if certs
        if File.file?(certs)
          params[:ca_file] = certs
        elsif File.directory?(certs)
          params[:ca_path] = certs
        end
      end
      params[:verify_mode] =
        verify ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
      params
    end