module URI (Ruby 4.0 リファレンスマニュアル)

要約

URI を扱うためのモジュールです。

特異メソッド

decode_www_form(str, enc=Encoding::UTF_8) -> [[String, String]]Ruby 1.9.3 から[permalink][rdoc][edit]

文字列から URL-encoded form data をデコードします。

application/x-www-form-urlencoded 形式のデータをデコードし、 [key, value] という形の配列の配列を返します。

enc で指定したエンコーディングの文字列が URL エンコードされたものとみなし、エンコーディングを付加します。

このメソッドは https://url.spec.whatwg.org/#concept-urlencoded-parser にもとづいて実装されています。そのため「&」区切りのみに対応していて、「;」区切りには対応していません。

require 'uri'
ary = URI.decode_www_form("a=1&a=2&b=3")
p ary                 #=> [['a', '1'], ['a', '2'], ['b', '3']]
p ary.assoc('a').last #=> '1'
p ary.assoc('b').last #=> '3'
p Hash[ary]           #=> {"a"=>"2", "b"=>"3"}

[PARAM] str:: デコード対象の文字列
[PARAM] enc:: エンコーディング
[EXCEPTION] ArgumentError:: str のフォーマットが不正である場合に発生します

[SEE_ALSO] URI.decode_www_form_component, URI.encode_www_form

decode_www_form_component(str, enc=Encoding::UTF_8) -> StringRuby 1.9.3 から[permalink][rdoc][edit]

URL-encoded form data の文字列の各コンポーネントをデコードした文字列を返します。

通常は URI.decode_www_form を使うほうがよいでしょう。

"+" という文字は空白文字にデコードします。

enc で指定したエンコーディングの文字列が URL エンコードされたものとみなし、エンコーディングを付加します。

このメソッドは https://www.w3.org/TR/html5/sec-forms.html#urlencoded-form-data にもとづいて実装されています。

require 'uri'
enc = URI.encode_www_form_component('Ruby リファレンスマニュアル')
# => "Ruby+%E3%83%AA%E3%83%95%E3%82%A1%E3%83%AC%E3%83%B3%E3%82%B9%E3%83%9E%E3%83%8B%E3%83%A5%E3%82%A2%E3%83%AB"
p URI.decode_www_form_component(enc)
# => "Ruby リファレンスマニュアル"

[PARAM] str:: デコード対象の文字列
[PARAM] enc:: エンコーディング
[EXCEPTION] ArgumentError:: str のフォーマットが不正である場合に発生します

[SEE_ALSO] URI.encode_www_form_component, URI.decode_www_form

encode_www_form(enum, enc=nil) -> StringRuby 1.9.3 から[permalink][rdoc][edit]

enum から URL-encoded form data を生成します。

HTML5 で定義されている application/x-www-form-urlencoded 形式の文字列を生成します。

enum には通常 [key, value] という形の配列の配列を渡します。以下の例を見てください。

require 'uri'
p URI.encode_www_form([["a", "1"], ["b", "2"], ["c", "x yz"]])
# => "a=1&b=2&c=x+yz"

実際には、each のブロック呼び出しで [key, value] の形のデータを渡すものであれば何でも渡すことができます(例えば Hash など)。

require 'uri'
p URI.encode_www_form({"a"=>"1", "b"=>"2", "c"=>"x yz"})
# => "a=1&b=2&c=x+yz"

このメソッドは引数のエンコーディングを変換しません。そのため送るデータのエンコーディングを変換したい場合はあらかじめ変換しておいてください(例えば ASCII incompatible なものを UTF-8 に変換する場合など)。各要素のエンコーディングがばらばらの場合もあらかじめエンコーディングを揃えてからこのメソッドを使うべきです。

このメソッドはファイルを入力にすることはできません。ファイルを送りたい場合は multipart/form-data をつかうべきでこのメソッドを使うべきではありません。

このメソッドは内部的に URI.encode_www_form_component を使っています。

このメソッドは https://url.spec.whatwg.org/#concept-urlencoded-serializer にもとづいて実装されています。

[PARAM] enum:: エンコードするデータ列([key, value] という形のデータの列)
[PARAM] enc:: 指定された場合、パーセントエンコーディングする前に、このエンコーディングに変換

