class Mail::Address

Public Class Methods

new(value = nil) click to toggle source

Mail::Address handles all email addresses in Mail. It takes an email address string and parses it, breaking it down into its component parts and allowing you to get the address, comments, display name, name, local part, domain part and fully formatted address.

Mail::Address requires a correctly formatted email address per RFC2822 or RFC822. It handles all obsolete versions including obsolete domain routing on the local part.

a = Address.new('Mikel Lindsaar (My email address) <mikel@test.lindsaar.net>')
a.format       #=> 'Mikel Lindsaar <mikel@test.lindsaar.net> (My email address)'
a.address      #=> 'mikel@test.lindsaar.net'
a.display_name #=> 'Mikel Lindsaar'
a.local        #=> 'mikel'
a.domain       #=> 'test.lindsaar.net'
a.comments     #=> ['My email address']
a.to_s         #=> 'Mikel Lindsaar <mikel@test.lindsaar.net> (My email address)'
# File lib/mail/elements/address.rb, line 22
def initialize(value = nil)
  @output_type = :decode
  if value.nil?
    @parsed = false
    @data = nil
  else
    parse(value)
  end
end

Public Instance Methods

address() click to toggle source

Returns the address that is in the address itself. That is, the local@domain string, without any angle brackets or the like.

a = Address.new('Mikel Lindsaar (My email address) <mikel@test.lindsaar.net>')
a.address #=> 'mikel@test.lindsaar.net'
# File lib/mail/elements/address.rb, line 63
def address
  parse unless @parsed
  domain ? "#{local}@#{domain}" : local
end
address=(value) click to toggle source

Provides a way to assign an address to an already made Mail::Address object.

a = Address.new
a.address = 'Mikel Lindsaar (My email address) <mikel@test.lindsaar.net>'
a.address #=> 'mikel@test.lindsaar.net'
# File lib/mail/elements/address.rb, line 73
def address=(value)
  parse(value)
end
comments() click to toggle source

Returns an array of comments that are in the email, or an empty array if there are no comments

a = Address.new('Mikel Lindsaar (My email address) <mikel@test.lindsaar.net>')
a.comments #=> ['My email address']
# File lib/mail/elements/address.rb, line 122
def comments
  parse unless @parsed
  get_comments.map { |c| c.squeeze(SPACE) } unless get_comments.empty?
end
decoded() click to toggle source
# File lib/mail/elements/address.rb, line 159
def decoded
  @output_type = :decode
  format
end
display_name() click to toggle source

Returns the display name of the email address passed in.

a = Address.new('Mikel Lindsaar (My email address) <mikel@test.lindsaar.net>')
a.display_name #=> 'Mikel Lindsaar'
# File lib/mail/elements/address.rb, line 81
def display_name
  parse unless @parsed
  @display_name ||= get_display_name
  Encodings.decode_encode(@display_name.to_s, @output_type) if @display_name
end
display_name=( str ) click to toggle source

Provides a way to assign a display name to an already made Mail::Address object.

a = Address.new
a.address = 'mikel@test.lindsaar.net'
a.display_name = 'Mikel Lindsaar'
a.format #=> 'Mikel Lindsaar <mikel@test.lindsaar.net>'
# File lib/mail/elements/address.rb, line 93
def display_name=( str )
  @display_name = str.dup # in case frozen
end
domain() click to toggle source

Returns the domain part (the right hand side of the @ sign in the email address) of the address

a = Address.new('Mikel Lindsaar (My email address) <mikel@test.lindsaar.net>')
a.domain #=> 'test.lindsaar.net'
# File lib/mail/elements/address.rb, line 112
def domain
  parse unless @parsed
  Encodings.decode_encode(strip_all_comments(get_domain), @output_type) if get_domain
end
encoded() click to toggle source
# File lib/mail/elements/address.rb, line 154
def encoded
  @output_type = :encode
  format
end
format() click to toggle source

Returns a correctly formatted address for the email going out. If given an incorrectly formatted address as input, Mail::Address will do its best to format it correctly. This includes quoting display names as needed and putting the address in angle brackets etc.

a = Address.new('Mikel Lindsaar (My email address) <mikel@test.lindsaar.net>')
a.format #=> 'Mikel Lindsaar <mikel@test.lindsaar.net> (My email address)'
# File lib/mail/elements/address.rb, line 45
def format
  parse unless @parsed
  if @data.nil?
    EMPTY
  elsif display_name
    [quote_phrase(display_name), "<#{address}>", format_comments].compact.join(SPACE)
  elsif address
    [address, format_comments].compact.join(SPACE)
  else
    raw
  end
