class Minitar::Writer::WriteOnlyStream

A stream wrapper that can only be written to. Any attempt to read from this restricted stream will result in a NameError being thrown.

Public Class Methods

new (io)

Source

# File lib/minitar/writer.rb, line 13
def initialize(io)
  @io = io
end

w = Minitar::Writer.open(STDOUT)

add_file_simple('foo.txt', :size → 3)

Source

# File lib/minitar/writer.rb, line 59
def self.open(io) # :yields: Writer
  writer = new(io)
  return writer unless block_given?

  # This exception context must remain, otherwise the stream closes on open even if
  # a block is not given.
  begin
    yield writer
  ensure
    writer.close
  end
end

With no associated block, Writer::open is a synonym for Writer::new. If the optional code block is given, it will be passed the new writer as an argument and the Writer object will automatically be closed when the block terminates. In this instance, Writer::open returns the value of the block.

Minitar::Writer.open(STDOUT) do |w| w.add_file_simple(‘foo.txt’, :size => 3) end

Public Instance Methods

add_file (name, opts = {}, &) { |WriteOnlyStream, +opts+| ... }

Source

# File lib/minitar/writer.rb, line 169
def add_file(name, opts = {}, &) # :yields: WriteOnlyStream, +opts+
  raise ClosedStream if @closed

  return add_file_simple(name, opts, &) if opts[:data]

  raise Minitar::NonSeekableStream unless Minitar.seekable?(@io)

  short_name, prefix, needs_long_name = split_name(name)

  data_offset = needs_long_name ? 3 * 512 : 512
  init_pos = @io.pos
  @io.write("\0" * data_offset) # placeholder for the header

  yield WriteOnlyStream.new(@io), opts

  size = @io.pos - (init_pos + data_offset)
  remainder = (512 - (size % 512)) % 512
  @io.write("\0" * remainder)

  final_pos, @io.pos = @io.pos, init_pos

  header = {
    mode: opts[:mode],
    mtime: opts[:mtime],
    size: size,
    gid: opts[:gid],
    uid: opts[:uid]
  }

  write_header(header, name, short_name, prefix, needs_long_name)

  @io.pos = final_pos
end

Adds a file to the archive as name. The data can be provided in the opts[:data] or provided to a yielded WriteOnlyStream. The size of the file will be determined from the amount of data written to the stream.

Valid parameters to opts are:

:mode:: The Unix file permissions mode value. If not provided, defaults to 0o644. :uid:: The Unix file owner user ID number. :gid:: The Unix file owner group ID number. :mtime:: File modification time, interpreted as an integer. :data:: Optional. The data to write to the archive.

If opts[:data] is provided, this acts the same as add_file_simple. Otherwise, the file’s size will be determined from the amount of data written to the stream.

For add_file to be used without opts[:data], the Writer must be wrapping a stream object that is seekable. Otherwise, add_file_simple must be used.

opts may be modified during the writing of the file to the stream.

add_file_simple('foo.txt', :data → "bar")

add_file_simple('foo.txt', :size → 3) do |w|

write("bar")

end

Source

# File lib/minitar/writer.rb, line 107
def add_file_simple(name, opts = {}) # :yields: BoundedWriteStream
  raise ClosedStream if @closed

  header = {
    mode: opts.fetch(:mode, 0o644),
    mtime: opts.fetch(:mtime, nil),
    gid: opts.fetch(:gid, nil),
    uid: opts.fetch(:uid, nil)
  }

  data = opts.fetch(:data, nil)
  size = opts.fetch(:size, nil)

  if block_given?
    raise ArgumentError, "Too much data (opts[:data] and block_given?)." if data
    raise ArgumentError, "No size provided" unless size
  else
    raise ArgumentError, "No data provided" unless data

    bytes = data.bytesize
    size = bytes if size.nil? || size < bytes
  end

  header[:size] = size

  short_name, prefix, needs_long_name = split_name(name)
  write_header(header, name, short_name, prefix, needs_long_name)

  os = BoundedWriteStream.new(@io, size)
  if block_given?
    yield os
  else
    os.write(data)
  end

  min_padding = size - os.written
  @io.write("\0" * min_padding)
  remainder = (512 - (size % 512)) % 512
  @io.write("\0" * remainder)
end

Adds a file to the archive as name. The data can be provided in the opts[:data] or provided to a BoundedWriteStream that is yielded to the provided block.

If opts[:data] is provided, all other values to opts are optional. If the data is provided to the yielded BoundedWriteStream, opts[:size] must be provided.

Valid parameters to opts are:

