Class: Mail::Address

Inherits:
Object
  • Object
show all
Defined in:
lib/mail/elements/address.rb

Overview

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) <[email protected]>')
a.format       #=> 'Mikel Lindsaar <[email protected]> (My email address)'
a.address      #=> '[email protected]'
a.display_name #=> 'Mikel Lindsaar'
a.local        #=> 'mikel'
a.domain       #=> 'test.lindsaar.net'
a.comments     #=> ['My email address']
a.to_s         #=> 'Mikel Lindsaar <[email protected]> (My email address)'

Instance Method Summary collapse

Constructor Details

#initialize(value = nil) ⇒ Address

Returns a new instance of Address.



25
26
27
28
29
30
31
32
 
# File 'lib/mail/elements/address.rb', line 25

def initialize(value = nil)
  if value.nil?
    @parsed = false
    @data = nil
  else
    parse(value)
  end
end

Instance Method Details

#address(output_type = :decode) ⇒ Object

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) <[email protected]>')
a.address #=> '[email protected]'



65
66
67
68
69
70
71
72
 
# File 'lib/mail/elements/address.rb', line 65

def address(output_type = :decode)
  parse unless @parsed
  if d = domain(output_type)
    "#{local(output_type)}@#{d}"
  else
    local(output_type)
  end
end

#address=(value) ⇒ Object

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

a = Address.new
a.address = 'Mikel Lindsaar (My email address) <[email protected]>'
a.address #=> '[email protected]'



79
80
81
 
# File 'lib/mail/elements/address.rb', line 79

def address=(value)
  parse(value)
end

#comments ⇒ Object

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

a = Address.new('Mikel Lindsaar (My email address) <[email protected]>')
a.comments #=> ['My email address']

b = Address.new('Mikel Lindsaar <[email protected]>')
b.comments #=> nil



132
133
134
135
136
137
138
139
140
 
# File 'lib/mail/elements/address.rb', line 132

def comments
  parse unless @parsed
  comments = get_comments
  if comments.nil? || comments.none?
    nil
  else
    comments.map { |c| c.squeeze(Constants::SPACE) }
  end
end

#decoded ⇒ Object 



173
174
175
 
# File 'lib/mail/elements/address.rb', line 173

def decoded
  format :decode
end

#display_name(output_type = :decode) ⇒ Object

Returns the display name of the email address passed in.

a = Address.new('Mikel Lindsaar (My email address) <[email protected]>')
a.display_name #=> 'Mikel Lindsaar'



87
88
89
90
91
 
# File 'lib/mail/elements/address.rb', line 87

def display_name(output_type = :decode)
  parse unless @parsed
  @display_name ||= get_display_name
  Encodings.decode_encode(@display_name.to_s, output_type) if @display_name
end

#display_name=(str) ⇒ Object

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

a = Address.new
a.address = '[email protected]'
a.display_name = 'Mikel Lindsaar'
a.format #=> 'Mikel Lindsaar <[email protected]>'



99
100
101
 
# File 'lib/mail/elements/address.rb', line 99

def display_name=( str )
  @display_name = str.nil? ? nil : str.dup # in case frozen
end

#domain(output_type = :decode) ⇒ Object

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) <[email protected]>')
a.domain #=> 'test.lindsaar.net'



118
119
120
121
 
# File 'lib/mail/elements/address.rb', line 118

def domain(output_type = :decode)
  parse unless @parsed
  Encodings.decode_encode(strip_all_comments(get_domain), output_type) if get_domain
end

#encoded ⇒ Object 



169
170
171
 
# File 'lib/mail/elements/address.rb', line 169

def encoded
  format :encode
end

#format(output_type = :decode) ⇒ Object

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) <[email protected]>')
a.format #=> 'Mikel Lindsaar <[email protected]> (My email address)'



47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/mail/elements/address.rb', line 47

def format(output_type = :decode)
  parse unless @parsed
  if @data.nil?
    Constants::EMPTY
  elsif name = display_name(output_type)
    [Utilities.quote_phrase(name), "<#{address(output_type)}>", format_comments].compact.join(Constants::SPACE)
  elsif a = address(output_type)
    [a, format_comments].compact.join(Constants::SPACE)
  else
    raw
  end
end

#group ⇒ Object 



177
178
179
 
# File 'lib/mail/elements/address.rb', line 177

def group
  @data && @data.group
end

#inspect ⇒ Object

Shows the Address object basic details, including the Address

a = Address.new('Mikel (My email) <[email protected]>')
a.inspect #=> "#<Mail::Address:14184910 Address: |Mikel <[email protected]> (My email)| >"



164
165
166
167
 
# File 'lib/mail/elements/address.rb', line 164

def inspect
  parse unless @parsed
  "#<#{self.class}:#{self.object_id} Address: |#{to_s}| >"
end

#local(output_type = :decode) ⇒ Object

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) <[email protected]>')
a.local #=> 'mikel'



108
109
110
111
 
# File 'lib/mail/elements/address.rb', line 108

def local(output_type = :decode)
  parse unless @parsed
  Encodings.decode_encode("#{@data.obs_domain_list}#{get_local.strip}", output_type) if get_local
end

#name ⇒ Object

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('[email protected] (Mikel Lindsaar)')
a.name #=> 'Mikel Lindsaar'



147
148
149
150
 
# File 'lib/mail/elements/address.rb', line 147

def name
  parse unless @parsed
  get_name
end

#raw ⇒ Object

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



36
37
38
 
# File 'lib/mail/elements/address.rb', line 36

def raw
  @data.raw
end

#to_s ⇒ Object

Returns the format of the address, or returns nothing

a = Address.new('Mikel Lindsaar (My email address) <[email protected]>')
a.format #=> 'Mikel Lindsaar <[email protected]> (My email address)'



156
157
158
159
 
# File 'lib/mail/elements/address.rb', line 156

def to_s
  parse unless @parsed
  format
end