Extended maintenance of Ruby 1.9.3 ended on February 23, 2015. Read more

In Files

  • uri/mailto.rb

URI::MailTo

RFC2368, 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) click to toggle source

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'])
puts m1.to_s  ->  mailto:joe@example.com?subject=Ruby

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

m3 = URI::MailTo.build({:to => 'listman@example.com', :headers => [['subject', 'subscribe']]})
puts m3.to_s  ->  mailto:listman@example.com?subject=subscribe
 
               # File uri/mailto.rb, line 91
def self.build(args)
  tmp = Util::make_components_hash(self, args)

  if tmp[:to]
    tmp[:opaque] = tmp[:to]
  else
    tmp[:opaque] = ''
  end

  if tmp[:headers]
    tmp[:opaque] << '?'

    if tmp[:headers].kind_of?(Array)
      tmp[:opaque] << tmp[:headers].collect { |x|
        if x.kind_of?(Array)
          x[0] + '=' + x[1..-1].to_s
        else
          x.to_s
        end
      }.join('&')

    elsif tmp[:headers].kind_of?(Hash)
      tmp[:opaque] << tmp[:headers].collect { |h,v|
        h + '=' + v
      }.join('&')

    else
      tmp[:opaque] << tmp[:headers].to_s
    end
  end

  return super(tmp)
end
new(*arg) click to toggle source

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.

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

  @to = nil
  @headers = []

  if MAILTO_REGEXP =~ @opaque
    if arg[-1]
      self.to = $1
      self.headers = $2
    else
      set_to($1)
      set_headers($2)
    end

  else
    raise InvalidComponentError,
      "unrecognised opaque part for mailtoURL: #{@opaque}"
  end
end

Public Instance Methods

headers=(v) click to toggle source

setter for headers v

 
               # File uri/mailto.rb, line 219
def headers=(v)
  check_headers(v)
  set_headers(v)
  v
end
to=(v) click to toggle source

setter for to v

 
               # File uri/mailto.rb, line 184
def to=(v)
  check_to(v)
  set_to(v)
  v
end
to_mailtext() click to toggle source

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"

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

      return "To: #{to}
#{head}
#{body}
"
    end
Also aliased as: to_rfc822text
to_rfc822text() click to toggle source
Alias for: to_mailtext
to_s() click to toggle source

Constructs String from URI

 
               # File uri/mailto.rb, line 226
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

Protected Instance Methods

set_headers(v) click to toggle source

private setter for headers v

 
               # File uri/mailto.rb, line 208
def set_headers(v)
  @headers = []
  if v
    v.scan(HEADER_REGEXP) do |x|
      @headers << x.split(/=/o, 2)
    end
  end
end
set_to(v) click to toggle source

private setter for to v

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

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.