модуль OpenURI::OpenRead

# File lib/open-uri.rb, line 804
def open(*rest, &block)
  OpenURI.open_uri(self, *rest, &block)
end

OpenURI::OpenRead#open предоставляет «open» для URI::HTTP и URI::FTP.

OpenURI::OpenRead#open принимает 3 необязательных аргумента:

OpenURI::OpenRead#open([mode [, perm]] [, options]) [{|io| ... }]

OpenURI::OpenRead#open возвращает объект, подобный IO, если блок не задан. В противном случае метод передаёт объект IO блоку и возвращает его значение. Объект IO расширяется модулем OpenURI::Meta.

mode и perm работают так же, как Kernel#open.

Однако mode должен быть режимом чтения, поскольку OpenURI::OpenRead#open пока не поддерживает режим записи. Кроме того, perm игнорируется, так как имеет смысл только при создании файла.

options должен быть хэшем.

Каждая опция со строковым ключом задаёт дополнительное поле заголовка HTTP. То есть она игнорируется для FTP без HTTP-прокси.

Хэш может содержать и другие опции, ключами которых являются символы:

:proxy

Формат:

:proxy => "http://proxy.foo.com:8000/"
:proxy => URI.parse("http://proxy.foo.com:8000/")
:proxy => true
:proxy => false
:proxy => nil

Если задана опция :proxy, её значением должна быть String, URI, логическое значение или nil.

Если задана String или URI, она рассматривается как прокси-URI.

Если задано true или сама опция не указана, проверяется переменная окружения «scheme_proxy». Вместо «scheme» подставляется «http», «https» или «ftp».

Если задано false или nil, переменные окружения игнорируются, и соединение устанавливается напрямую с сервером.

:proxy_http_basic_authentication

Формат:

:proxy_http_basic_authentication =>
  ["http://proxy.foo.com:8000/", "proxy-user", "proxy-password"]
:proxy_http_basic_authentication =>
  [URI.parse("http://proxy.foo.com:8000/"),
   "proxy-user", "proxy-password"]

Если задана опция :proxy, её значением должен быть Array из 3 элементов. Он должен содержать прокси-URI, имя пользователя прокси и пароль прокси. Прокси-URI должен быть String, URI или nil. Имя пользователя прокси и пароль должны быть значениями типа String.

Если для прокси-URI задано nil, эта опция просто игнорируется.

Если заданы :proxy и :proxy_http_basic_authentication, возникает ArgumentError.

:http_basic_authentication

Формат:

:http_basic_authentication=>[user, password]

Если задана :http_basic_authentication, её значением должен быть массив из двух строк: имени пользователя и пароля. Он используется для базовой HTTP-аутентификации, определённой RFC 2617.

:content_length_proc

Формат:

:content_length_proc => lambda {|content_length| ... }

Если задана опция :content_length_proc, процедура из значения этой опции вызывается до начала фактической передачи. Она принимает один аргумент — ожидаемую длину содержимого в байтах.

Если при перенаправлении HTTP выполняются две или более передачи, процедура вызывается только один раз — для последней передачи.

Если ожидаемая длина содержимого неизвестна, процедура вызывается с аргументом nil. Это происходит, когда в ответе HTTP отсутствует заголовок Content-Length.

:progress_proc

Формат:

:progress_proc => lambda {|size| ...}

Если задана опция :progress_proc, процедура вызывается с одним аргументом каждый раз, когда «open» получает фрагмент содержимого из сети. Аргумент size — это накопленный объём переданных данных в байтах.

Если при перенаправлении HTTP выполняются две или более передачи, процедура вызывается только один раз — для последней передачи.

:progress_proc и :content_length_proc предназначены для использования с индикатором выполнения. Например, его можно реализовать следующим образом с помощью Ruby/ProgressBar.

pbar = nil
open("http://...",
  :content_length_proc => lambda {|t|
    if t && 0 < t
      pbar = ProgressBar.new("...", t)
      pbar.file_transfer_mode
    end
  },
  :progress_proc => lambda {|s|
    pbar.set s if pbar
  }) {|f| ... }

:read_timeout

Формат:

:read_timeout=>nil     (no timeout)
:read_timeout=>10      (10 second)

Опция :read_timeout задаёт время ожидания чтения для HTTP-соединений.

:open_timeout

Формат:

:open_timeout=>nil     (no timeout)
:open_timeout=>10      (10 second)

Опция :open_timeout задаёт время ожидания открытия для HTTP-соединений.

:ssl_ca_cert

Формат:

:ssl_ca_cert=>filename or an Array of filenames

:ssl_ca_cert используется для указания сертификата центра сертификации для SSL. Если он задан, сертификаты по умолчанию не используются.

:ssl_verify_mode

Формат:

:ssl_verify_mode=>mode

:ssl_verify_mode используется для указания режима проверки openssl.

:ssl_min_version

Формат:

:ssl_min_version=>:TLS1_2

Опция :ssl_min_version задаёт минимально допустимую версию протокола SSL/TLS. См. также OpenSSL::SSL::SSLContext#min_version=.

:ssl_max_version

Формат:

:ssl_max_version=>:TLS1_2

Опция :ssl_max_version задаёт максимально допустимую версию протокола SSL/TLS. См. также OpenSSL::SSL::SSLContext#max_version=.

:ftp_active_mode

Формат:

:ftp_active_mode=>bool

:ftp_active_mode => true используется для включения активного режима FTP. В Ruby 1.9 по умолчанию используется пассивный режим. Обратите внимание, что в Ruby 1.8 и более ранних версиях по умолчанию используется активный режим.

:redirect

Формат:

:redirect=>bool

По умолчанию :redirect имеет значение true. :redirect => false используется для отключения всех перенаправлений HTTP.

При перенаправлении возникает исключение OpenURI::HTTPRedirect. Использование true также означает, что перенаправления между HTTP и FTP разрешены.

:max_redirects

Формат:

:max_redirects=>int

Количество разрешённых перенаправлений HTTP, после которого возникает OpenURI::TooManyRedirects. По умолчанию — 64.

:request_specific_fields

Формат:

:request_specific_fields => {}
:request_specific_fields => lambda {|url| ...}

Опция :request_specific_fields позволяет указать пользовательские поля заголовка, отправляемые вместе с HTTP-запросом. Её можно передать как Hash или как Proc, которая вычисляется для каждого запроса и возвращает Hash полей заголовка.

Если передан Hash, он задаёт заголовки только для первоначального запроса; при перенаправлениях эти заголовки отправляться не будут.

Если передан Proc, он будет выполняться для каждого запроса, включая перенаправления, что позволяет динамически настраивать заголовки в зависимости от URL запроса. Важно, чтобы Proc возвращал Hash. Этот Hash задаёт заголовки, отправляемые вместе с запросом.

Пример с Hash

URI.open("http://...",
         request_specific_fields: {"Authorization" => "token dummy"}) {|f| ... }

Пример с Proc:

URI.open("http://...",
         request_specific_fields: lambda { |uri|
           if uri.host == "example.com"
             {"Authorization" => "token dummy"}
           else
             {}
           end
         }) {|f| ... }

# File lib/open-uri.rb, line 812
def read(options={})
  self.open(options) {|f|
    str = f.read
    Meta.init str, f
    str
  }
end

OpenURI::OpenRead#read([ options ]) читает содержимое, на которое ссылается self, и возвращает его в виде строки. Строка расширяется модулем OpenURI::Meta. Аргумент options такой же, как у OpenURI::OpenRead#open.