class RMail::Address

This class provides the following functionality:

Constants

ATEXT

Public Class Methods

new(string = nil) click to toggle source

Create a new address. If the string argument is not nil, it is parsed for mail addresses and if one is found, it is used to initialize this object.

# File lib/rmail/address.rb, line 52
def initialize(string = nil)
  @local = @domain = @comments = @display_name = nil

  if string.kind_of?(String)
    addrs = Address.parse(string)
    if addrs.length > 0
      @local = addrs[0].local
      @domain = addrs[0].domain
      @comments = addrs[0].comments
      @display_name = addrs[0].display_name
    end
  else
    raise ArgumentError unless string.nil?
  end
end
parse(string) click to toggle source

Given a string, this function attempts to extract mailing addresses from it and returns an RMail::Address::List of those addresses (RMail::Address::List is a subclass of Array).

This is identical to using a RMail::Address::Parser directly like this:

RMail::Address::Parser.new(string).parse
# File lib/rmail/address.rb, line 788
def Address.parse(string)
  Parser.new(string).parse
end

Public Instance Methods

<=>(other) click to toggle source

Compare this address with another based on the email address portion only (any display name and comments are ignored). If the other object is not an RMail::Address, it is coerced into a string with its to_str method and then parsed into an RMail::Address object.

# File lib/rmail/address.rb, line 73
def <=>(other)
  if !other.kind_of?(RMail::Address)
    other = RMail::Address.new(other.to_str)
  end
  cmp = (@local || '') <=> (other.local || '')
  if cmp == 0
    cmp = (@domain || '') <=> (other.domain || '')
  end
  return cmp
end
address() click to toggle source

Returns the email address portion of the address (i.e. without a display name, angle addresses, or comments).

The string returned is not suitable for insertion into an e-mail. RFC2822 quoting rules are not followed. The raw address is returned instead.

For example, if the local part requires quoting, this function will not perform the quoting (see format for that). So this function can returns strings such as:

"address with no quoting@example.net"

See also format

# File lib/rmail/address.rb, line 212
def address
  if @domain.nil?
    @local
  else
    @local + '@' + @domain
  end
end
comments() click to toggle source

Returns the comments in this address as an array of strings.

# File lib/rmail/address.rb, line 157
def comments
  @comments
end
comments=(comments) click to toggle source

Set the comments for this address. The comments argument can be a string, or an array of strings. In either case, any existing comments are replaced.

See also comments, name

# File lib/rmail/address.rb, line 166
def comments=(comments)
  case comments
  when nil
    @comments = comments
  when Array
    @comments = comments
  when String
    @comments = [ comments ]
  else
    raise TypeError, "Argument to RMail::Address#comments= must be " +
      "String, Array or nil, was #{comments.type}."
  end
  @comments.freeze
end
display_name() click to toggle source

Returns the display name of this address. The display name is present only for “angle addr” style addresses such as:

John Doe <johnd@example.net>

In this case, the display name will be “John Doe”. In particular this old style address has no display name:

bobs@example.net (Bob Smith)

See also display_name=, name

# File lib/rmail/address.rb, line 125
def display_name
  @display_name
end
display_name=(str) click to toggle source

Assign a display name to this address. See display_name for a definition of what this is.

See also display_name

# File lib/rmail/address.rb, line 133
def display_name=(str)
  unless str.nil? || str.kind_of?(String)
    raise ArgumentError, 'not a string'
  end
  @display_name = str
  @display_name = nil if @display_name == ''
end
domain() click to toggle source

Retrieve to the domain portion of the mail address. This is the portion after the @ sign.

# File lib/rmail/address.rb, line 183
def domain
  @domain
end
domain=(domain) click to toggle source

Assign a domain name to this address. This is the portion after the @ sign. Any existing domain name will be changed.

# File lib/rmail/address.rb, line 189
def domain=(domain)
  @domain = if domain.nil? or domain == ''
              nil
            else
              raise ArgumentError unless domain.kind_of?(String)
              domain.strip
            end
end
eql?(other) click to toggle source

Return true if the two objects are equal. Do this based solely on the email address portion (any display name and comments are ignored). Fails if the other object is not an RMail::Address object.

# File lib/rmail/address.rb, line 96
def eql?(other)
  raise TypeError unless other.kind_of?(RMail::Address)
  @local.eql?(other.local) and @domain.eql?(other.domain)
end
format() click to toggle source

Return this address as a String formated as appropriate for insertion into a mail message.

# File lib/rmail/address.rb, line 222
def format
  display_name = if @display_name.nil?
                   nil
                 elsif @display_name =~ /^[-\/\w=!#\$%&'*+?^`{|}~ ]+$/
                   @display_name
                 else
                   '"' + @display_name.gsub(/["\\]/, '\\\\\&') + '"'
                 end
  local = if (@local !~ /^[-\w=!#\$%&'*+?^`{|}~\.\/]+$/ ||
              @local =~ /^\./ ||
              @local =~ /\.$/ ||
              @local =~ /\.\./)
            '"' + @local.gsub(/["\\]/, '\\\\\&') + '"'
          else
            @local
          end
  domain = if (!@domain.nil? and
               (@domain !~ /^[-\w=!#\$%&'*+?^`{|}~\.\/]+$/ ||
                @domain =~ /^\./ ||
                @domain =~ /\.$/ ||
                @domain =~ /\.\./))
           then
             '[' + if @domain =~ /^\[(.*)\]$/
                     $1
                   else
                     @domain
                   end.gsub(/[\[\]\\]/, '\\\\\&') + ']'
           else
             @domain
           end
  address = if domain.nil?
              local
            elsif !display_name.nil? or domain[-1] == ?]
              '<' + local + '@' + domain + '>'
            else
              local + '@' + domain
            end
  comments = nil
  comments = unless @comments.nil?
               @comments.collect { |c|
      '(' + c.gsub(/[()\\]/, '\\\\\&') + ')'
    }.join(' ')
             end
  [display_name, address, comments].compact.join(' ')
end
Also aliased as: to_str
hash() click to toggle source

Return a hash value for this address. This is based solely on the email address portion (any display name and comments are ignored).

# File lib/rmail/address.rb, line 88
def hash
  address.hash
end
local() click to toggle source

Retrieve the local portion of the mail address. This is the portion that precedes the @ sign.

# File lib/rmail/address.rb, line 103
def local
  @local
end
local=(l) click to toggle source

Assign the local portion of the mail address. This is the portion that precedes the @ sign.

# File lib/rmail/address.rb, line 109
def local=(l)
  raise ArgumentError unless l.nil? || l.kind_of?(String)
  @local = l
end
name() click to toggle source

Returns a best guess at a display name for this email address. This function first checks if the address has a true display name (see display_name) and returns it if so. Otherwise, if the address has any comments, the last comment will be returned.

In most cases, this will behave reasonably. For example, it will return “Bob Smith” for this address:

bobs@example.net (Bob Smith)

See also display_name, comments, comments=

# File lib/rmail/address.rb, line 152
def name
  @display_name || (@comments && @comments.last)
end
to_str()

Addresses can be converted into strings.

Alias for: format