[SEE_ALSO] URI.encode_www_form_component, URI.decode_www_form

encode_www_form_component(str, enc=nil) -> StringRuby 1.9.3 から[permalink][rdoc][edit]

文字列を URL-encoded form data の1コンポーネントとしてエンコードした文字列を返します。

通常は URI.encode_www_form を使うほうがよいでしょう。

このメソッドでは *, -, ., 0-9, A-Z, _, a-z, は変換せず、空白は + に変換し、その他は %XX に、変換します。

このメソッドは https://www.w3.org/TR/2013/CR-html5-20130806/forms.html#url-encoded-form-data にもとづいて実装されています。

require 'uri'
p URI.encode_www_form_component('Ruby リファレンスマニュアル')
# => "Ruby+%E3%83%AA%E3%83%95%E3%82%A1%E3%83%AC%E3%83%B3%E3%82%B9%E3%83%9E%E3%83%8B%E3%83%A5%E3%82%A2%E3%83%AB"

[PARAM] str:: エンコードする文字列
[PARAM] enc:: 指定された場合、パーセントエンコーディングする前に、strをこのエンコーディングに変換

[SEE_ALSO] URI.decode_www_form_component, URI.encode_www_form

extract(str) -> [String][permalink][rdoc][edit]

extract(str, schemes) -> [String]

extract(str) {|uri_str| ... } -> nil

extract(str, schemes) {|uri_str| ... } -> nil

文字列 str に対して正規表現によるマッチを試み、絶対URIにマッチした部分文字列からなる配列として返します。抽出する URI がなければ空の配列を返します。

第2引数に文字列の配列 schemes が与えられた場合はそのスキームだけを検索します。

ブロックが与えられた場合は String#scan と同様で、マッチした部分がみつかるたびに uri_str にその部分を代入してブロックを評価します。このときは nil を返します。

このメソッドは Ruby 2.2 から obsolete です。

[PARAM] str:: 文字列を与えます。
[PARAM] schemes:: 検索の対象としたいスキームを、文字列の配列として与えます。

例

require 'uri'
str = "
        http://www.ruby-lang.org/
        http://www.ruby-lang.org/man-1.6/
"
p URI.extract(str, ["http"])
=> ["http://www.ruby-lang.org/", "http://www.ruby-lang.org/man-1.6/"]

join(uri_str, *path) -> object[permalink][rdoc][edit]

文字列 uri_str と path ... を URI として連結して得られる URI オブジェクトを返します。

[RFC2396] の Section 5.2 の仕様に従って連結します。以下と等価です

require 'uri'
URI.parse(uri_str) + path + ...

[PARAM] uri_str:: URI 文字列
[PARAM] path:: 後ろに連結する文字列
[EXCEPTION] URI::InvalidComponentError:: 各要素が適合しない場合に発生します。
[EXCEPTION] URI::InvalidURIError:: パースに失敗した場合に発生します。

例

require 'uri'
p URI.join('http://www.ruby-lang.org/', '/ja/man-1.6/')
=> #<URI::HTTP:0x2010017a URL:http://www.ruby-lang.org/ja/man-1.6/>

parse(uri_str) -> object[permalink][rdoc][edit]

与えられた URI から該当する URI::Generic のサブクラスのインスタンスを生成して返します。scheme が指定されていない場合は、URI::Generic オブジェクトを返します。

[PARAM] uri_str:: パースしたい URI を文字列として与えます。
[EXCEPTION] URI::InvalidComponentError:: 各要素が適合しない場合に発生します。
[EXCEPTION] URI::InvalidURIError:: パースに失敗した場合に発生します。

例

require 'uri'
p uri = URI.parse("http://www.ruby-lang.org/")

# => #<URI::HTTP:0x201002a6 URL:http://www.ruby-lang.org/>
p uri.scheme    # => "http"
p uri.host      # => "www.ruby-lang.org"
p uri.port      # => 80
p uri.path      # => "/"

regexp -> Regexp[permalink][rdoc][edit]

regexp(schemes) -> Regexp

URIにマッチする正規表現を返します。

schemes を与えた場合は、そのスキームの URI にのみマッチする正規表現を返します。

