class Archive::Tar::External

This class encapsulates tar & zip operations.

Constants

VERSION

The version of the archive-tar-external library.

Attributes

archive_name[RW]

The name of the archive file to be used, e.g. “test.tar”

compressed_archive_name[R]

The name of the archive file after compression, e.g. “test.tar.gz”

format[R]

The format of the archive file. The default is “pax”.

tar_program[RW]

The name of the tar program you wish to use. The default is “tar”.

Public Class Methods

expand(archive, *files)
Alias for: extract_archive
expand_archive(archive, *files)
Alias for: extract_archive
extract(archive, *files)
Alias for: extract_archive
extract_archive(archive, *files) click to toggle source

A class method that behaves identically to the equivalent instance method, except that you must specifiy that tarball as the first argument. Also, the tar program is hard coded to 'tar xf'.

# File lib/archive/tar/external.rb, line 244
def self.extract_archive(archive, *files)
  cmd = "tar xf #{archive}"
  cmd = "#{cmd} #{files.join(' ')}" unless files.empty?

  Open3.popen3(cmd) do |_ain, _aout, aerr|
    err = aerr.gets
    raise Error, err.chomp if err
  end

  self
end
Also aliased as: expand_archive, extract, expand
new(archive_name, file_pattern = nil, program = nil, format = 'pax') click to toggle source

Returns an Archive::Tar::External object. The archive_name is the name of the tarball. While a .tar extension is recommended based on years of convention, it is not enforced.

Note that this does not actually create the archive unless you pass a value to file_pattern. This then becomes a shortcut for Archive::Tar::External.new + Archive::Tar::External#create_archive.

If program is provided, then it compresses the archive as well by calling Archive::Tar::External#compress_archive internally.

You may also specify an archive format. As of version 1.5, the default is 'pax'. Previous versions used whatever your tar program used by default.

# File lib/archive/tar/external.rb, line 49
def initialize(archive_name, file_pattern = nil, program = nil, format = 'pax')
  @archive_name            = archive_name.to_s
  @compressed_archive_name = nil
  @tar_program             = 'tar'
  @format                  = 'pax'

  create_archive(file_pattern) if file_pattern
  compress_archive(program) if program
end
uncompress(archive, program = 'gunzip')
Alias for: uncompress_archive
uncompress_archive(archive, program = 'gunzip') click to toggle source

Uncompress an existing archive, using program to uncompress it. The default decompression program is gunzip.

# File lib/archive/tar/external.rb, line 148
def self.uncompress_archive(archive, program = 'gunzip')
  cmd = "#{program} #{archive}"

  Open3.popen3(cmd) do |_prog_in, _prog_out, prog_err|
    err = prog_err.gets
    raise CompressError, err.chomp if err
  end
end
Also aliased as: uncompress

Public Instance Methods

add(*files)
Alias for: add_to_archive
add_to_archive(*files) click to toggle source

Adds files to an already existing archive.

# File lib/archive/tar/external.rb, line 184
def add_to_archive(*files)
  raise Error, 'there must be at least one file specified' if files.empty?

  cmd = "#{@tar_program} rf #{@archive_name} #{files.join(' ')}"

  Open3.popen3(cmd) do |_ain, _aout, aerr|
    err = aerr.gets
    raise Error, err.chomp if err
  end
  self
end
Also aliased as: add
archive_info() click to toggle source

Returns an array of file names that are included within the tarball. This method does not extract the archive.

# File lib/archive/tar/external.rb, line 164
def archive_info
  result = []
  cmd = "#{@tar_program} tf #{@archive_name}"

  Open3.popen3(cmd) do |_ain, aout, aerr|
    err = aerr.gets
    raise Error, err.chomp if err

    while (output = aout.gets)
      result << output.chomp
    end
  end

  result
end
Also aliased as: info
compress(program = 'gzip')
Alias for: compress_archive
compress_archive(program = 'gzip') click to toggle source

Compresses the archive with program, or gzip if no program is provided. If you want to pass arguments to program, merely include them as part of the program name, e.g. “gzip -f”.

Any errors that occur here will raise a Tar::CompressError.

