модуль 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, значение должно быть массивом с 3 элементами. Он должен содержать прокси-URI, имя пользователя прокси и пароль прокси. Прокси-URI должен быть строкой, URI или nil. Имя пользователя и пароль прокси должны быть строками.

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

Если указаны параметры :proxy и :proxy_http_basic_authentication, генерируется исключение ArgumentError.

:http_basic_authentication

Синопсис:

:http_basic_authentication=>[user, password]

Если указан параметр :http_basic_authentication, значение должно быть массивом из двух строк: имени пользователя и пароля. Используется для аутентификации HTTP Basic, определенной 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 запросом. Он может быть передан в виде хэша или процедуры, которая вычисляется для каждого запроса и возвращает хэш полей заголовков.

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

Если указана процедура, она будет выполняться для каждого запроса, включая редиректы, позволяя динамическое изменение заголовков на основе URL запроса. Важно, чтобы процедура возвращала хэш. И этот хэш указывает заголовки, которые должны быть отправлены с запросом.

Например, с хэшем:

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

Например, с процедурой:

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.