NAME

spar -- Simple Perl ARchive manager

SYNOPSIS

spar command[ option ...] archive[ file ...]
spar utility

Creates or extracts a poor man's archive. Especially when containing lots of small files a spar can be by a factor smaller than a tar. And it can be conveniently edited, especially in Emacs.

Commands

-a, --append

This can add further files to an existing spar. If that is empty or inexistant, this is the same as --createdata.

-c, --create

Creates the archive of all given files as a self unpacking Perl script. If no files are given, archives the current directory.

-d, --createdata

Like --create, but the spar contains only the data. It will require either spar or the code output by spar --perlcode to unpack it. This is the default if the archive doesn't exist or is -, i.e. stdout.

-t, --table, --list

Show a table of contents.

-x, --extract, --get

Extract all files and directories contained in the archive.

Options

Currently these options are only applicable to the --append, --create and --createdata commands.

-E, --exclude=FILE

Exclude file FILE. FILE may be a full or relative path, or a simple filename to exclude in every directory it is found. FILE may contain Perl's wildcards ?, * and {,}. In that case it stands for zero or more actual files. You should protect these wildcards from the shell, by quoting them.

-X, --exclude-from=FILE

Exclude files listed in FILE. Each line is as in the --exclude option, except you must not protect wildcards.

Utilities

-e, --emacs, --emacsmode

Output an Emacs mode you can paste into your ~/.emacs for editing spars.

-p, --perl, --perlcode

Output code you can paste into your script to extract a spar. This can also be used for getting any files your script needs, right from the __DATA__ section.

DESCRIPTION

Creates or extracts a poor man's archive. Especially when containing lots of small files it can be by a factor smaller than a tar. Newlines are extracted in what Perl considers the local format. Due to this, spars with binary files are not portable to systems with different newline conventions.

Unlike tar it does not strip a leading / from filenames. If you want to do that, you must call spar in the root directory and give it relative paths.

Since everything becomes one text, this can be used for renaming files along with their content (refactoring). Such a need may arise in programming, where directory and file names will often reflect the packages or classes they contain. But from an operating system point of view, you modify these aspects in very different ways (e.g. mv and emacs).

Unlike one of the two par utilities available on the internet, the content here is completely separated from the extraction-code in Perl. (The other par is only a perl frontend to zip.)

FORMAT

The archive format is plain text. Special characters within the files or file names are not masked. All metadata resides on lines starting with ###\t. There are the following kinds of metadata:

SPAR url

This is the magic number on the first line of data-only spars. The url is from where you can download the spar program. This line is only informative and actually gets ignored.

D\tmode\tatime\tmtime\tname

This creates the directory name. name may contain any characters except for a newline. The mode is octal and atime and mtime are as in the utime function. The mode is only set after extracting the directory contents, so you can extract write-protected directories.

lines\tmode\tatime\tmtime\tname

This marks the next lines lines as the content of file name. Those lines are directly followed by the end of file, or another metadata line. Due to the lines-count, the file may istself contain lines matching spar-metadata (i.e. an embedded spar) without confusing spar. If lines is negative, the extracted file will not end with a newline. The mode is octal and atime and mtime are as in the utime function.

L\tH\t0\t0\tname

L\tS\t0\t0\tname

These create the link (H) or symlink (S) name. The name of the file linked to is on the following line. The mode and times of the links themselves are whatever the system makes them.

DOWNLOAD

You can get the latest version of spar from http://www.cpan.org/scripts/. Because makepp was the first to use this, it is hosted on CVS at http://cvs.sourceforge.net/viewcvs.py/makepp/makepp/makepp_tests/ and the subdirectory additional_tests/ contains a test-suite runnable by run_tests.pl, also from there.

AUTHOR

Daniel Pfeiffer <occitan@esperanto.org>