Class: Mail::Address

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

Constant Summary

Constants included from Patterns

Patterns::ATOM_UNSAFE, Patterns::CONTROL_CHAR, Patterns::CRLF, Patterns::FIELD_BODY, Patterns::FIELD_LINE, Patterns::FIELD_NAME, Patterns::FIELD_SPLIT, Patterns::FWS, Patterns::HEADER_LINE, Patterns::PHRASE_UNSAFE, Patterns::QP_SAFE, Patterns::QP_UNSAFE, Patterns::TEXT, Patterns::TOKEN_UNSAFE, Patterns::WSP

Instance Method Summary collapse

Methods included from Utilities

#atom_safe?, #bracket, #capitalize_field, #constantize, #dasherize, #dquote, #escape_paren, #map_lines, #map_with_index, #match_to_s, #paren, #quote_atom, #quote_phrase, #quote_token, #token_safe?, #unbracket, #underscoreize, #unparen, #unquote, #uri_escape, #uri_parser, #uri_unescape

Constructor Details

#initialize(value = nil) ⇒ Address

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)'



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

def initialize(value = nil)
  @output_type = :decode
  @tree = nil
  @raw_text = value
  case
  when value.nil?
    @parsed = false
    return
  else
    parse(value)
  end
end

Instance Method Details

#address ⇒ 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]'



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

def address
  parse unless @parsed
  domain ? "#{local}@#{domain}" : local
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]'



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

def address=(value)
  parse(value)
end

#comments ⇒ Object

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



127
128
129
130
131
132
133
134
 
# File 'lib/mail/elements/address.rb', line 127

def comments
  parse unless @parsed
  if get_comments.empty?
    nil
  else
    get_comments.map { |c| c.squeeze(" ") }
  end
end

#decoded ⇒ Object 



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

def decoded
  @output_type = :decode
  format
end

#display_name ⇒ 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'



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

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) ⇒ 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]>'



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

def display_name=( str )
  @display_name = str
end

#domain ⇒ 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'



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

def domain
  parse unless @parsed
  strip_all_comments(get_domain) if get_domain
end

#encoded ⇒ Object 



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

def encoded
  @output_type = :encode
  format
end

#format ⇒ 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)'



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

def format
  parse unless @parsed
  case
  when tree.nil?
    ''
  when display_name
    [quote_phrase(display_name), "<#{address}>", format_comments].compact.join(" ")
  when address
    [address, format_comments].compact.join(" ")
  else
    tree.text_value
  end
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)| >"



158
159
160
161
 
# File 'lib/mail/elements/address.rb', line 158

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

#local ⇒ 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'



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

def local
  parse unless @parsed
  "#{obs_domain_list}#{get_local.strip}" 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'



141
142
143
144
 
# File 'lib/mail/elements/address.rb', line 141

def name
  parse unless @parsed
  get_name
end

#raw ⇒ Object

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



38
39
40
 
# File 'lib/mail/elements/address.rb', line 38

def raw
  @raw_text
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)'



150
151
152
153
 
# File 'lib/mail/elements/address.rb', line 150

def to_s
  parse unless @parsed
  format
end