Class: Mail::Address

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

Constant Summary

Constants included from Utilities

Utilities::CRLF, Utilities::CRLF_REGEX, Utilities::LF

Constants included from Constants

Constants::ASTERISK, Constants::ATOM_UNSAFE, Constants::B_VALUES, Constants::CAPITAL_M, Constants::COLON, Constants::CONTROL_CHAR, Constants::CR, Constants::CRLF, Constants::CR_ENCODED, Constants::EMPTY, Constants::ENCODED_VALUE, Constants::EQUAL_LF, Constants::FIELD_BODY, Constants::FIELD_LINE, Constants::FIELD_NAME, Constants::FIELD_PREFIX, Constants::FIELD_SPLIT, Constants::FULL_ENCODED_VALUE, Constants::FWS, Constants::HEADER_LINE, Constants::HEADER_SPLIT, Constants::HYPHEN, Constants::LF, Constants::LF_ENCODED, Constants::NULL_SENDER, Constants::PHRASE_UNSAFE, Constants::QP_SAFE, Constants::QP_UNSAFE, Constants::Q_VALUES, Constants::SPACE, Constants::TEXT, Constants::TOKEN_UNSAFE, Constants::UNDERSCORE, Constants::WSP

Instance Method Summary collapse

Methods included from Utilities

#atom_safe?, blank?, #bracket, #capitalize_field, #constantize, #dasherize, #dquote, #escape_paren, #map_lines, #map_with_index, #match_to_s, #paren, #quote_atom, #quote_phrase, #quote_token, to_crlf, to_lf, #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) <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)'


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

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

Instance Method Details

#addressObject

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'


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

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) <mikel@test.lindsaar.net>'
a.address #=> 'mikel@test.lindsaar.net'


76
77
78
# File 'lib/mail/elements/address.rb', line 76

def address=(value)
  parse(value)
end

#commentsObject

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


125
126
127
128
# File 'lib/mail/elements/address.rb', line 125

def comments
  parse unless @parsed
  get_comments.map { |c| c.squeeze(SPACE) } unless get_comments.empty?
end

#decodedObject



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

def decoded
  @output_type = :decode
  format
end

#display_nameObject

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'


84
85
86
87
88
# File 'lib/mail/elements/address.rb', line 84

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 = 'mikel@test.lindsaar.net'
a.display_name = 'Mikel Lindsaar'
a.format #=> 'Mikel Lindsaar <mikel@test.lindsaar.net>'


96
97
98
# File 'lib/mail/elements/address.rb', line 96

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

#domainObject

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'


115
116
117
118
# File 'lib/mail/elements/address.rb', line 115

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

#encodedObject



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

def encoded
  @output_type = :encode
  format
end

#formatObject

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


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

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

#groupObject



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

def group
  @data && @data.group
end

#inspectObject

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


152
153
154
155
# File 'lib/mail/elements/address.rb', line 152

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

#localObject

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'


105
106
107
108
# File 'lib/mail/elements/address.rb', line 105

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

#nameObject

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'


135
136
137
138
# File 'lib/mail/elements/address.rb', line 135

def name
  parse unless @parsed
  get_name
end

#rawObject

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



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

def raw
  @data.raw
end

#to_sObject

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


144
145
146
147
# File 'lib/mail/elements/address.rb', line 144

def to_s
  parse unless @parsed
  format
end