# class Mail::Address

### Public Class Methods

new(value = nil) click to toggle source

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

    # File lib/mail/elements/address.rb, line 22
    def initialize(value = nil)
      @output_type = :decode
      if value.nil?
        @parsed = false
        @data = nil
      else
        parse(value)
      end
    end

### Public Instance Methods

address() click to toggle source

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'

    # File lib/mail/elements/address.rb, line 63
    def address
      parse unless @parsed
      domain ? "#{local}@#{domain}" : local
    end

address=(value) click to toggle source

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'

    # File lib/mail/elements/address.rb, line 73
    def address=(value)
      parse(value)
    end

comments() click to toggle source

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

    # File lib/mail/elements/address.rb, line 122
    def comments
      parse unless @parsed
      comments = get_comments
      if comments.nil? || comments.none?
        nil
      else
        comments.map { |c| c.squeeze(SPACE) }
      end
    end

decoded() click to toggle source

    # File lib/mail/elements/address.rb, line 164
    def decoded
      @output_type = :decode
      format
    end

display_name() click to toggle source

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'

    # File lib/mail/elements/address.rb, line 81
    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 ) click to toggle source

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

    # File lib/mail/elements/address.rb, line 93
    def display_name=( str )
      @display_name = str.nil? ? nil : str.dup # in case frozen
    end

domain() click to toggle source

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'

    # File lib/mail/elements/address.rb, line 112
    def domain
      parse unless @parsed
      Encodings.decode_encode(strip_all_comments(get_domain), @output_type) if get_domain
    end

encoded() click to toggle source

    # File lib/mail/elements/address.rb, line 159
    def encoded
      @output_type = :encode
      format
    end

format() click to toggle source

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

    # File lib/mail/elements/address.rb, line 45
    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

group() click to toggle source

    # File lib/mail/elements/address.rb, line 169
    def group
      @data && @data.group
    end

inspect() click to toggle source

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

    # File lib/mail/elements/address.rb, line 154
    def inspect
      parse unless @parsed
      "#<#{self.class}:#{self.object_id} Address: |#{to_s}| >"
    end

local() click to toggle source

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'

    # File lib/mail/elements/address.rb, line 102
    def local
      parse unless @parsed
      Encodings.decode_encode("#{@data.obs_domain_list}#{get_local.strip}", @output_type) if get_local
    end

name() click to toggle source

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'

    # File lib/mail/elements/address.rb, line 137
    def name
      parse unless @parsed
      get_name
    end

raw() click to toggle source

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

    # File lib/mail/elements/address.rb, line 34
    def raw
      @data.raw
    end

to_s() click to toggle source

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

    # File lib/mail/elements/address.rb, line 146
    def to_s
      parse unless @parsed
      format
    end

### Private Instance Methods

format_comments() click to toggle source

    # File lib/mail/elements/address.rb, line 229
    def format_comments
      if comments
        comment_text = comments.map {|c| escape_paren(c) }.join(SPACE).squeeze(SPACE)
        @format_comments ||= "(#{comment_text})"
      else
        nil
      end
    end

get_comments() click to toggle source

    # File lib/mail/elements/address.rb, line 246
    def get_comments
      @data && @data.comments
    end

get_display_name() click to toggle source

    # File lib/mail/elements/address.rb, line 210
    def get_display_name
      if @data && @data.display_name
        str = strip_all_comments(@data.display_name.to_s)
      elsif @data && @data.comments && @data.domain
        str = strip_domain_comments(format_comments)
      end
      str unless Utilities.blank?(str)
    end

get_domain() click to toggle source

    # File lib/mail/elements/address.rb, line 242
    def get_domain
      @data && @data.domain
    end

get_local() click to toggle source

    # File lib/mail/elements/address.rb, line 238
    def get_local
      @data && @data.local
    end

get_name() click to toggle source

    # File lib/mail/elements/address.rb, line 219
    def get_name
      if display_name
        str = display_name
      elsif comments
        str = "(#{comments.join(SPACE).squeeze(SPACE)})"
      end

      unparen(str) unless Utilities.blank?(str)
    end

parse(value = nil) click to toggle source

    # File lib/mail/elements/address.rb, line 175
    def parse(value = nil)
      @parsed = true
      @data = nil

      case value
      when Mail::Parsers::AddressStruct
        @data = value
      when String
        unless Utilities.blank?(value)
          address_list = Mail::Parsers::AddressListsParser.new.parse(value)
          @data = address_list.addresses.first
        end
      end
    end

strip_all_comments(string) click to toggle source

    # File lib/mail/elements/address.rb, line 190
    def strip_all_comments(string)
      unless Utilities.blank?(comments)
        comments.each do |comment|
          string = string.gsub("(#{comment})", EMPTY)
        end
      end
      string.strip
    end

strip_domain_comments(value) click to toggle source

    # File lib/mail/elements/address.rb, line 199
    def strip_domain_comments(value)
      unless Utilities.blank?(comments)
        comments.each do |comment|
          if @data.domain && @data.domain.include?("(#{comment})")
            value = value.gsub("(#{comment})", EMPTY)
          end
        end
      end
      value.to_s.strip
    end