class RMail::Address
This class provides the following functionality:
Constants
- ATEXT
Public Class Methods
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.
# 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
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
# File lib/rmail/address.rb, line 788 def Address.parse(string) Parser.new(string).parse end
Public Instance Methods
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.
# 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
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 quoting@example.net"
See also format
# File lib/rmail/address.rb, line 212 def address if @domain.nil? @local else @local + '@' + @domain end end
Returns the comments in this address as an array of strings.
# File lib/rmail/address.rb, line 157 def comments @comments end
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.
# 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
Returns the display name of this address. The display name is present only for “angle addr” style addresses such as:
John Doe <johnd@example.net>
In this case, the display name will be “John Doe”. In particular this old style address has no display name:
bobs@example.net (Bob Smith)
See also display_name
=, name
# File lib/rmail/address.rb, line 125 def display_name @display_name end
Assign a display name to this address. See display_name
for a definition of what this is.
See also display_name
# 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
Retrieve to the domain portion of the mail address. This is the portion after the @
sign.
# File lib/rmail/address.rb, line 183 def domain @domain end
Assign a domain name to this address. This is the portion after the @
sign. Any existing domain name will be changed.
# 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
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.
# 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
Return this address as a String formated as appropriate for insertion into a mail message.
# 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
Return a hash value for this address. This is based solely on the email address portion (any display name and comments are ignored).
# File lib/rmail/address.rb, line 88 def hash address.hash end
Retrieve the local portion of the mail address. This is the portion that precedes the @
sign.
# File lib/rmail/address.rb, line 103 def local @local end
Assign the local portion of the mail address. This is the portion that precedes the @
sign.
# File lib/rmail/address.rb, line 109 def local=(l) raise ArgumentError unless l.nil? || l.kind_of?(String) @local = l end
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:
bobs@example.net (Bob Smith)
See also display_name
, comments
, comments=
# File lib/rmail/address.rb, line 152 def name @display_name || (@comments && @comments.last) end