class Minitar

== Synopsis

Using minitar is easy. The simplest case is:

require 'zlib'
require 'minitar'

# Packs everything that matches Find.find('tests'). test.tar will automatically be
# closed by Minitar.pack.
Minitar.pack('tests', File.open('test.tar', 'wb'))

# Unpacks 'test.tar' to 'x', creating 'x' if necessary.
Minitar.unpack('test.tar', 'x')

A gzipped tar can be written with:

# test.tgz will be closed automatically.
Minitar.pack('tests', Zlib::GzipWriter.new(File.open('test.tgz', 'wb'))

# test.tgz will be closed automatically.
Minitar.unpack(Zlib::GzipReader.new(File.open('test.tgz', 'rb')), 'x')

As the case above shows, one need not write to a file. However, it will sometimes require that one dive a little deeper into the API, as in the case of StringIO objects. Note that I’m not providing a block with Minitar::Output, as Minitar::Output#close automatically closes both the Output object and the wrapped data stream object.

begin
  sgz = Zlib::GzipWriter.new(StringIO.new(""))
  tar = Minitar::Output.new(sgz)
  Find.find('tests') do |entry|
    Minitar.pack_file(entry, tar)
  end
ensure
    # Closes both tar and sgz.
  tar.close
end

Constants

ClosedStream: The exception raised when operations are performed on a stream that has previously been closed.
Error: The base class for any minitar error.
FileNameTooLong: The exception raised when a filename exceeds 256 bytes in length, the maximum supported by the standard Tar format.
InvalidTarStream: The exception raised when a file contains an invalid Posix header.
NonSeekableStream: Raised when a wrapped data stream class is not seekable.
SecureRelativePathError: The exception raised when a file contains a relative path in secure mode (the default for this version).
UnexpectedEOF: The exception raised when a data stream ends before the amount of data expected in the archive’s PosixHeader.
VERSION

Public Class Methods

dir? (path)

Source

# File lib/minitar.rb, line 68
def dir?(path)
  path = "#{path}/" unless path.to_s.end_with?("/")
  File.directory?(path)
end

Tests if path refers to a directory. Fixes an apparently corrupted stat() call on Windows.

open (dest, mode = "r", &)

Source

# File lib/minitar.rb, line 75
def open(dest, mode = "r", &)
  case mode
  when "r", "rb"
    Minitar::Input.open(dest, &)
  when "w", "wb"
    Minitar::Output.open(dest, &)
  else
    raise ArgumentError, "Unknown open mode for Minitar.open."
  end
end

A convenience method for wrapping Minitar::Input.open (mode r or +rb) and Minitar::Output.open (mode w or wb). No other modes are currently supported.

pack (src, dest, recurse_dirs = true, &block)

Source

# File lib/minitar.rb, line 228
def pack(src, dest, recurse_dirs = true, &block)
  require "find"
  Minitar::Output.open(dest) do |outp|
    if src.is_a?(Array)
      src.each do |entry|
        if dir?(entry) && recurse_dirs
          Find.find(entry) do |ee|
            pack_file(ee, outp, &block)
          end
        else
          pack_file(entry, outp, &block)
        end
      end
    else
      Find.find(src) do |entry|
        pack_file(entry, outp, &block)
      end
    end
  end
end

A convenience method to pack files specified by src into dest. If src is an Array, then each file detailed therein will be packed into the resulting Minitar::Output stream; if recurse_dirs is true, then directories will be recursed.

If src is not an Array, it will be treated as the result of Find.find; all files matching will be packed.

pack_as_file (entry, data, outputter) { |action, name, stats| ... }

Source

# File lib/minitar.rb, line 104
def pack_as_file(entry, data, outputter) # :yields: action, name, stats
  outputter = outputter.tar if outputter.is_a?(Minitar::Output)

  stats = {
    gid: nil,
    uid: nil,
    mtime: Time.now,
    size: data&.size || 0,
    mode: data ? 0o644 : 0o755
  }

  if entry.is_a?(Hash)
    name = entry[:name]
    entry.each_pair {
      next if _1 == :name
      stats[_1] = _2 unless _2.nil?
    }
  else
    name = entry
  end

  if data.nil? # Create a directory
    yield :dir, name, stats if block_given?
    outputter.mkdir(name, stats)
  else
    outputter.add_file_simple(name, stats) do |os|
      stats[:current] = 0
      yield :file_start, name, stats if block_given?

      StringIO.open(data, "rb") do |ff|
        until ff.eof?
          stats[:currinc] = os.write(ff.read(4096))
          stats[:current] += stats[:currinc]
          yield :file_progress, name, stats if block_given?
        end
      end

      yield :file_done, name, stats if block_given?
    end
  end
end

A convenience method to pack the provided data as a file named entry. entry may either be a name or a Hash with the fields described below. When only a name is provided, or only some Hash fields are provided, the default values will apply.

:name:: The filename to be packed into the archive. Required. :mode:: The mode to be applied. Defaults to 0o644 for files and 0o755 for directories. :uid:: The user owner of the file. Default is nil. :gid:: The group owner of the file. Default is nil. :mtime:: The modification Time of the file. Default is Time.now.

If data is nil, a directory will be created. Use an empty String for a normal empty file.

pack_file (entry, outputter) { |action, name, stats| ... }

Source

# File lib/minitar.rb, line 175
def pack_file(entry, outputter) # :yields: action, name, stats
  outputter = outputter.tar if outputter.is_a?(Minitar::Output)

  stats = {}

  if entry.is_a?(Hash)
    name = entry[:name]
    entry.each { |kk, vv| stats[kk] = vv unless vv.nil? }
  else
    name = entry
  end

  name = name.sub(%r{\./}, "")
  stat = File.stat(name)
  stats[:mode] ||= stat.mode
  stats[:mtime] ||= stat.mtime
  stats[:size] = stat.size

  if windows?
    stats[:uid] = nil
    stats[:gid] = nil
  else
    stats[:uid] ||= stat.uid
    stats[:gid] ||= stat.gid
  end

  if File.file?(name)
    outputter.add_file_simple(name, stats) do |os|
      stats[:current] = 0
      yield :file_start, name, stats if block_given?
      File.open(name, "rb") do |ff|
        until ff.eof?
          stats[:currinc] = os.write(ff.read(4096))
          stats[:current] += stats[:currinc]
          yield :file_progress, name, stats if block_given?
        end
      end
      yield :file_done, name, stats if block_given?
    end
  elsif dir?(name)
    yield :dir, name, stats if block_given?
    outputter.mkdir(name, stats)
  else
    raise "Don't yet know how to pack this type of file."
  end
end

A convenience method to pack the file provided. entry may either be a filename (in which case various values for the file (see below) will be obtained from File#stat(entry) or a Hash with the fields:

:name:: The filename to be packed into the archive. Required. :mode:: The mode to be applied. :uid:: The user owner of the file. (Ignored on Windows.) :gid:: The group owner of the file. (Ignored on Windows.) :mtime:: The modification Time of the file.

During packing, if a block is provided, pack_file yields an action Symbol, the full name of the file being packed, and a Hash of statistical information, just as with Minitar::Input#extract_entry.

The action will be one of: :dir:: The entry is a directory. :file_start:: The entry is a file; the extract of the file is just beginning. :file_progress:: Yielded every 4096 bytes during the extract of the entry. :file_done:: Yielded when the entry is completed.

The stats hash contains the following keys: :current:: The current total number of bytes read in the entry. :currinc:: The current number of bytes read in this read cycle. :name:: The filename to be packed into the tarchive. REQUIRED. :mode:: The mode to be applied. :uid:: The user owner of the file. (nil on Windows.) :gid:: The group owner of the file. (nil on Windows.) :mtime:: The modification Time of the file.

seekable? (io, methods = nil)

Source

# File lib/minitar.rb, line 268
def seekable?(io, methods = nil)
  # The IO class throws an exception at runtime if we try to change position on
  # a non-regular file.
  if io.respond_to?(:stat)
    io.stat.file?
  else
    # Duck-type the rest of this.
    methods ||= [:pos, :pos=, :seek, :rewind]
    methods = [methods] unless methods.is_a?(Array)
    methods.all? { |m| io.respond_to?(m) }
  end
end

Check whether io can seek without errors.

unpack (src, dest, files = [], options = {}, &block)

Source

# File lib/minitar.rb, line 251
def unpack(src, dest, files = [], options = {}, &block)
  Minitar::Input.open(src) do |inp|
    if File.exist?(dest) && !dir?(dest)
      raise "Can't unpack to a non-directory."
    end

    FileUtils.mkdir_p(dest) unless File.exist?(dest)

    inp.each do |entry|
      if files.empty? || files.include?(entry.full_name)
        inp.extract_entry(dest, entry, options, &block)
      end
    end
  end
end

A convenience method to unpack files from src into the directory specified by dest. Only those files named explicitly in files will be extracted.