class Archive::Tar::Minitar::Writer

The class that writes a tar format archive to a data stream.

Constants

WriteBoundaryOverflow

The exception raised when the user attempts to write more data to a BoundedWriteStream than has been allocated.

Public Class Methods

const_missing(c) click to toggle source
# File lib/archive/tar/minitar/writer.rb, line 59
def self.const_missing(c)
  case c
  when :BoundedStream
    warn 'BoundedStream has been renamed to BoundedWriteStream'
    const_set(:BoundedStream, BoundedWriteStream)
  else
    super
  end
end
new(io) click to toggle source

Creates and returns a new Writer object.

# File lib/archive/tar/minitar/writer.rb, line 97
def initialize(io)
  @io     = io
  @closed = false
end
w = Archive::Tar::Minitar::Writer.open(STDOUT) click to toggle source
add_file_simple('foo.txt', :size → 3)
close

With no associated block, +::open+ is a synonym for +::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, +::open+ returns the value of the block.

Archive::Tar::Minitar::Writer.open(STDOUT) do |w|
  w.add_file_simple('foo.txt', :size => 3)
end
# File lib/archive/tar/minitar/writer.rb, line 83
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

Public Instance Methods

add_file(name, opts = {}) { |write_only_stream, opts| ... } click to toggle source

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

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

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

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

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

  name, prefix = split_name(name)

  init_pos = @io.pos
  @io.write("\00"" * 512) # placeholder for the header

  yield WriteOnlyStream.new(@io), opts

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

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

  header = {
    :name => name,
    :mode => opts[:mode],
    :mtime => opts[:mtime],
    :size => size,
    :gid => opts[:gid],
    :uid => opts[:uid],
    :prefix => prefix
  }
  @io.write(PosixHeader.new(header))
  @io.pos = final_pos
end
add_file_simple('foo.txt', :data → "bar") click to toggle source
add_file_simple('foo.txt', :size → 3) do |w|
write("bar")
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 0644.

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

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

  header = {
    :prefix => prefix,
    :name   => name,
    :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?
    if data
      raise ArgumentError,
        'Too much data (opts[:data] and block_given?).'
    end

    raise ArgumentError, 'No size provided' unless size
  else
    raise ArgumentError, 'No data provided' unless data

    size = data.size if size < data.size
  end

  header[:size] = size

  @io.write(PosixHeader.new(header))

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

  min_padding = opts[:size] - os.written
  @io.write("\00"" * min_padding)
  remainder = (512 - (opts[:size] % 512)) % 512
  @io.write("\00"" * remainder)
end
close() click to toggle source

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

# File lib/archive/tar/minitar/writer.rb, line 269
def close
  return if @closed
  @io.write("\00"" * 1024)
  @closed = true
end
closed?() click to toggle source

Returns false if the writer is open.

# File lib/archive/tar/minitar/writer.rb, line 263
def closed?
  @closed
end
flush() click to toggle source

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

# File lib/archive/tar/minitar/writer.rb, line 257
def flush
  raise ClosedStream if @closed
  @io.flush if @io.respond_to?(:flush)
end
mkdir(name, opts = {}) click to toggle source

Creates a directory entry in the tar.

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

  name, prefix = split_name(name)
  header = {
    :name => name,
    :mode => opts[:mode],
    :typeflag => '5',
    :size => 0,
    :gid => opts[:gid],
    :uid => opts[:uid],
    :mtime => opts[:mtime],
    :prefix => prefix
  }
  @io.write(PosixHeader.new(header))
  nil
end