Class: URI::FTP

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, Generic
Instance Chain: self, Generic, ::URI, RFC2396_REGEXP
Inherits:	URI::Generic Object URI::Generic URI::FTP
Defined in:	lib/uri/ftp.rb

Overview

FTP URI syntax is defined by RFC1738 section 3.2.

This class will be redesigned because of difference of implementations; the structure of its path. draft-hoffman-ftp-uri-04 is a draft but it is a good summary about the de facto spec. tools.ietf.org/html/draft-hoffman-ftp-uri-04

Constant Summary

COMPONENT =

An Array of the available components for FTP

# File 'lib/uri/ftp.rb', line 30
```
[
  :scheme,
  :userinfo, :host, :port,
  :path, :typecode
].freeze
```
DEFAULT_PORT =

A Default port of 21 for FTP

# File 'lib/uri/ftp.rb', line 25
```
21
```
TYPECODE =
Typecode is “a”, “i” or “d”.
- “a” indicates a text file (the FTP command was ASCII)
- “i” indicates a binary file (FTP command IMAGE)
- “d” indicates the contents of a directory should be displayed
# File 'lib/uri/ftp.rb', line 43
```
['a', 'i', 'd'].freeze
```
TYPECODE_PREFIX =
Typecode prefix
```
';type='
```
# File 'lib/uri/ftp.rb', line 47
```
';type='.freeze
```

::URI - Included

DEFAULT_PARSER, HTML5ASCIIINCOMPAT, Parser, REGEXP, RFC3986_PARSER, TBLDECWWWCOMP_, TBLENCWWWCOMP_, VERSION, VERSION_CODE, WEB_ENCODINGS_

Generic - Inherited

COMPONENT, DEFAULT_PORT, USE_REGISTRY

Class Method Summary

.build(args)

Description.
.new(scheme, userinfo, host, port, registry, path, opaque, query, fragment, parser = nil, arg_check = false) ⇒ FTP constructor

Description.
.new2(user, password, host, port, path, typecode = nil, arg_check = true)

Generic - Inherited

.build	Synopsis.
.build2	Synopsis.
.component	Components of the ::URI in the order.
.default_port	Returns default port.
.new	Args.
.use_proxy?, .use_registry

Instance Attribute Summary

#typecode rw

typecode accessor.
#typecode=(typecode) rw

Args.

Generic - Inherited

#absolute	Alias for Generic#absolute?.
#fragment	returns the fragment component of the ::URI.
#fragment=	check the fragment `v` component against the Parser Regexp for `:FRAGMENT`.
#hierarchical?	Checks if ::URI has a path.
#host	returns the host component of the ::URI.
#host=	Args.
#hostname	extract the host part of the ::URI and unwrap brackets for IPv6 addresses.
#hostname=	set the host part of the ::URI as the argument with brackets for IPv6 addresses.
#opaque	returns the opaque part of the ::URI.
#opaque=	Args.
#password	returns the password component.
#password=	Args.
#path	returns the path component of the ::URI.
#path=	Args.
#port	returns the port component of the ::URI.
#port=	Args.
#query	returns the query component of the ::URI.
#query=	Args.
#registry=,
#relative?	Checks if ::URI is relative.
#scheme	returns the scheme component of the ::URI.
#scheme=	Args.
#user	returns the user component.
#user=	Args.
#userinfo	returns the userinfo, either as 'user' or 'user:password'.
#userinfo=	Sets userinfo, argument is string like 'name:pass'.
#registry

Instance Method Summary

#path

Returns the path from an FTP URI.
#to_s

Returns a String representation of the FTP
#set_path(v) protected

Private setter for the path of the FTP
#set_typecode(v) protected

Private setter for the typecode v
#check_typecode(v) private

validates typecode v, returns a true or false boolean.
#merge(oth) Internal use only

Generic - Inherited

