Class: Net::SFTP::Operations::File

Class | Net::SFTP::Operations::File
In: | lib/net/sftp/operations/file.rb lib/net/sftp/operations/file.rb
Parent: | Object

A wrapper around an SFTP file handle, that exposes an IO-like interface for interacting with the remote file. All operations are synchronous (blocking), making this a very convenient way to deal with remote files.

A wrapper is usually created via the Net::SFTP::Session#file factory:

      file = sftp.file.open("/path/to/remote")
      puts file.gets
      file.close

### Methods

close close eof? eof? gets gets new new pos= pos= print print puts puts read read readline readline stat stat write write

### Attributes

handle | [R] | The SFTP file handle object that this object wraps
handle | [R] | The SFTP file handle object that this object wraps
pos | [R] | The current position within the remote file
pos | [R] | The current position within the remote file
sftp | [R] | A reference to the Net::SFTP::Session instance that drives this wrapper
sftp | [R] | A reference to the Net::SFTP::Session instance that drives this wrapper

### Public Class methods

new(sftp, handle)

Creates a new wrapper that encapsulates the given `handle` (such as would be returned by Net::SFTP::Session#open!). The `sftp` parameter must be the same Net::SFTP::Session instance that opened the file.

[Source]

        # File lib/net/sftp/operations/file.rb, line 28
    28:     def initialize(sftp, handle)
    29:       @sftp     = sftp
    30:       @handle   = handle
    31:       @pos      = 0
    32:       @real_pos = 0
    33:       @real_eof = false
    34:       @buffer   = ""
    35:     end

new(sftp, handle)

Creates a new wrapper that encapsulates the given `handle` (such as would be returned by Net::SFTP::Session#open!). The `sftp` parameter must be the same Net::SFTP::Session instance that opened the file.

[Source]

        # File lib/net/sftp/operations/file.rb, line 28
    28:     def initialize(sftp, handle)
    29:       @sftp     = sftp
    30:       @handle   = handle
    31:       @pos      = 0
    32:       @real_pos = 0
    33:       @real_eof = false
    34:       @buffer   = ""
    35:     end

### Public Instance methods

close()

Closes the underlying file and sets the handle to `nil`. Subsequent operations on this object will fail.

[Source]

        # File lib/net/sftp/operations/file.rb, line 47
    47:     def close
    48:       sftp.close!(handle)
    49:       @handle = nil
    50:     end

close()

Closes the underlying file and sets the handle to `nil`. Subsequent operations on this object will fail.

[Source]

        # File lib/net/sftp/operations/file.rb, line 47
    47:     def close
    48:       sftp.close!(handle)
    49:       @handle = nil
    50:     end

eof?()

Returns true if the end of the file has been encountered by a previous read. Setting the current file position via pos= will reset this flag (useful if the file‘s contents have changed since the EOF was encountered).

[Source]

        # File lib/net/sftp/operations/file.rb, line 56
    56:     def eof?
    57:       @real_eof && @buffer.empty?
    58:     end

eof?()

Returns true if the end of the file has been encountered by a previous read. Setting the current file position via pos= will reset this flag (useful if the file‘s contents have changed since the EOF was encountered).

[Source]

        # File lib/net/sftp/operations/file.rb, line 56
    56:     def eof?
    57:       @real_eof && @buffer.empty?
    58:     end

gets(sep_string=$/)

Reads up to the next instance of `sep_string` in the stream, and returns the bytes read (including `sep_string`). If `sep_string` is omitted, it defaults to +$/+. If EOF is encountered before any data could be read, gets will return `nil`.

[Source]

         # File lib/net/sftp/operations/file.rb, line 86
     86:     def gets(sep_string=$/)
     87:       delim = if sep_string.length == 0
     88:         "#{$/}#{$/}"
     89:       else
     90:         sep_string
     91:       end
     92:
     93:       loop do
     94:         at = @buffer.index(delim)
     95:         if at
     96:           offset = at + delim.length
     97:           @pos += offset
     98:           line, @buffer = @buffer[0,offset], @buffer[offset..-1]
     99:           return line
    100:         elsif !fill
    101:           return nil if @buffer.empty?
    102:           @pos += @buffer.length
    103:           line, @buffer = @buffer, ""
    104:           return line
    105:         end
    106:       end
    107:     end

gets(sep_string=$/)

Reads up to the next instance of `sep_string` in the stream, and returns the bytes read (including `sep_string`). If `sep_string` is omitted, it defaults to +$/+. If EOF is encountered before any data could be read, gets will return `nil`.

[Source]

         # File lib/net/sftp/operations/file.rb, line 86
     86:     def gets(sep_string=$/)
     87:       delim = if sep_string.length == 0
     88:         "#{$/}#{$/}"
     89:       else
     90:         sep_string
     91:       end
     92:
     93:       loop do
     94:         at = @buffer.index(delim)
     95:         if at
     96:           offset = at + delim.length
     97:           @pos += offset
     98:           line, @buffer = @buffer[0,offset], @buffer[offset..-1]
     99:           return line
    100:         elsif !fill
    101:           return nil if @buffer.empty?
    102:           @pos += @buffer.length
    103:           line, @buffer = @buffer, ""
    104:           return line
    105:         end
    106:       end
    107:     end

pos=(offset)

Repositions the file pointer to the given offset (relative to the start of the file). This will also reset the EOF flag.

[Source]

        # File lib/net/sftp/operations/file.rb, line 39
    39:     def pos=(offset)
    40:       @real_pos = @pos = offset
    41:       @buffer = ""
    42:       @real_eof = false
    43:     end

pos=(offset)

Repositions the file pointer to the given offset (relative to the start of the file). This will also reset the EOF flag.

[Source]

        # File lib/net/sftp/operations/file.rb, line 39
    39:     def pos=(offset)
    40:       @real_pos = @pos = offset
    41:       @buffer = ""
    42:       @real_eof = false
    43:     end

print(*items)

Writes each argument to the stream. If +$+ is set, it will be written after all arguments have been written.

[Source]

         # File lib/net/sftp/operations/file.rb, line 129
    129:     def print(*items)
    130:       items.each { |item| write(item) }
    131:       write($\) if $\
    132:       nil
    133:     end

print(*items)

Writes each argument to the stream. If +$+ is set, it will be written after all arguments have been written.

[Source]

         # File lib/net/sftp/operations/file.rb, line 129
    129:     def print(*items)
    130:       items.each { |item| write(item) }
    131:       write($\) if $\
    132:       nil
    133:     end

puts(*items)

Writes each argument to the stream, appending a newline to any item that does not already end in a newline. Array arguments are flattened.

[Source]

         # File lib/net/sftp/operations/file.rb, line 137
    137:     def puts(*items)
    138:       items.each do |item|
    139:         if Array === item
    140:           puts(*item)
    141:         else
    142:           write(item)
    143:           write("\n") unless item[-1] == ?\n
    144:         end
    145:       end
    146:       nil
    147:     end

puts(*items)

Writes each argument to the stream, appending a newline to any item that does not already end in a newline. Array arguments are flattened.

[Source]

         # File lib/net/sftp/operations/file.rb, line 137
    137:     def puts(*items)
    138:       items.each do |item|
    139:         if Array === item
    140:           puts(*item)
    141:         else
    142:           write(item)
    143:           write("\n") unless item[-1] == ?\n
    144:         end
    145:       end
    146:       nil
    147:     end

read(n=nil)

Reads up to `n` bytes of data from the stream. Fewer bytes will be returned if EOF is encountered before the requested number of bytes could be read. Without an argument (or with a nil argument) all data to the end of the file will be read and returned.

This will advance the file pointer (pos).

[Source]

        # File lib/net/sftp/operations/file.rb, line 66
    66:     def read(n=nil)
    67:       loop do
    68:         break if n && @buffer.length >= n
    69:         break unless fill
    70:       end
    71:
    72:       if n
    73:         result, @buffer = @buffer[0,n], (@buffer[n..-1] || "")
    74:       else
    75:         result, @buffer = @buffer, ""
    76:       end
    77:
    78:       @pos += result.length
    79:       return result
    80:     end

read(n=nil)

Reads up to `n` bytes of data from the stream. Fewer bytes will be returned if EOF is encountered before the requested number of bytes could be read. Without an argument (or with a nil argument) all data to the end of the file will be read and returned.

This will advance the file pointer (pos).

[Source]

        # File lib/net/sftp/operations/file.rb, line 66
    66:     def read(n=nil)
    67:       loop do
    68:         break if n && @buffer.length >= n
    69:         break unless fill
    70:       end
    71:
    72:       if n
    73:         result, @buffer = @buffer[0,n], (@buffer[n..-1] || "")
    74:       else
    75:         result, @buffer = @buffer, ""
    76:       end
    77:
    78:       @pos += result.length
    79:       return result
    80:     end

readline(sep_string=$/)

Same as gets, but raises EOFError if EOF is encountered before any data could be read.

[Source]

         # File lib/net/sftp/operations/file.rb, line 111
    111:     def readline(sep_string=$/)
    112:       line = gets(sep_string)
    113:       raise EOFError if line.nil?
    114:       return line
    115:     end

readline(sep_string=$/)

Same as gets, but raises EOFError if EOF is encountered before any data could be read.

[Source]

         # File lib/net/sftp/operations/file.rb, line 111
    111:     def readline(sep_string=$/)
    112:       line = gets(sep_string)
    113:       raise EOFError if line.nil?
    114:       return line
    115:     end

stat()

Performs an fstat operation on the handle and returns the attribute object (Net::SFTP::Protocol::V01::Attributes, Net::SFTP::Protool::V04::Attributes, or Net::SFTP::Protocol::V06::Attributes, depending on the SFTP protocol version in use).

[Source]

         # File lib/net/sftp/operations/file.rb, line 153
    153:     def stat
    154:       sftp.fstat!(handle)
    155:     end

stat()

Performs an fstat operation on the handle and returns the attribute object (Net::SFTP::Protocol::V01::Attributes, Net::SFTP::Protool::V04::Attributes, or Net::SFTP::Protocol::V06::Attributes, depending on the SFTP protocol version in use).

[Source]

         # File lib/net/sftp/operations/file.rb, line 153
    153:     def stat
    154:       sftp.fstat!(handle)
    155:     end

write(data)

Writes the given data to the stream, incrementing the file position and returning the number of bytes written.

[Source]

         # File lib/net/sftp/operations/file.rb, line 119
    119:     def write(data)
    120:       data = data.to_s
    121:       sftp.write!(handle, @real_pos, data)
    122:       @real_pos += data.length
    123:       @pos = @real_pos
    124:       data.length
    125:     end

write(data)

Writes the given data to the stream, incrementing the file position and returning the number of bytes written.

[Source]

         # File lib/net/sftp/operations/file.rb, line 119
    119:     def write(data)
    120:       data = data.to_s
    121:       sftp.write!(handle, @real_pos, data)
    122:       @real_pos += data.length
    123:       @pos = @real_pos
    124:       data.length
    125:     end

[Validate]