end
group() click to toggle source
# File lib/mail/elements/address.rb, line 164
def group
  @data && @data.group
end
inspect() click to toggle source

Shows the Address object basic details, including the Address

a = Address.new('Mikel (My email) <mikel@test.lindsaar.net>')
a.inspect #=> "#<Mail::Address:14184910 Address: |Mikel <mikel@test.lindsaar.net> (My email)| >"
# File lib/mail/elements/address.rb, line 149
def inspect
  parse unless @parsed
  "#<#{self.class}:#{self.object_id} Address: |#{to_s}| >"
end
local() click to toggle source

Returns the local part (the left hand side of the @ sign in the email address) of the address

a = Address.new('Mikel Lindsaar (My email address) <mikel@test.lindsaar.net>')
a.local #=> 'mikel'
# File lib/mail/elements/address.rb, line 102
def local
  parse unless @parsed
  Encodings.decode_encode("#{@data.obs_domain_list}#{get_local.strip}", @output_type) if get_local
end
name() click to toggle source

Sometimes an address will not have a display name, but might have the name as a comment field after the address. This returns that name if it exists.

a = Address.new('mikel@test.lindsaar.net (Mikel Lindsaar)')
a.name #=> 'Mikel Lindsaar'
# File lib/mail/elements/address.rb, line 132
def name
  parse unless @parsed
  get_name
end
raw() click to toggle source

Returns the raw input of the passed in string, this is before it is passed by the parser.

# File lib/mail/elements/address.rb, line 34
def raw
  @data.raw
end
to_s() click to toggle source

Returns the format of the address, or returns nothing

a = Address.new('Mikel Lindsaar (My email address) <mikel@test.lindsaar.net>')
a.format #=> 'Mikel Lindsaar <mikel@test.lindsaar.net> (My email address)'
# File lib/mail/elements/address.rb, line 141
def to_s
  parse unless @parsed
  format
end

Private Instance Methods

format_comments() click to toggle source
# File lib/mail/elements/address.rb, line 224
def format_comments
  if comments
    comment_text = comments.map {|c| escape_paren(c) }.join(SPACE).squeeze(SPACE)
    @format_comments ||= "(#{comment_text})"
  else
    nil
  end
end
get_comments() click to toggle source
# File lib/mail/elements/address.rb, line 241
def get_comments
  @data && @data.comments
end
get_display_name() click to toggle source
# File lib/mail/elements/address.rb, line 205
def get_display_name
  if @data.display_name
    str = strip_all_comments(@data.display_name.to_s)
  elsif @data.comments && @data.domain
    str = strip_domain_comments(format_comments)
  end
  str unless Utilities.blank?(str)
end
get_domain() click to toggle source
# File lib/mail/elements/address.rb, line 237
def get_domain
  @data && @data.domain
end
get_local() click to toggle source
# File lib/mail/elements/address.rb, line 233
def get_local
  @data && @data.local
end
get_name() click to toggle source
# File lib/mail/elements/address.rb, line 214
def get_name
  if display_name
    str = display_name
  elsif comments
    str = "(#{comments.join(SPACE).squeeze(SPACE)})"
  end

  unparen(str) unless Utilities.blank?(str)
end
parse(value = nil) click to toggle source
# File lib/mail/elements/address.rb, line 170
def parse(value = nil)
  @parsed = true
  @data = nil

  case value
  when Mail::Parsers::AddressStruct
    @data = value
  when String
    unless Utilities.blank?(value)
      address_list = Mail::Parsers::AddressListsParser.new.parse(value)
      @data = address_list.addresses.first
    end
  end
end
strip_all_comments(string) click to toggle source
# File lib/mail/elements/address.rb, line 185
def strip_all_comments(string)
  unless Utilities.blank?(comments)
    comments.each do |comment|
      string = string.gsub("(#{comment})", EMPTY)
    end
  end
  string.strip
end
strip_domain_comments(value) click to toggle source
# File lib/mail/elements/address.rb, line 194
def strip_domain_comments(value)
  unless Utilities.blank?(comments)
    comments.each do |comment|
      if @data.domain && @data.domain.include?("(#{comment})")
        value = value.gsub("(#{comment})", EMPTY)
      end
    end
  end
  value.to_s.strip
end