module URI

Not quite open-uri, but similar. Provides read and write methods for the resource represented by the URI. Currently supports reads for URI::HTTP and writes for URI::SFTP. Also provides convenience methods for downloads and uploads.

URI is a module providing classes to handle Uniform Resource Identifiers (RFC2396)

Features¶ ↑

Uniform handling of handling URIs
Flexibility to introduce custom URI schemes
Flexibility to have an alternate URI::Parser (or just different patterns and regexp’s)

Basic example¶ ↑

require 'uri'

uri = URI("http://foo.com/posts?id=30&limit=5#time=1305298413")
#=> #<URI::HTTP:0x00000000b14880
      URL:http://foo.com/posts?id=30&limit=5#time=1305298413>
uri.scheme
#=> "http"
uri.host
#=> "foo.com"
uri.path
#=> "/posts"
uri.query
#=> "id=30&limit=5"
uri.fragment
#=> "time=1305298413"

uri.to_s
#=> "http://foo.com/posts?id=30&limit=5#time=1305298413"

Adding custom URIs¶ ↑

module URI
  class RSYNC < Generic
    DEFAULT_PORT = 873
  end
  @@schemes['RSYNC'] = RSYNC
end
#=> URI::RSYNC

URI.scheme_list
#=> {"FTP"=>URI::FTP, "HTTP"=>URI::HTTP, "HTTPS"=>URI::HTTPS,
     "LDAP"=>URI::LDAP, "LDAPS"=>URI::LDAPS, "MAILTO"=>URI::MailTo,
     "RSYNC"=>URI::RSYNC}

uri = URI("rsync://rsync.foo.com")
#=> #<URI::RSYNC:0x00000000f648c8 URL:rsync://rsync.foo.com>

RFC References¶ ↑

A good place to view an RFC spec is www.ietf.org/rfc.html

Here is a list of all related RFC’s.

Class tree¶ ↑

URI::Generic (in uri/generic.rb)
- URI::FTP - (in uri/ftp.rb)
- URI::HTTP - (in uri/http.rb)
  - URI::HTTPS - (in uri/https.rb)
- URI::LDAP - (in uri/ldap.rb)
  - URI::LDAPS - (in uri/ldaps.rb)
- URI::MailTo - (in uri/mailto.rb)
URI::Parser - (in uri/common.rb)
URI::REGEXP - (in uri/common.rb)
- URI::REGEXP::PATTERN - (in uri/common.rb)
URI::Util - (in uri/common.rb)
URI::Escape - (in uri/common.rb)
URI::Error - (in uri/common.rb)
- URI::InvalidURIError - (in uri/common.rb)
- URI::InvalidComponentError - (in uri/common.rb)
- URI::BadURIError - (in uri/common.rb)

Copyright Info¶ ↑

Author: Akira Yamada <akira@ruby-lang.org>
Documentation: Akira Yamada <akira@ruby-lang.org> Dmitry V. Sabanin <sdmitry@lrn.ru> Vincent Batts <vbatts@hashbangbash.com>
License: Copyright © 2001 akira yamada <akira@ruby-lang.org> You can redistribute it and/or modify it under the same term as Ruby.
Revision: $Id: uri.rb 31555 2011-05-13 20:03:21Z drbrain $

Public Class Methods

download(uri, target, options?) click to toggle source

Downloads the resource to the target.

The target may be a file name (string or task), in which case the file is created from the resource. The target may also be any object that responds to write, e.g. File, StringIO, Pipe.

Use the progress bar when running in verbose mode.

# File lib/buildr/core/transports.rb, line 71
def download(uri, target, options = nil)
  uri = URI.parse(uri.to_s) unless URI === uri
  uri.download target, options
end

read(uri, options?) → content click to toggle source

read(uri, options?) { |chunk| ... }

Reads from the resource behind this URI. The first form returns the content of the resource, the second form yields to the block with each chunk of content (usually more than one).

For example:

File.open 'image.jpg', 'w' do |file|
  URI.read('http://example.com/image.jpg') { |chunk| file.write chunk }
end

Shorter version:

File.open('image.jpg', 'w') { |file| file.write URI.read('http://example.com/image.jpg') }

Supported options:

:modified – Only download if file modified since this timestamp. Returns nil if not modified.
:progress – Show the progress bar while reading.

# File lib/buildr/core/transports.rb, line 57
def read(uri, options = nil, &block)
  uri = URI.parse(uri.to_s) unless URI === uri
  uri.read options, &block
end

upload(uri, source, options?) click to toggle source

Uploads from source to the resource.

The source may be a file name (string or task), in which case the file is uploaded to the resource. The source may also be any object that responds to read (and optionally size), e.g. File, StringIO, Pipe.

Use the progress bar when running in verbose mode.

# File lib/buildr/core/transports.rb, line 107
def upload(uri, source, options = nil)
  uri = URI.parse(uri.to_s) unless URI === uri
  uri.upload source, options
end

write(uri, content, options?) click to toggle source

write(uri, options?) { |bytes| .. }

Writes to the resource behind the URI. The first form writes the content from a string or an object that responds to read and optionally size. The second form writes the content by yielding to the block. Each yield should return up to the specified number of bytes, the last yield returns nil.

For example:

File.open 'killer-app.jar', 'rb' do |file|
  write('sftp://localhost/jars/killer-app.jar') { |chunk| file.read(chunk) }
end

Or:

write 'sftp://localhost/jars/killer-app.jar', File.read('killer-app.jar')

Supported options:

:progress – Show the progress bar while reading.

# File lib/buildr/core/transports.rb, line 93
def write(uri, *args, &block)
  uri = URI.parse(uri.to_s) unless URI === uri
  uri.write *args, &block
end