diff options
Diffstat (limited to 'trunk/lib/uri/mailto.rb')
-rw-r--r-- | trunk/lib/uri/mailto.rb | 266 |
1 files changed, 266 insertions, 0 deletions
diff --git a/trunk/lib/uri/mailto.rb b/trunk/lib/uri/mailto.rb new file mode 100644 index 0000000000..3a9d15318f --- /dev/null +++ b/trunk/lib/uri/mailto.rb @@ -0,0 +1,266 @@ +# +# = uri/mailto.rb +# +# Author:: Akira Yamada <akira@ruby-lang.org> +# License:: You can redistribute it and/or modify it under the same term as Ruby. +# Revision:: $Id$ +# + +require 'uri/generic' + +module URI + + # + # RFC2368, The mailto URL scheme + # + class MailTo < Generic + include REGEXP + + DEFAULT_PORT = nil + + COMPONENT = [ :scheme, :to, :headers ].freeze + + # :stopdoc: + # "hname" and "hvalue" are encodings of an RFC 822 header name and + # value, respectively. As with "to", all URL reserved characters must + # be encoded. + # + # "#mailbox" is as specified in RFC 822 [RFC822]. This means that it + # consists of zero or more comma-separated mail addresses, possibly + # including "phrase" and "comment" components. Note that all URL + # reserved characters in "to" must be encoded: in particular, + # parentheses, commas, and the percent sign ("%"), which commonly occur + # in the "mailbox" syntax. + # + # Within mailto URLs, the characters "?", "=", "&" are reserved. + + # hname = *urlc + # hvalue = *urlc + # header = hname "=" hvalue + HEADER_PATTERN = "(?:[^?=&]*=[^?=&]*)".freeze + HEADER_REGEXP = Regexp.new(HEADER_PATTERN, 'N').freeze + # headers = "?" header *( "&" header ) + # to = #mailbox + # mailtoURL = "mailto:" [ to ] [ headers ] + MAILBOX_PATTERN = "(?:#{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).freeze + # :startdoc: + + # + # == 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 + # + 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 + + # + # == 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. + # + 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 + + # The primary e-mail address of the URL, as a String + attr_reader :to + + # E-mail headers set by the URL, as an Array of Arrays + attr_reader :headers + + def check_to(v) + return true unless v + return true if v.size == 0 + + if OPAQUE !~ v || /\A#{MAILBOX_PATTERN}*\z/o !~ v + raise InvalidComponentError, + "bad component(expected opaque component): #{v}" + end + + return true + end + private :check_to + + def set_to(v) + @to = v + end + protected :set_to + + def to=(v) + check_to(v) + set_to(v) + v + end + + def check_headers(v) + return true unless v + return true if v.size == 0 + + if OPAQUE !~ v || + /\A(#{HEADER_PATTERN}(?:\&#{HEADER_PATTERN})*)\z/o !~ v + raise InvalidComponentError, + "bad component(expected opaque component): #{v}" + end + + return true + end + private :check_headers + + def set_headers(v) + @headers = [] + if v + v.scan(HEADER_REGEXP) do |x| + @headers << x.split(/=/o, 2) + end + end + end + protected :set_headers + + def headers=(v) + check_headers(v) + set_headers(v) + v + end + + 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 + + # 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" + # + 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 + alias to_rfc822text to_mailtext + end + + @@schemes['MAILTO'] = MailTo +end |