Module: Archive::Tar::Minitar

Module | Archive::Tar::Minitar
In: | lib/archive/tar/minitar.rb

# Archive::Tar::Minitar 0.5.2

Archive::Tar::Minitar is a pure-Ruby library and command-line utility that provides the ability to deal with POSIX tar(1) archive files. The implementation is based heavily on Mauricio Ferna‘ndez‘s implementation in rpa-base, but has been reorganised to promote reuse in other projects.

This tar class performs a subset of all tar (POSIX tape archive) operations. We can only deal with typeflags 0, 1, 2, and 5 (see Archive::Tar::PosixHeader). All other typeflags will be treated as normal files.

NOTE:: | support for typeflags 1 and 2 is not yet implemented in this version.

This release is version 0.5.2. The library can only handle files and directories at this point. A future version will be expanded to handle symbolic links and hard links in a portable manner. The command line utility, minitar, can only create archives, extract from archives, and list archive contents.

## Synopsis

Using this library is easy. The simplest case is:

      require 'zlib'
      require 'archive/tar/minitar'
      include Archive::Tar

        # Packs everything that matches Find.find('tests')
      File.open('test.tar', 'wb') { |tar| Minitar.pack('tests', tar) }
        # Unpacks 'test.tar' to 'x', creating 'x' if necessary.
      Minitar.unpack('test.tar', 'x')

A gzipped tar can be written with:

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

      tgz = Zlib::GzipReader.new(File.open('test.tgz', 'rb'))
        # Warning: tgz will be closed!
      Minitar.unpack(tgz, '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 = Output.new(sgz)
        Find.find('tests') do |entry|
          Minitar.pack_file(entry, tar)
        end
      ensure
          # Closes both tar and sgz.
        tar.close
      end

## Copyright

Copyright 2004 Mauricio Julio Ferna‘ndez Pradier and Austin Ziegler

This program is based on and incorporates parts of RPA::Package from rpa-base (lib/rpa/package.rb and lib/rpa/util.rb) by Mauricio and has been adapted to be more generic by Austin.

‘minitar’ contains an adaptation of Ruby/ProgressBar by Satoru Takabayashi <satoru@namazu.org>, copyright 2001 - 2004.

This program is free software. It may be redistributed and/or modified under the terms of the GPL version 2 (or later) or Ruby‘s licence.

### Methods

dir? open pack pack_file unpack

### Classes and Modules

Module Archive::Tar::Minitar::Command
Class Archive::Tar::Minitar::BlockRequired
Class Archive::Tar::Minitar::ClosedStream
Class Archive::Tar::Minitar::FileNameTooLong
Class Archive::Tar::Minitar::Input
Class Archive::Tar::Minitar::NonSeekableStream
Class Archive::Tar::Minitar::Output
Class Archive::Tar::Minitar::Reader
Class Archive::Tar::Minitar::UnexpectedEOF
Class Archive::Tar::Minitar::Writer

### Constants

VERSION | = | "0.5.2"

### Public Class methods

dir?(path)

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

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

A convenience method for wrapping Archive::Tar::Minitar::Input.open (mode `r`) and Archive::Tar::Minitar::Output.open (mode `w`). No other modes are currently supported.

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

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 Archive::Tar::Minitar::Output stream; if `recurse_dirs` is true, then directories will be recursed.

If `src` is an Array, it will be treated as the argument to Find.find; all files matching will be packed.

pack_file(entry, outputter) {|:file_start, name, stats if block_given?| ...}

A convenience method to packs 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 tarchive. 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` Symol, the full name of the file being packed, and a Hash of statistical information, just as with Archive::Tar::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.

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

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

[Validate]