Class: RMail::Address

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/rmail/address.rb

Overview

This class provides the following functionality:

  • Parses RFC2822 address lists into a list of Address objects (see #parse).

  • Format Address objects as appropriate for insertion into email messages (see #format).

  • Allows manipulation of the various parts of the address (see #local=, #domain=, #display_name=, #comments=).

Defined Under Namespace

Classes: List, Parser

Constant Summary collapse

ATEXT = 
'[\w=!#$%&\'*+-?^\`{|}~]+'

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(string = nil) ⇒ Address

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.



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# 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

Class Method Details

.parse(string) ⇒ Object

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



788
789
790
 
# File 'lib/rmail/address.rb', line 788

def Address.parse(string)
  Parser.new(string).parse
end

Instance Method Details

#<=>(other) ⇒ Object

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.



73
74
75
76
77
78
79
80
81
82
 
# 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 ⇒ Object

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 [email protected]"

See also #format



212
213
214
215
216
217
218
 
# File 'lib/rmail/address.rb', line 212

def address
  if @domain.nil?
	@local
  else
	@local + '@' + @domain
  end
end

#comments ⇒ Object

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



157
158
159
 
# File 'lib/rmail/address.rb', line 157

def comments
  @comments
end

#comments=(comments) ⇒ Object

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



166
167
168
169
170
171
172
173
174
175
176
177
178
179
 
# 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 ⇒ Object

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

John Doe <[email protected]>

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

[email protected] (Bob Smith)

See also display_name=, #name



125
126
127
 
# File 'lib/rmail/address.rb', line 125

def display_name
  @display_name
end

#display_name=(str) ⇒ Object

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

See also display_name



133
134
135
136
137
138
139
 
# 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 ⇒ Object

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



183
184
185
 
# File 'lib/rmail/address.rb', line 183

def domain
  @domain
end

#domain=(domain) ⇒ Object

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



189
190
191
192
193
194
195
196
 
# 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) ⇒ Boolean

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.

Returns:

  • (Boolean)

Raises:

  • (TypeError) 


96
97
98
99
 
# 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 ⇒ Object Also known as: to_str

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



222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
 
# 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

#hash ⇒ Object

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



88
89
90
 
# File 'lib/rmail/address.rb', line 88

def hash
  address.hash
end

#local ⇒ Object

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



103
104
105
 
# File 'lib/rmail/address.rb', line 103

def local
  @local
end

#local=(l) ⇒ Object

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

Raises:

  • (ArgumentError) 


109
110
111
112
 
# File 'lib/rmail/address.rb', line 109

def local=(l)
  raise ArgumentError unless l.nil? || l.kind_of?(String)
  @local = l
end

#name ⇒ Object

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:

[email protected] (Bob Smith)

See also display_name, #comments, #comments=



152
153
154
 
# File 'lib/rmail/address.rb', line 152

def name
  @display_name || (@comments && @comments.last)
end