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

Inherits:
Object
  • Object
show all
Defined in:
lib/net/sftp/operations/file.rb

Overview

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(sftp, handle) ⇒ File

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.



28
29
30
31
32
33
34
35
 
# File 'lib/net/sftp/operations/file.rb', line 28

def initialize(sftp, handle)
  @sftp     = sftp
  @handle   = handle
  @pos      = 0
  @real_pos = 0
  @real_eof = false
  @buffer   = ""
end

Instance Attribute Details

#handle ⇒ Object (readonly)

The SFTP file handle object that this object wraps



20
21
22
 
# File 'lib/net/sftp/operations/file.rb', line 20

def handle
  @handle
end

#pos ⇒ Object

The current position within the remote file



23
24
25
 
# File 'lib/net/sftp/operations/file.rb', line 23

def pos
  @pos
end

#sftp ⇒ Object (readonly)

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



17
18
19
 
# File 'lib/net/sftp/operations/file.rb', line 17

def sftp
  @sftp
end

Instance Method Details

#close ⇒ Object

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



47
48
49
50
 
# File 'lib/net/sftp/operations/file.rb', line 47

def close
  sftp.close!(handle)
  @handle = nil
end

#eof? ⇒ Boolean

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

Returns:

  • (Boolean) 


56
57
58
 
# File 'lib/net/sftp/operations/file.rb', line 56

def eof?
  @real_eof && @buffer.empty?
end

#gets(sep_string = $/) ⇒ Object

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.



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/net/sftp/operations/file.rb', line 86

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

#print(*items) ⇒ Object

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



129
130
131
132
133
 
# File 'lib/net/sftp/operations/file.rb', line 129

def print(*items)
  items.each { |item| write(item) }
  write($\) if $\
  nil
end

#puts(*items) ⇒ Object

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



137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/net/sftp/operations/file.rb', line 137

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) ⇒ Object

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



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/net/sftp/operations/file.rb', line 66

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 = $/) ⇒ Object

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

Raises:

  • (EOFError) 


111
112
113
114
115
 
# File 'lib/net/sftp/operations/file.rb', line 111

def readline(sep_string=$/)
  line = gets(sep_string)
  raise EOFError if line.nil?
  return line
end

#stat ⇒ Object

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



153
154
155
 
# File 'lib/net/sftp/operations/file.rb', line 153

def stat
  sftp.fstat!(handle)
end

#write(data) ⇒ Object

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



119
120
121
122
123
124
125
 
# File 'lib/net/sftp/operations/file.rb', line 119

def write(data)
  data = data.to_s
  sftp.write!(handle, @real_pos, data)
  @real_pos += data.length
  @pos = @real_pos
  data.length
end