CompressionPackageDesign: tango-compression-stuff.d

/**
 * IArchive models the basic actions you can perform on an archive.
 *
 * Users should be able to read from an archive by opening it, and using the
 * IArchiveEntry objects to read out the contents.
 *
 * Writing archives should be done by creating an empty archive, using
 * addFile() calls to attach files to the archive, and then a call to write()
 * to actually generate the archive.
 *
 * Modifying archives will be tricky, since the way this is usually done is to
 * simply create a new archive, splicing the new and old together.  Perhaps it
 * should be assumed that you can't write back to the same archive you've
 * already opened.  If you want to do things like that, you'll have to use a
 * temporary file...
 */
interface IArchive
{
    /**
     * Closes the archive, discarding all changes.
     */
    void close();

    /**
     * Writes the contents of the archive out to either a file on disk, or to
     * a conduit.
     */
    void write(char[] path);
    void write(Path path);
    void write(IConduit conduit);

    /**
     * Adds a file to the archive, reading from either a file on disk or a
     * conduit, and placing it in the given archive path.
     */
    void addFile(char[] path, char[] archivePath);
    void addFile(Path path, Path archivePath);
    void addFile(IConduit conduit, Path archivePath);

    /**
     * (Maybe)
     * Adds a directory and the files it contains to the archive.  The final
     * argument can be given as "false" to prevent recursively adding all
     * sub-directories as well.
     */
    void addDirectory(char[] path, char[] archivePath, bool recursive = true);
    void addDirectory(Path path, Path archivePath, bool recursive = true);

    /**
     * Removes a file from the archive.
     */
    void removeFile(char[] path);
    void removeFile(Path path);

    /**
     * Retrieves the archive entry for a given archive path.
     */
    IArchiveEntry getFile(char[] path);
    IArchiveEntry getFile(Path path);

    /**
     * (Maybe--would be nice to have, and provides symmetry to addFile)
     * Extracts the specified archive path to either a file on disk, or to a
     * conduit.
     */
    void extractFile(char[] path, char[] outPath);
    void extractFile(Path path, Path outPath);
    void extractFile(Path path, IConduit conduit);

    /**
     * Iterates over all files in the archive.
     */
    int opApply(int delegate(IArchiveEntry) dg);
    int opApply(int delegate(IArchiveEntry, size_t) dg);

    /**
     * Gets/sets the abstract compression level.
     *
     * This is either a good idea, or a really bad one.  The problem is that
     * this won't always make sense: for ZIP files, yeah; it makes sense.  But
     * for TAR files, it doesn't make any sense whatsoever (unless we give
     * TarFile.write magic powers to pick a compression codec from this value.
     *
     * It's worth thinking about, any way.
     */
    CompressionLevel compressionLevel();
    void compressionLevel(CompressionLevel level);
}

/**
 * These constants represent general compression levels that can be used
 * without having to actually know what the compression scheme is, or how it
 * works.
 *
 * However, whilst "Store" and "Maximum" are obviously useful, I'm not so sure
 * about the middle three.  Yeah, granularity is nice, but who's going to sit
 * there and think "Gee, I really think I need Medium on this one!"...
 */
enum CompressionLevel
{
    Store,
    Low,
    Medium,
    High,
    Maximum,
}

/**
 * An alternative to the above would be to define two additional interfaces:
 * IInternalCompression and IExternalCompression.  The first would be used
 * with formats like ZIP that compress their contents, and the second for
 * formats like TAR that are compressed in their entirety.
 *
 * IInternalCompression could expose something meaningful for ZIP-like files
 * (like compression level), whilst IExternalCompression could have a
 * reference to a compression codec to use.
 */

class TarFile : IArchive
{
    /**
     * Opens an existing tar file from either a file on disk or a conduit, and
     * decompresses it with the given codec.
     *
     * NOTE: there should exist a "magic" filter that automatically chooses
     * the appropriate filter based on either the file name or magic numbers.
     */
    this(char[] path, IConduitFilter codec = null);
    this(Path path, IConduitFilter codec = null);
    this(IConduit conduit, IConduitFilter codec = null);

    /**
     * Writes the archive to either disk or a conduit, and applies the given
     * compression codec to the stream.
     */
    void write(char[] path, IConduitFilter codec = null);
    void write(Path path, IConduitFilter codec = null);
    void write(IConduit conduit, IConduitFilter codec = null);
}

class ZipFile : IArchive
{
    /**
     * Opens an existing zip archive either from disk or from a conduit.
     */
    this(char[] path);
    this(Path path);
    this(IConduit conduit);
}

/**
 * IArchiveEntry combines a conduit for reading data out of the file, and some
 * basic metadata on the file itself.
 *
 * Archive entries should be assumed to be read-only and non-seekable, since
 * writing and seeking are a complete pain in the arse with archive formats
 * (especially compressed ones!).
 */
interface IArchiveEntry : IConduit
{
    char[]  filename;       // The entry's file name
    Time    lastModified;   // Modification time-stamp
    size_t  size;           // Uncompressed size
}

class TarEntry : IArchiveEntry
{
    uint            mode;   // Permission bits
    TarEntryType    type;   // File type (file, symlink, link, etc.)
    char[]          linkName; // Link target
    uint            userId, groupId;
    char[]          userName, groupName;
}

class ZipEntry : IArchiveEntry
{
    uint    compressType;   // More format-specific junk...
    char[]  comment;
    char[]  createSystem;
    uint    createVersion, extractVersion;
    uint    flagBits;
    uint    volume;
    size_t  compressedSize;
}