いずれの場合も返り値の正規表現は不定数の正規表現グループ (括弧) を含みます。この括弧の数はバージョンによって変動する可能性があるので、それに依存したコードを書くべきではありません。

また、有効なURIではない文字列(たとえば"http://") にもマッチするため、有効なURIかどうかは必要に応じて別途検査してください。

このメソッドは Ruby 2.2 から obsolete です。

[PARAM] schemes:: マッチさせたいスキームを、文字列の配列として与えます。

例

require 'uri'
p URI.regexp =~ "http://www.ruby-lang.org/"  #=> 0

split(url) -> [String | nil][permalink][rdoc][edit]

URI を要素に分割した文字列の配列を返します。

各要素の種類と順番は以下のとおりです。

scheme
userinfo
host
port
registry
path
opaque
query
fragment

[PARAM] url:: パースしたい URI を文字列として与えます。
[EXCEPTION] URI::InvalidURIError:: パースに失敗した場合に発生します。

例

require 'uri'
p URI.split("http://www.ruby-lang.org/")
#=> ["http", nil, "www.ruby-lang.org", nil, nil, "/", nil, nil, nil]

追加されるメソッド

open(name, mode = 'r', perm = nil, options = {}) -> StringIO | Tempfile | IORuby 2.5.0 から[permalink][rdoc][edit] [added by open-uri]

open(name, mode = 'r', perm = nil, options = {}) {|ouri| ...} -> object [added by open-uri]

name が http:// や https://、ftp:// で始まっている文字列なら URI のリソースを取得した上で StringIO オブジェクトまたは Tempfile オブジェクトとして返します。返されるオブジェクトは OpenURI::Meta モジュールで extend されています。

name に open メソッドが定義されている場合は、*rest を引数として渡し name.open(*rest, &block) のように name の open メソッドが呼ばれます。

これ以外の場合は、name はファイル名として扱われ、従来の Kernel?.open(name, *rest) が呼ばれます。

ブロックを与えた場合は上の場合と同様、name が http:// や https://、ftp:// で始まっている文字列なら URI のリソースを取得した上で StringIO オブジェクトまたは Tempfile オブジェクトを引数としてブロックを評価します。後は同様です。引数のオブジェクトは OpenURI::Meta モジュールで extend されています。

[PARAM] name:: オープンしたいリソースを文字列で与えます。
[PARAM] mode:: モードを文字列で与えます。Kernel?.open の mode_enc とおおむね同じですが、外部エンコーディングの指定(ext_enc)は有効な一方、内部エンコーディングの指定 (ext_enc:int_enc の int_enc)は無視されます。内部エンコーディングへの変換が必要な場合は、読み込んだ文字列を String#encode で変換してください (返り値のオブジェクトはレスポンスの大きさによって StringIO にも Tempfile ベースの IO にもなり、IO#set_encoding による内部エンコーディングへの変換は StringIO では行われないためです)。

例

require 'open-uri'

# 外部エンコーディングとして cp932 を指定し、
# 読み込んだ文字列を String#encode で UTF-8 に変換する
URI.open('http://example.com/', 'r:cp932') do |f|
  f.read.encode('UTF-8', invalid: :replace, undef: :replace)
end

[PARAM] perm:: open(2) の第 3 引数のように、ファイルを生成する場合のファイルのパーミッションを整数で指定します。Kernel?.open と同じです
[PARAM] options:: ハッシュを与えます。詳しくは OpenURI.open_uri を参照してください。
[EXCEPTION] OpenURI::HTTPError:: 対象となる URI のスキームが http または https であり、かつリソースの取得に失敗したときに発生します。
[EXCEPTION] Net::FTPError:: 対象となる URI のスキームが ftp であり、かつリソースの取得に失敗した時に Net::FTPError のサブクラスが発生します。詳しくは net/ftp を参照して下さい。

[SEE_ALSO] Kernel?.open, OpenURI.open_uri

定数

UNSAFE -> Regexp[permalink][rdoc][edit]

URIとして指定できない文字にマッチする正規表現

/[^-_.!~*'()a-zA-Z\d;\/?:@&=+$,\[\]]/n

です。

要約

目次

特異メソッド

追加されるメソッド

定数