# class URI::MailTo

RFC6068, the mailto URL scheme.

### Constants

COMPONENT

  An `Array` of the available components for `URI::MailTo`.

DEFAULT_PORT

  A Default port of nil for `URI::MailTo`.

### Attributes

headers [R]

E-mail headers set by the URL, as an `Array` of Arrays.

to [R]

The primary e-mail address of the URL, as a `String`.

### Public Class Methods

build (args)
Source

    # File lib/uri/mailto.rb, line 85
    def self.build(args)
      tmp = Util.make_components_hash(self, args)

      case tmp[:to]
      when Array
        tmp[:opaque] = tmp[:to].join(',')
      when String
        tmp[:opaque] = tmp[:to].dup
      else
        tmp[:opaque] = ''
      end

      if tmp[:headers]
        query =
          case tmp[:headers]
          when Array
            tmp[:headers].collect { |x|
              if x.kind_of?(Array)
                x[0] + '=' + x[1..-1].join
              else
                x.to_s
              end
            }.join('&')
          when Hash
            tmp[:headers].collect { |h,v|
              h + '=' + v
            }.join('&')
          else
            tmp[:headers].to_s
          end
        unless query.empty?
          tmp[:opaque] << '?' << query
        end
      end

      super(tmp)
    end

## Description¶ ↑

Creates a new `URI::MailTo` object from components, with syntax checking.

Components can be provided as an `Array` or `Hash`. If an `Array` is used, the components must be supplied as `[to, headers]`.

If a `Hash` is used, the keys are the component names preceded by colons.

The headers can be supplied as a pre-encoded string, such as `"subject=subscribe&cc=address"`, or as an `Array` of Arrays like `[['subject', 'subscribe'], ['cc', 'address']]`.

Examples:

    require 'uri'

    m1 = URI::MailTo.build(['joe@example.com', 'subject=Ruby'])
    m1.to_s  # => "mailto:joe@example.com?subject=Ruby"

    m2 = URI::MailTo.build(['john@example.com', [['Subject', 'Ruby'], ['Cc', 'jack@example.com']]])
    m2.to_s  # => "mailto:john@example.com?Subject=Ruby&Cc=jack@example.com"

    m3 = URI::MailTo.build({:to => 'listman@example.com', :headers => [['subject', 'subscribe']]})
    m3.to_s  # => "mailto:listman@example.com?subject=subscribe"

Calls superclass method `URI::Generic::build`
new (*arg)
Source

    # File lib/uri/mailto.rb, line 132
    def initialize(*arg)
      super(*arg)

      @to = nil
      @headers = []

      # The RFC3986 parser does not normally populate opaque
      @opaque = "?#{@query}" if @query && !@opaque

      unless @opaque
        raise InvalidComponentError,
          "missing opaque part for mailto URL"
      end
      to, header = @opaque.split('?', 2)
      # allow semicolon as a addr-spec separator
      # http://support.microsoft.com/kb/820868
      unless /\A(?:[^@,;]+@[^@,;]+(?:\z|[,;]))*\z/ =~ to
        raise InvalidComponentError,
          "unrecognised opaque part for mailtoURL: #{@opaque}"
      end

      if arg[10] # arg_check
        self.to = to
        self.headers = header
      else
        set_to(to)
        set_headers(header)
      end
    end

## Description¶ ↑

Creates a new `URI::MailTo` object from generic URL components with no syntax checking.

This method is usually called from `URI::parse`, which checks the validity of each component.

Calls superclass method `URI::Generic::new`

### Public Instance Methods

headers= (v)
Source

    # File lib/uri/mailto.rb, line 232
    def headers=(v)
      check_headers(v)
      set_headers(v)
      v
    end

Setter for headers `v`.

to= (v)
Source

    # File lib/uri/mailto.rb, line 200
    def to=(v)
      check_to(v)
      set_to(v)
      v
    end

Setter for to `v`.

to_mailtext ()
Source

    # File lib/uri/mailto.rb, line 268
        def to_mailtext
          to = URI.decode_www_form_component(@to)
          head = ''
          body = ''
          @headers.each do |x|
            case x[0]
            when 'body'
              body = URI.decode_www_form_component(x[1])
            when 'to'
              to << ', ' + URI.decode_www_form_component(x[1])
            else
              head << URI.decode_www_form_component(x[0]).capitalize + ': ' +
                URI.decode_www_form_component(x[1])  + "\n"
            end
          end

          "To: #{to}
    #{head}
    #{body}
    "
        end

Returns the RFC822 e-mail text equivalent of the URL, as a `String`.

Example:

    require 'uri'

    uri = URI.parse("mailto:ruby-list@ruby-lang.org?Subject=subscribe&cc=myaddr")
    uri.to_mailtext
    # => "To: ruby-list@ruby-lang.org\nSubject: subscribe\nCc: myaddr\n\n\n"

Also aliased as: to_rfc822text
to_rfc822text ()
Alias for: to_mailtext
to_s ()
Source

    # File lib/uri/mailto.rb, line 239
    def to_s
      @scheme + ':' +
        if @to
          @to
        else
          ''
        end +
        if @headers.size > 0
          '?' + @headers.collect{|x| x.join('=')}.join('&')
        else
          ''
        end +
        if @fragment
          '#' + @fragment
        else
          ''
        end
    end

Constructs `String` from `URI`.

### Protected Instance Methods

set_headers (v)
Source

    # File lib/uri/mailto.rb, line 221
    def set_headers(v)
      @headers = []
      if v
        v.split('&').each do |x|
          @headers << x.split(/=/, 2)
        end
      end
    end

Private setter for headers `v`.

set_to (v)
Source

    # File lib/uri/mailto.rb, line 194
    def set_to(v)
      @to = v
    end

Private setter for to `v`.

### Private Instance Methods

check_headers (v)
Source

    # File lib/uri/mailto.rb, line 208
    def check_headers(v)
      return true unless v
      return true if v.size == 0
      if HEADER_REGEXP !~ v
        raise InvalidComponentError,
          "bad component(expected opaque component): #{v}"
      end

      true
    end

Checks the headers `v` component against either

- HEADER_REGEXP

check_to (v)
Source

    # File lib/uri/mailto.rb, line 169
    def check_to(v)
      return true unless v
      return true if v.size == 0

      v.split(/[,;]/).each do |addr|
        # check url safety as path-rootless
        if /\A(?:%\h\h|[!$&-.0-;=@-Z_a-z~])*\z/ !~ addr
          raise InvalidComponentError,
            "an address in 'to' is invalid as URI #{addr.dump}"
        end

        # check addr-spec
        # don't s/\+/ /g
        addr.gsub!(/%\h\h/, URI::TBLDECWWWCOMP_)
        if EMAIL_REGEXP !~ addr
          raise InvalidComponentError,
            "an address in 'to' is invalid as uri-escaped addr-spec #{addr.dump}"
        end
      end

      true
    end

Checks the to `v` component.