#+	Alias for Generic#merge.
#-	Alias for Generic#route_from.
#==	Compares two URIs.
#absolute?	Checks if ::URI is an absolute one.
#coerce	Args.
#component	Components of the ::URI in the order.
#default_port	Returns default port.
#eql?,
#find_proxy	returns a proxy ::URI.
#hash, #inspect,
#merge	Args.
#merge!	Args.
#normalize	Returns normalized ::URI.
#normalize!	Destructive version of `#normalize`
#parser	returns the parser to be used.
#route_from	Args.
#route_to	Args.
#select	Args.
#to_s	Constructs String from ::URI.
#component_ary	returns an Array of the components defined from the COMPONENT Array.
#set_host	protected setter for the host component `v`
#set_opaque	protected setter for the opaque component `v`
#set_password	protected setter for the password component `v`
#set_path	protected setter for the path component `v`
#set_port	protected setter for the port component `v`
#set_scheme	protected setter for the scheme component `v`
#set_user	protected setter for the user component `v`
#set_userinfo	protect setter for the `user` component, and `password` if available.
#check_host	check the host `v` component for RFC2396 compliance and against the Parser Regexp for `:HOST`.
#check_opaque	check the opaque `v` component for RFC2396 compliance and against the Parser Regexp for `:OPAQUE`.
#check_password	check the password `v` component for RFC2396 compliance and against the Parser Regexp for `:USERINFO`.
#check_path	check the path `v` component for RFC2396 compliance and against the Parser Regexp for `:ABS_PATH` and `:REL_PATH`.
#check_port	check the port `v` component for RFC2396 compliance and against the Parser Regexp for `:PORT`.
#check_scheme	check the scheme `v` component against the Parser Regexp for `:SCHEME`.
#check_user	check the user `v` component for RFC2396 compliance and against the Parser Regexp for `:USERINFO`.
#check_userinfo	check the `user` and `password`.
#escape_userpass	escapes 'user:password' `v` based on RFC 1738 section 3.1.
#merge_path	Merges a base path `base`, with relative path `rel`, returns a modified base path.
#replace!	replace self by other ::URI object.
#route_from0,
#split_path	returns an Array of the path split on '/'.
#split_userinfo	returns the userinfo `ui` as user, password if properly formatted as 'user:password'.
#set_registry, #check_registry, #route_from_path

Constructor Details

.new(scheme, userinfo, host, port, registry, path, opaque, query, fragment, parser = nil, arg_check = false) ⇒ `FTP`

Description

Creates a new FTP object from generic URL components with no syntax checking.

Unlike build(), this method does not escape the path component as required by RFC1738; instead it is treated as per RFC2396.

Arguments are scheme, userinfo, host, port, registry, #path, opaque, query and fragment, in that order.

Raises:

(InvalidURIError)

[ GitHub ]

# File 'lib/uri/ftp.rb', line 133


