Class: URI::MailTo

Inherits:
Generic show all
Includes:
REGEXP
Defined in:
lib/uri/mailto.rb

Overview

RFC2368, The mailto URL scheme

Constant Summary

DEFAULT_PORT =
nil
COMPONENT =
[ :scheme, :to, :headers ].freeze
HEADER_PATTERN =

hname = *urlc hvalue = *urlc header = hname "=" hvalue

"(?:[^?=&]*=[^?=&]*)".freeze
HEADER_REGEXP =
Regexp.new(HEADER_PATTERN, 'N').freeze
MAILBOX_PATTERN =

headers = "?" header *( "&" header ) to = #mailbox mailtoURL = "mailto:" [ to ] [ headers ]

"(?:#{PATTERN::ESCAPED}|[^(),%?=&])".freeze
MAILTO_REGEXP =
Regexp.new(" # :nodoc:
  \\A
  (#{MAILBOX_PATTERN}*?)                          (?# 1: to)
  (?:
    \\?
    (#{HEADER_PATTERN}(?:\\&#{HEADER_PATTERN})*)  (?# 2: headers)
  )?
  (?:
    \\#
    (#{PATTERN::FRAGMENT})                        (?# 3: fragment)
  )?
  \\z
", Regexp::EXTENDED, 'N').freeze

Constants included from REGEXP

REGEXP::ABS_PATH, REGEXP::ABS_URI, REGEXP::ABS_URI_REF, REGEXP::ESCAPED, REGEXP::FRAGMENT, REGEXP::HOST, REGEXP::OPAQUE, REGEXP::PORT, REGEXP::QUERY, REGEXP::REGISTRY, REGEXP::REL_PATH, REGEXP::REL_URI, REGEXP::REL_URI_REF, REGEXP::SCHEME, REGEXP::UNSAFE, REGEXP::URI_REF, REGEXP::USERINFO

Constants inherited from Generic

Generic::USE_REGISTRY

Constants included from URI

VERSION, VERSION_CODE

Instance Attribute Summary (collapse)

Attributes inherited from Generic

#fragment, #host, #opaque, #path, #port, #query, #registry, #scheme

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from Generic

#==, #absolute?, build2, #coerce, component, #component, default_port, #default_port, #eql?, #hash, #hierarchical?, #inspect, #merge, #merge!, #normalize, #normalize!, #password, #password=, #relative?, #route_from, #route_to, #select, use_registry, #user, #user=, #userinfo, #userinfo=

Methods included from URI

extract, join, parse, regexp, split

Methods included from Escape

#escape, #unescape

Constructor Details

- (MailTo) initialize(*arg)

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.



131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
# File 'lib/uri/mailto.rb', line 131

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

Instance Attribute Details

- (Object) headers

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



156
157
158
# File 'lib/uri/mailto.rb', line 156

def headers
  @headers
end

- (Object) to

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



153
154
155
# File 'lib/uri/mailto.rb', line 153

def to
  @to
end

Class Method Details

+ (Object) build(args)

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


88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
# File 'lib/uri/mailto.rb', line 88

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

Instance Method Details

- (Object) to_mailtext Also known as: to_rfc822text

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"


241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
# File 'lib/uri/mailto.rb', line 241

def to_mailtext
  to = URI::unescape(@to)
  head = ''
  body = ''
  @headers.each do |x|
    case x[0]
    when 'body'
      body = URI::unescape(x[1])
    when 'to'
      to << ', ' + URI::unescape(x[1])
    else
      head << URI::unescape(x[0]).capitalize + ': ' +
        URI::unescape(x[1])  + "\n"
    end
  end

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

- (Object) to_s



212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
# File 'lib/uri/mailto.rb', line 212

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