Class RMail::Address
In: lib/rmail/address.rb
Parent: Object

This class provides the following functionality:

Methods

<=>   address   comments   comments=   display_name   display_name=   domain   domain=   eql?   format   hash   local   local=   name   new   parse   to_str  

Included Modules

Comparable

Classes and Modules

Class RMail::Address::List
Class RMail::Address::Parser

Constants

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

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.

[Source]

# 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

[Source]

# File lib/rmail/address.rb, line 776
    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.

[Source]

# File lib/rmail/address.rb, line 74
    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

[Source]

# File lib/rmail/address.rb, line 213
    def address
      if @domain.nil?
        @local
      else
        @local + '@' + @domain
      end
    end

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

[Source]

# File lib/rmail/address.rb, line 158
    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.

See also comments, name

[Source]

# File lib/rmail/address.rb, line 167
    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

[Source]

# File lib/rmail/address.rb, line 126
    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

[Source]

# File lib/rmail/address.rb, line 134
    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.

[Source]

# File lib/rmail/address.rb, line 184
    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.

[Source]

# File lib/rmail/address.rb, line 190
    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.

[Source]

# File lib/rmail/address.rb, line 97
    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.

[Source]

# File lib/rmail/address.rb, line 223
    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).

[Source]

# File lib/rmail/address.rb, line 89
    def hash
      address.hash
    end

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

[Source]

# File lib/rmail/address.rb, line 104
    def local
      @local
    end

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

[Source]

# File lib/rmail/address.rb, line 110
    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=

[Source]

# File lib/rmail/address.rb, line 153
    def name
      @display_name || (@comments && @comments.last)
    end
to_str()

Alias for format

[Validate]