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. datatracker.ietf.org/doc/html/draft-hoffman-ftp-uri-04

Constant Summary

COMPONENT =

An Array of the available components for FTP.

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

A Default port of 21 for FTP.

# File 'lib/uri/ftp.rb', line 24
```
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 42
```
['a', 'i', 'd'].freeze
```
TYPECODE_PREFIX =

Typecode prefix “;type=”.

# File 'lib/uri/ftp.rb', line 45
```
';type='.freeze
```

`::URI` - Included

DEFAULT_PARSER, INITIAL_SCHEMES, Parser, REGEXP, RFC3986_PARSER, TBLDECWWWCOMP_, TBLENCURICOMP_, 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=	Checks the fragment `v` component against the Parser Regexp for `:FRAGMENT`.
#hierarchical?	Returns true if `::URI` is hierarchical.
#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=	Sets 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 (without `::URI` decoding).
#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?	Returns true if `::URI` does not have a scheme (e.g.
#scheme	Returns the scheme component of the `::URI`.
#scheme=	Args.
#user	Returns the user component (without `::URI` decoding).
#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 true or false.
#merge(oth) Internal use only

`Generic` - Inherited

#+	Alias for Generic#merge.
#-	Alias for Generic#route_from.
#==	Compares two URIs.
#absolute?	Returns true if `::URI` has a scheme (e.g.
#coerce	Args.
#component	Components of the `::URI` in the order.
#decoded_password	Returns the password component after `::URI` decoding.
#decoded_user	Returns the user component after `::URI` decoding.
#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`.
#to_str	Alias for Generic#to_s.
#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	Protected setter for the `user` component, and `password` if available (with validation).
#check_host	Checks the host `v` component for RFC2396 compliance and against the Parser Regexp for `:HOST`.
#check_opaque	Checks the opaque `v` component for RFC2396 compliance and against the Parser Regexp for `:OPAQUE`.
#check_password	Checks the password `v` component for RFC2396 compliance and against the Parser Regexp for `:USERINFO`.
#check_path	Checks the path `v` component for RFC2396 compliance and against the Parser Regexp for `:ABS_PATH` and `:REL_PATH`.
#check_port	Checks the port `v` component for RFC2396 compliance and against the Parser Regexp for `:PORT`.
#check_scheme	Checks the scheme `v` component against the Parser Regexp for `:SCHEME`.
#check_user	Checks the user `v` component for RFC2396 compliance and against the Parser Regexp for `:USERINFO`.
#check_userinfo	Checks 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!	Replaces 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'

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

uri2 = URI::FTP.build({:host => 'ftp.example.com',
  :path => 'ruby/src'})
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 47


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 ftp://john@ftp.example.com/my_file.img>
uri.typecode = "i"
uri
#=> #<URI::FTP ftp://john@ftp.example.com/my_file.img;type=i>

[ GitHub ]

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


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

Instance Method Details

#check_typecode(v) (private)

Validates typecode v, returns true or false.

[ 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 214


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 to 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://ftp.example.com/%2Fpub/ruby

This method will then return “/pub/ruby”.

[ GitHub ]

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


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 245


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 251


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

`::URI` - Included

`Generic` - Inherited

`Generic` - Inherited

`Generic` - Inherited

`Generic` - Inherited

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