Class Net::SFTP::Operations::File
In: 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   eof?   gets   new   pos=   print   puts   read   readline   stat   write  

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)

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
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
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
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
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
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]