class Net::SFTP::Operations::File

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

Attributes

handle[R]

The SFTP file handle object that this object wraps

pos[R]

The current position within the remote file

sftp[R]

A reference to the Net::SFTP::Session instance that drives this wrapper

Public Class Methods

new(sftp, handle) click to toggle source

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.

# File lib/net/sftp/operations/file.rb, line 27
def initialize(sftp, handle)
  @sftp     = sftp
  @handle   = handle
  @pos      = 0
  @real_pos = 0
  @real_eof = false
  @buffer   = ""
end

Public Instance Methods

close() click to toggle source

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

# File lib/net/sftp/operations/file.rb, line 46
def close
  sftp.close!(handle)
  @handle = nil
end
eof?() click to toggle source

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).

# File lib/net/sftp/operations/file.rb, line 55
def eof?
  @real_eof && @buffer.empty?
end
gets(sep_string=$/) click to toggle source

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.

# File lib/net/sftp/operations/file.rb, line 85
def gets(sep_string=$/)
  delim = if sep_string.length == 0
    "#{$/}#{$/}"
  else
    sep_string
  end

  loop do
    at = @buffer.index(delim)
    if at
      offset = at + delim.length
      @pos += offset
      line, @buffer = @buffer[0,offset], @buffer[offset..-1]
      return line
    elsif !fill
      return nil if @buffer.empty?
      @pos += @buffer.length
      line, @buffer = @buffer, ""
      return line
    end
  end
end
pos=(offset) click to toggle source

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

# File lib/net/sftp/operations/file.rb, line 38
def pos=(offset)
  @real_pos = @pos = offset
  @buffer = ""
  @real_eof = false
end
print(*items) click to toggle source

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

puts(*items) click to toggle source

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

# File lib/net/sftp/operations/file.rb, line 136
def puts(*items)
  items.each do |item|
    if Array === item
      puts(*item)
    else
      write(item)
      write("\n") unless item[-1] == ?\n
    end
  end
  nil
end
read(n=nil) click to toggle source

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).

# File lib/net/sftp/operations/file.rb, line 65
def read(n=nil)
  loop do
    break if n && @buffer.length >= n
    break unless fill
  end

  if n
    result, @buffer = @buffer[0,n], (@buffer[n..-1] || "")
  else
    result, @buffer = @buffer, ""
  end

  @pos += result.length
  return result
end
readline(sep_string=$/) click to toggle source

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

# File lib/net/sftp/operations/file.rb, line 110
def readline(sep_string=$/)
  line = gets(sep_string)
  raise EOFError if line.nil?
  return line
end
stat() click to toggle source

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).

# File lib/net/sftp/operations/file.rb, line 152
def stat
  sftp.fstat!(handle)
end
write(data) click to toggle source

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

# File lib/net/sftp/operations/file.rb, line 118
def write(data)
  data = data.to_s
  sftp.write!(handle, @real_pos, data)
  @real_pos += data.length
  @pos = @real_pos
  data.length
end

Private Instance Methods

fill() click to toggle source

Fills the buffer. Returns true if it succeeded, and false if EOF was encountered before any data was read.

# File lib/net/sftp/operations/file.rb, line 160
def fill
  data = sftp.read!(handle, @real_pos, 8192)

  if data.nil?
    @real_eof = true
    return false
  else
    @real_pos += data.length
    @buffer << data
  end

  !@real_eof
end