This is the README for ARCHIVE, a package for reading an writing
disk-based file archives such as those generated by the 'tar' and 'cpio'
programs on Unix.  This package aspires to be a pure Common Lisp
replacement for the 'tar' program.

Current functionality includes basic extraction from and creation of tar
archives.  Basic extraction from certain kinds of cpio archives is also
supported.

ASDF packaging is provided; (asdf:oos 'asdf:load-op :archive) should be
all you need to get started.  Once you have the system loaded, you can
try the following small example, which replicates the functionality of
'tar tf':

(defun list-archive-entries (pathname)
  (archive:with-open-archive (archive pathname :direction :input)
    (archive:do-archive-entries (entry archive)
      (format t "~A~%" (archive:name entry)))))

Access to the data for individual entries is also provided.
ENTRY-STREAM returns a stream that provides access to the raw bytes of
data for the entry.  If you want to access it as text, you need to use a
library to encode the bytes into characters, or wrap the stream using
Edi Weitz's FLEXI-STREAMS.  The following example prints out the first
line of every file in the archive (assuming that the entry is a text
file, of course):

(defun first-line-of-archive-entries (pathname)
  (archive:with-open-archive (archive pathname :direction :input)
    (archive:do-archive-entries (entry archive)
      (when (archive:entry-regular-file-p entry)
        (let ((stream (flexi-streams:make-flexi-stream (entry-stream entry))))
          (format t "~A~%" (read-line stream)))))))

Another thing to do is create archives:

;;; This function is actually included in ARCHIVE.
(defun create-tar-file (pathname filelist)
  (archive:with-open-archive (archive pathname :direction :output
                                      :if-exists :supersede)
    (dolist (file filelist (archive:finalize-archive archive))
      (let ((entry (archive:create-entry-from-pathname archive file)))
        (archive:write-entry-to-archive archive entry)))))

Note that you need to call FINALIZE-ARCHIVE once you are done adding
entries.

Comments, criticisms, additions, and optimizations are welcome at the
below email address.

Nathan Froyd
froydnj@gmail.com