def initialize(scheme,
               userinfo, host, port, registry,
               path, opaque,
               query,
               fragment,
               parser = nil,
               arg_check = false)
  raise InvalidURIError unless path
  path = path.sub(/^\//,'')
  path.sub!(/^%2F/,'/')
  super(scheme, userinfo, host, port, registry, path, opaque,
        query, fragment, parser, arg_check)
  @typecode = nil
  if tmp = @path.index(TYPECODE_PREFIX)
    typecode = @path[tmp + TYPECODE_PREFIX.size..-1]
    @path = @path[0..tmp - 1]

    if arg_check
      self.typecode = typecode
    else
      self.set_typecode(typecode)
    end
  end
end

Class Method Details

.build(args)

Description

Creates a new FTP object from components, with syntax checking.

The components accepted are userinfo, host, port, #path and #typecode.

The components should be provided either as an Array, or as a Hash with keys formed by preceding the component names with a colon.

If an Array is used, the components must be passed in the order

userinfo, host, port, path, typecode

If the path supplied is absolute, it will be escaped in order to make it absolute in the ::URI. Examples:

require 'uri'

uri = URI::FTP.build(['user:password', 'ftp.example.com', nil,
  '/path/file.zip', 'i'])
puts uri.to_s  ->  ftp://user:password@ftp.example.com/%2Fpath/file.zip;type=i

uri2 = URI::FTP.build({:host => 'ftp.example.com',
  :path => 'ruby/src'})
puts uri2.to_s  ->  ftp://ftp.example.com/ruby/src

[ GitHub ]

# File 'lib/uri/ftp.rb', line 96


def self.build(args)

  # Fix the incoming path to be generic URL syntax
  # FTP path  ->  URL path
  # foo/bar       /foo/bar
  # /foo/bar      /%2Ffoo/bar
  #
  if args.kind_of?(Array)
    args[3] = '/' + args[3].sub(/^\//, '%2F')
  else
    args[:path] = '/' + args[:path].sub(/^\//, '%2F')
  end

  tmp = Util::make_components_hash(self, args)

  if tmp[:typecode]
    if tmp[:typecode].size == 1
      tmp[:typecode] = TYPECODE_PREFIX + tmp[:typecode]
    end
    tmp[:path] << tmp[:typecode]
  end

  return super(tmp)
end

.new2(user, password, host, port, path, typecode = nil, arg_check = true)

[ GitHub ]

# File 'lib/uri/ftp.rb', line 49


def self.new2(user, password, host, port, path,
              typecode = nil, arg_check = true) # :nodoc:
  # Do not use this method!  Not tested.  [Bug #7301]
  # This methods remains just for compatibility,
  # Keep it undocumented until the active maintainer is assigned.
  typecode = nil if typecode.size == 0
  if typecode && !TYPECODE.include?(typecode)
    raise ArgumentError,
      "bad typecode is specified: #{typecode}"
  end

  # do escape

  self.new('ftp',
           [user, password],
           host, port, nil,
           typecode ? path + TYPECODE_PREFIX + typecode : path,
           nil, nil, nil, arg_check)
end

Instance Attribute Details

#typecode (rw)

typecode accessor

see COMPONENT

[ GitHub ]

# File 'lib/uri/ftp.rb', line 161


attr_reader :typecode

#typecode=(typecode) (rw)

Args

v: String

Description

public setter for the typecode v. (with validation)

Usage

require 'uri'

uri = URI.parse("ftp://john@ftp.example.com/my_file.img")
#=> #<URI::FTP:0x00000000923650 URL:ftp://john@ftp.example.com/my_file.img>
uri.typecode = "i"
# =>  "i"
uri
#=> #<URI::FTP:0x00000000923650 URL:ftp://john@ftp.example.com/my_file.img;type=i>

[ GitHub ]

# File 'lib/uri/ftp.rb', line 209


def typecode=(typecode)
  check_typecode(typecode)
  set_typecode(typecode)
  typecode
end

Instance Method Details

#check_typecode(v) (private)

validates typecode v, returns a true or false boolean

[ GitHub ]

# File 'lib/uri/ftp.rb', line 166


def check_typecode(v)
  if TYPECODE.include?(v)
    return true
  else
    raise InvalidComponentError,
      "bad typecode(expected #{TYPECODE.join(', ')}): #{v}"
  end
end

#merge(oth)

This method is for internal use only.

[ GitHub ]

# File 'lib/uri/ftp.rb', line 215


def merge(oth) # :nodoc:
  tmp = super(oth)
  if self != tmp
    tmp.set_typecode(oth.typecode)
  end

  return tmp
end

#path

Returns the path from an FTP URI.

RFC 1738 specifically states that the path for an FTP URI does not include the / which separates the ::URI path from the ::URI host. Example:

ftp://ftp.example.com/pub/ruby

The above ::URI indicates that the client should connect to ftp.example.com then cd pub/ruby from the initial login directory.

If you want to cd to an absolute directory, you must include an escaped / (%2F) in the path. Example:

ftp.example.com/%2Fpub/ruby

This method will then return “/pub/ruby”

[ GitHub ]

# File 'lib/uri/ftp.rb', line 241


def path
  return @path.sub(/^\//,'').sub(/^%2F/,'/')
end

#set_path(v) (protected)

Private setter for the path of the FTP

[ GitHub ]

# File 'lib/uri/ftp.rb', line 246


def set_path(v)
  super("/" + v.sub(/^\//, "%2F"))
end

#set_typecode(v) (protected)

Private setter for the typecode v

#to_s

Returns a String representation of the FTP

[ GitHub ]

# File 'lib/uri/ftp.rb', line 252


def to_s
  save_path = nil
  if @typecode
    save_path = @path
    @path = @path + TYPECODE_PREFIX + @typecode
  end
  str = super
  if @typecode
    @path = save_path
  end

  return str
end

Class: URI::FTP

Overview

Constant Summary

::URI - Included

Generic - Inherited

Class Method Summary

Generic - Inherited

Instance Attribute Summary

Generic - Inherited

Instance Method Summary

Generic - Inherited

Constructor Details

.new(scheme, userinfo, host, port, registry, path, opaque, query, fragment, parser = nil, arg_check = false) ⇒ FTP

Description

Class Method Details

.build(args)

Description

.new2(user, password, host, port, path, typecode = nil, arg_check = true)

Instance Attribute Details

#typecode (rw)

#typecode=(typecode) (rw)

Args

Description

Usage

Instance Method Details

#check_typecode(v) (private)

#merge(oth)

#path

#set_path(v) (protected)

#set_typecode(v) (protected)

#to_s

.new(scheme, userinfo, host, port, registry, path, opaque, query, fragment, parser = nil, arg_check = false) ⇒ `FTP`