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

### Home Classes Methods

### In Files

- lib/net/sftp/operations/file.rb

### Parent

Object

### Methods

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

### Files

- README.rdoc

### Class/Module Index

Quicksearch

- Net
- Net::SFTP
- Net::SFTP::Constants
- Net::SFTP::Constants::ACE
- Net::SFTP::Constants::ACE::Flag
- Net::SFTP::Constants::ACE::Mask
- Net::SFTP::Constants::ACE::Type
- Net::SFTP::Constants::LockTypes
- Net::SFTP::Constants::OpenFlags
- Net::SFTP::Constants::OpenFlags::FV1
- Net::SFTP::Constants::OpenFlags::FV5
- Net::SFTP::Constants::OpenFlags::FV6
- Net::SFTP::Constants::PacketTypes
- Net::SFTP::Constants::RenameFlags
- Net::SFTP::Constants::StatusCodes
- Net::SFTP::Exception
- Net::SFTP::Operations
- Net::SFTP::Operations::Dir
- Net::SFTP::Operations::Download
- Net::SFTP::Operations::File
- Net::SFTP::Operations::FileFactory
- Net::SFTP::Operations::Upload
- Net::SFTP::Packet
- Net::SFTP::Protocol
- Net::SFTP::Protocol::Base
- Net::SFTP::Protocol::V01
- Net::SFTP::Protocol::V01::Attributes
- Net::SFTP::Protocol::V01::Base
- Net::SFTP::Protocol::V01::Name
- Net::SFTP::Protocol::V02
- Net::SFTP::Protocol::V02::Base
- Net::SFTP::Protocol::V03
- Net::SFTP::Protocol::V03::Base
- Net::SFTP::Protocol::V04
- Net::SFTP::Protocol::V04::Attributes
- Net::SFTP::Protocol::V04::Base
- Net::SFTP::Protocol::V04::Name
- Net::SFTP::Protocol::V05
- Net::SFTP::Protocol::V05::Base
- Net::SFTP::Protocol::V06
- Net::SFTP::Protocol::V06::Attributes
- Net::SFTP::Protocol::V06::Base
- Net::SFTP::Request
- Net::SFTP::Response
- Net::SFTP::Session
- Net::SFTP::StatusException
- Net::SFTP::Version
- Net::SSH
- Net::SSH::Connection
- Net::SSH::Connection::Session

No matching classes.

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

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

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

[Validate]

Generated with the Darkfish Rdoc Generator 2.