Merge pull request #1858 from tk0miya/uri_mailto

stdlib: Add types for URI::MailTo

stdlib/uri/0/mailto.rbs

@@ -4,5 +4,89 @@ module URI
   # RFC6068, the mailto URL scheme.
   #
   class MailTo < Generic
+    EMAIL_REGEXP: Regexp
+
+    # <!--
+    #   rdoc-file=lib/uri/mailto.rb
+    #   - 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'])
+    #     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"
+    #
+    def self.build: (Array[String]) -> instance
+                  | ([String, Array[Array[String]]]) -> instance
+                  | (Hash[Symbol, String | Array[Array[String]]]) -> instance
+
+    # <!-- rdoc-file=lib/uri/mailto.rb -->
+    # E-mail headers set by the URL, as an Array of Arrays.
+    #
+    def headers: () -> Array[[String, String]]
+
+    # <!--
+    #   rdoc-file=lib/uri/mailto.rb
+    #   - headers=(v)
+    # -->
+    # Setter for headers `v`.
+    #
+    def headers=: (String) -> String
+
+    # <!-- rdoc-file=lib/uri/mailto.rb -->
+    # The primary e-mail address of the URL, as a String.
+    #
+    def to: () -> String
+
+    # <!--
+    #   rdoc-file=lib/uri/mailto.rb
+    #   - to=(v)
+    # -->
+    # Setter for to `v`.
+    #
+    def to=: (String) -> String
+
+    # <!--
+    #   rdoc-file=lib/uri/mailto.rb
+    #   - to_mailtext()
+    # -->
+    # 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: () -> String
+
+    # <!--
+    #   rdoc-file=lib/uri/mailto.rb
+    #   - to_rfc822text()
+    # -->
+    #
+    def to_rfc822text: () -> String
   end
 end

test/stdlib/uri/mailto_test.rb

@@ -0,0 +1,59 @@
+require_relative "../test_helper"
+require "uri"
+
+class URI::MailToSingletonTest < Test::Unit::TestCase
+  include TestHelper
+
+  library "uri"
+  testing "singleton(::URI::MailTo)"
+
+  def test_EMAIL_REGEXP
+    assert_const_type "::Regexp", "URI::MailTo::EMAIL_REGEXP"
+  end
+
+  def test_build
+    assert_send_type "(::Array[ ::String ]) -> ::URI::MailTo",
+                     URI::MailTo, :build, ["example@example.com", "subject=subject"]
+    assert_send_type "([ ::String, ::Array[ ::Array[ ::String ] ] ]) -> ::URI::MailTo",
+                     URI::MailTo, :build, ["example@example.com", [["subject", "subject"]]]
+    assert_send_type "(::Hash[ ::Symbol, ::String | ::Array[ ::Array[ ::String ] ] ]) -> ::URI::MailTo",
+                     URI::MailTo, :build, { to: "example@example.com", headers: "subject=subject" }
+  end
+end
+
+class URI::MailToTest < Test::Unit::TestCase
+  include TestHelper
+
+  library "uri"
+  testing "::URI::MailTo"
+
+  def test_headers
+    assert_send_type "() -> ::Array[[ ::String, ::String ]]",
+                     URI::MailTo.build(["example@example.com", "subject=subject"]), :headers
+  end
+
+  def test_headers=
+    assert_send_type "(::String) -> ::String",
+                     URI::MailTo.build(["example@example.com", "subject=subject"]), :headers=, "subject=subject2"
+  end
+
+  def test_to
+    assert_send_type "() -> ::String",
+                     URI::MailTo.build(["example@example.com", "subject=subject"]), :to
+  end
+
+  def test_to=
+    assert_send_type "(::String) -> ::String",
+                     URI::MailTo.build(["example@example.com", "subject=subject"]), :to=, "example2@example.com"
+  end
+
+  def test_to_mailtext
+    assert_send_type "() -> ::String",
+                     URI::MailTo.build(["example@example.com", "subject=subject"]), :to_mailtext
+  end
+
+  def test_to_rfc822text
+    assert_send_type "() -> ::String",
+                     URI::MailTo.build(["example@example.com", "subject=subject"]), :to_rfc822text
+  end
+end