модуль OpenURI::OpenRead

# File lib/open-uri.rb, line 810
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, её значением должен быть массив из 2 строк: имени пользователя и пароля. Он используется для базовой 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 используется для указания сертификата центра сертификации (CA) для 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 818
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.