# File lib/archive/tar/external.rb, line 102
def compress_archive(program = 'gzip')
  cmd = "#{program} #{@archive_name}"

  Open3.popen3(cmd) do |_prog_in, _prog_out, prog_err|
    err = prog_err.gets
    raise CompressError, err.chomp if err

    # Find the new file name with the extension.  There's probably a more
    # reliable way to do this, but this should work 99% of the time.
    name = Dir["#{@archive_name}.{gz,bz2,cpio,zip}"].first
    @compressed_archive_name = name
  end

  self
end
Also aliased as: compress
compressed_archive_name=(name, ext = File.extname(name)) click to toggle source

Assign a compressed archive name. This autogenerates the archive_name based on the extension of the name provided, unless you provide the extension yourself. If the extension is '.tgz', then the base of the name + '.tar' will be the new archive name.

This should only be used if you have a pre-existing, compressed archive that you want to uncompress, and want to have a Tar::External object around. Otherwise, use the class method Tar::External.uncompress.

# File lib/archive/tar/external.rb, line 68
def compressed_archive_name=(name, ext = File.extname(name))
  if ext.downcase == '.tgz'
    @archive_name = File.basename(name, ext.downcase) << '.tar'
  else
    @archive_name = File.basename(name, ext)
  end
  @compressed_archive_name = name
end
create(file_pattern, options = 'cf')
Alias for: create_archive
create_archive(file_pattern, options = 'cf') click to toggle source

Creates the archive using file_pattern using options or 'cf' (create file) by default. The 'f' option should always be present and always be last.

Raises an Archive::Tar::Error if a failure occurs.

# File lib/archive/tar/external.rb, line 83
def create_archive(file_pattern, options = 'cf')
  cmd = "#{@tar_program} --format #{@format} -#{options} #{@archive_name} #{file_pattern}"

  Open3.popen3(cmd) do |_tar_in, _tar_out, tar_err|
    err = tar_err.gets
    raise Error, err.chomp if err
  end

  self
end
Also aliased as: create
expand(*files)
Alias for: extract_archive
expand_archive(*files)
Alias for: extract_archive
extract(*files)
Alias for: extract_archive
extract_archive(*files) click to toggle source

Expands the contents of the tarball. It does NOT delete the tarball. If files are provided, then only those files are extracted. Otherwise, all files are extracted.

Note that some tar programs, notably the tar program shipped by Sun, does not issue any sort of warning or error if you try to extract a file that does not exist in the archive.

# File lib/archive/tar/external.rb, line 224
def extract_archive(*files)
  cmd = "#{@tar_program} xf #{@archive_name}"
  cmd = "#{cmd} #{files.join(' ')}" unless files.empty?

  Open3.popen3(cmd) do |_ain, _aout, aerr|
    err = aerr.gets
    raise Error, err.chomp if err
  end

  self
end
Also aliased as: expand_archive, extract, expand
info()
Alias for: archive_info
uncompress(program = 'gunzip')
Alias for: uncompress_archive
uncompress_archive(program = 'gunzip') click to toggle source

Uncompresses the tarball using the program you pass to this method. The default is “gunzip”. Just as for compress_archive, you can pass arguments along as part of the argument.

Note that this is only for use with archives that have been zipped up with gunzip, or whatever. If you want to extract the files from the tarball, use Tar::External#extract instead.

Any errors that occur here will raise a Tar::CompressError.

# File lib/archive/tar/external.rb, line 130
def uncompress_archive(program = 'gunzip')
  raise CompressError, 'no compressed file found' unless @compressed_archive_name

  cmd = "#{program} #{@compressed_archive_name}"

  Open3.popen3(cmd) do |_prog_in, _prog_out, prog_err|
    err = prog_err.gets
    raise CompressError, err.chomp if err
    @compressed_archive_name = nil
  end
  self
end
Also aliased as: uncompress
update(*files)
Alias for: update_archive
update_archive(*files) click to toggle source

Updates the given files in the archive, i.e. they are added if they are not already in the archive or have been modified.

# File lib/archive/tar/external.rb, line 201
def update_archive(*files)
  raise Error, 'there must be at least one file specified' if files.empty?

  cmd = "#{@tar_program} uf #{@archive_name} #{files.join(' ')}"

  Open3.popen3(cmd) do |_ain, _aout, aerr|
    err = aerr.gets
    raise Error, err.chomp if err
  end

  self
end
Also aliased as: update