:data:: Optional. The data to write to the archive. :mode:: The Unix file permissions mode value. If not provided, defaults to 0o644. :size:: The size, in bytes. If :data is provided, this parameter may be ignored (if it is less than the size of the data provided) or used to add padding (if it is greater than the size of the data provided). :uid:: The Unix file owner user ID number. :gid:: The Unix file owner group ID number. :mtime:: File modification time, interpreted as an integer.

An exception will be raised if the Writer is already closed, or if more data is written to the BoundedWriteStream than expected.

close ()

Source

# File lib/minitar/writer.rb, line 253
def close
  return if @closed
  @io.write("\0" * 1024)
  @closed = true
end

Closes the Writer. This does not close the underlying wrapped output stream.

closed? (= @closed)

Source

# File lib/minitar/writer.rb, line 250
  def closed? = @closed

  # Closes the Writer. This does not close the underlying wrapped output stream.
  def close
    return if @closed
    @io.write("\0" * 1024)
    @closed = true
  end

  private

  def write_header(header, long_name, short_name, prefix, needs_long_name)
    if needs_long_name
      long_name_header = {
        prefix: "",
        name: PosixHeader::GNU_EXT_LONG_LINK,
        typeflag: "L",
        size: long_name.length + 1,
        mode: 0
      }
      @io.write(PosixHeader.new(long_name_header).to_s)
      @io.write(long_name)
      @io.write("\0" * (512 - (long_name.length % 512)))
    end

    new_header = header.merge({name: short_name, prefix: prefix})
    @io.write(PosixHeader.new(new_header).to_s)
  end

  def split_name(name)
    if name.bytesize <= 100
      prefix = ""
    else
      parts = name.split("/")
      newname = parts.pop

      nxt = ""

      loop do
        nxt = parts.pop || ""
        break if newname.bytesize + 1 + nxt.bytesize >= 100
        newname = "#{nxt}/#{newname}"
      end

      prefix = (parts + [nxt]).join("/")

      name = newname
    end

    [name, prefix, name.bytesize > 100 || prefix.bytesize > 155]
  end
end

Returns false if the writer is open.

flush ()

Source

# File lib/minitar/writer.rb, line 244
def flush
  raise ClosedStream if @closed
  @io.flush if @io.respond_to?(:flush)
end

Passes the flush method to the wrapped stream, used for buffered streams.

mkdir (name, opts = {})

Source

# File lib/minitar/writer.rb, line 204
def mkdir(name, opts = {})
  raise ClosedStream if @closed

  header = {
    mode: opts[:mode],
    typeflag: "5",
    size: 0,
    gid: opts[:gid],
    uid: opts[:uid],
    mtime: opts[:mtime]
  }

  short_name, prefix, needs_long_name = split_name(name)
  write_header(header, name, short_name, prefix, needs_long_name)

  nil
end

Creates a directory entry in the tar.

split_name (name)

Source

# File lib/minitar/writer.rb, line 279
def split_name(name)
  if name.bytesize <= 100
    prefix = ""
  else
    parts = name.split("/")
    newname = parts.pop

    nxt = ""

    loop do
      nxt = parts.pop || ""
      break if newname.bytesize + 1 + nxt.bytesize >= 100
      newname = "#{nxt}/#{newname}"
    end

    prefix = (parts + [nxt]).join("/")

    name = newname
  end

  [name, prefix, name.bytesize > 100 || prefix.bytesize > 155]
end

symlink (name, link_target, opts = {})

Source

# File lib/minitar/writer.rb, line 223
def symlink(name, link_target, opts = {})
  raise ClosedStream if @closed
  raise FileNameTooLong if link_target.size > 100

  name, prefix = split_name(name)
  header = {
    name: name,
    mode: opts[:mode],
    typeflag: "2",
    size: 0,
    linkname: link_target,
    gid: opts[:gid],
    uid: opts[:uid],
    mtime: opts[:mtime],
    prefix: prefix
  }
  @io.write(PosixHeader.new(header).to_s)
  nil
end

Creates a symbolic link entry in the tar.

write (data)

Source

# File lib/minitar/writer.rb, line 17
  def write(data) = @io.write(data)
end

write_header (header, long_name, short_name, prefix, needs_long_name)

Source

# File lib/minitar/writer.rb, line 261
def write_header(header, long_name, short_name, prefix, needs_long_name)
  if needs_long_name
    long_name_header = {
      prefix: "",
      name: PosixHeader::GNU_EXT_LONG_LINK,
      typeflag: "L",
      size: long_name.length + 1,
      mode: 0
    }
    @io.write(PosixHeader.new(long_name_header).to_s)
    @io.write(long_name)
    @io.write("\0" * (512 - (long_name.length % 512)))
  end

  new_header = header.merge({name: short_name, prefix: prefix})
  @io.write(PosixHeader.new(new_header).to_s)
end