std.zip

Read and write data in the zip archive format.

Standards:

The current implementation mostly conforms to ISO/IEC 21320-1:2015, which means,

• that files can only be stored uncompressed or using the deflate mechanism,
• that encryption features are not used,
• that digital signature features are not used,
• that patched data features are not used, and
• that archives may not span multiple volumes.

Additionally, archives are checked for malware attacks and rejected if detected. This includes

• zip bombs which generate gigantic amounts of unpacked data
• zip archives that contain overlapping records
• chameleon zip archives which generate different unpacked data, depending on the implementation of the unpack algorithm

The current implementation makes use of the zlib compression library.

Usage

There are two main ways of usage: Extracting files from a zip archive and storing files into a zip archive. These can be mixed though (e.g. read an archive, remove some files, add others and write the new archive).

Examples:

Example for reading an existing zip archive:

import std.stdio : writeln, writefln;
import std.file : read;
import std.zip;

void main(string[] args)
{
    // read a zip file into memory
    auto zip = new ZipArchive(read(args[1]));

    // iterate over all zip members
    writefln("%-10s  %-8s  Name", "Length", "CRC-32");
    foreach (name, am; zip.directory)
    {
        // print some data about each member
        writefln("%10s  %08x  %s", am.expandedSize, am.crc32, name);
        assert(am.expandedData.length == 0);

        // decompress the archive member
        zip.expand(am);
        assert(am.expandedData.length == am.expandedSize);
    }
}

Example for writing files into a zip archive:

import std.file : write;
import std.string : representation;
import std.zip;

void main()
{
    // Create an ArchiveMembers for each file.
    ArchiveMember file1 = new ArchiveMember();
    file1.name = "test1.txt";
    file1.expandedData("Test data.\n".dup.representation);
    file1.compressionMethod = CompressionMethod.none; // don't compress

    ArchiveMember file2 = new ArchiveMember();
    file2.name = "test2.txt";
    file2.expandedData("More test data.\n".dup.representation);
    file2.compressionMethod = CompressionMethod.deflate; // compress

    // Create an archive and add the member.
    ZipArchive zip = new ZipArchive();

    // add ArchiveMembers
    zip.addMember(file1);
    zip.addMember(file2);

    // Build the archive
    void[] compressed_data = zip.build();

    // Write to a file
    write("test.zip", compressed_data);
}

License:

Boost License 1.0.

Authors:

Walter Bright

Source

std/zip.d

class ZipException: object.Exception;

Thrown on error.

enum CompressionMethod: ushort;

Compression method used by ArchiveMember.

none

No compression, just archiving.

deflate

Deflate algorithm. Use zlib library to compress.

class ArchiveMember;

A single file or directory inside the archive.

string name;

The name of the archive member; it is used to index the archive directory for the member. Each member must have a unique name. Do not change without removing member from the directory first.

ubyte[] extra;

The content of the extra data field for this member. See original documentation for a description of the general format of this data. May contain undocumented 3rd-party data.

string comment;

Comment associated with this member.

ushort flags;

Contains some information on how to extract this archive. See original documentation for details.

ushort internalAttributes;

Internal attributes. Bit 1 is set, if the member is apparently in binary format and bit 2 is set, if each record is preceded by the length of the record.

const pure nothrow @nogc @property @safe ushort extractVersion();

The zip file format version needed to extract this member.

Returns:

Format version needed to extract this member.

const pure nothrow @nogc @property @safe uint crc32();

Cyclic redundancy check (CRC) value.

Returns:

CRC32 value.

const pure nothrow @nogc @property @safe uint compressedSize();

Size of data of member in compressed form.

Returns:

Size of the compressed archive.

const pure nothrow @nogc @property @safe uint expandedSize();

Size of data of member in uncompressed form.

Returns:

Size of uncompressed archive.

deprecated const pure nothrow @nogc @property @safe ushort diskNumber();

Should be 0.

Returns:

The number of the disk where this member can be found.

pure nothrow @nogc @property @safe ubyte[] compressedData();

Data of member in compressed form.

Returns:

The file data in compressed form.

pure nothrow @nogc @property @safe ubyte[] expandedData();

@property @safe void expandedData(ubyte[] ed);

Get or set data of member in uncompressed form. When an existing archive is read ZipArchive.expand needs to be called before this can be accessed.

Parameters:

ubyte[] ed

Expanded Data.

Returns:

The file data.

@property @safe void fileAttributes(uint attr);

const nothrow @nogc @property uint fileAttributes();

Get or set the OS specific file attributes for this archive member.

Parameters:

uint attr

Attributes as obtained by std.file.getAttributes or std.file.DirEntry.attributes.

Returns:

The file attributes or 0 if the file attributes were encoded for an incompatible OS (Windows vs. POSIX).

const pure nothrow @nogc @property @safe DosFileTime time();

@property void time(SysTime time);

pure nothrow @nogc @property @safe void time(DosFileTime time);

Get or set the last modification time for this member.

Parameters:

SysTime time

Time to set (will be saved as DosFileTime, which is less accurate).

Returns:

The last modification time in DosFileFormat.

const pure nothrow @nogc @property @safe CompressionMethod compressionMethod();

pure @property @safe void compressionMethod(CompressionMethod cm);

Get or set compression method used for this member.

Parameters:

CompressionMethod cm

Compression method.

Returns:

Compression method.

See Also:

CompressionMethod

pure nothrow @nogc @property @safe uint index(uint value);

const pure nothrow @nogc @property @safe uint index();

The index of this archive member within the archive. Set this to a different value for reordering the members of an archive.

Parameters:

uint value

Index value to set.

Returns:

The index.

class ZipArchive;

Object representing the entire archive. ZipArchives are collections of ArchiveMembers.

string comment;

The archive comment. Must be less than 65536 bytes in length.

pure nothrow @nogc @property @safe ubyte[] data();

Array representing the entire contents of the archive.

Returns:

Data of the entire contents of the archive.

deprecated const pure nothrow @nogc @property @safe uint diskNumber();

0 since multi-disk zip archives are not supported.

Returns:

Number of this disk.

deprecated const pure nothrow @nogc @property @safe uint diskStartDir();

0 since multi-disk zip archives are not supported.

Returns:

Number of the disk, where the central directory starts.

deprecated const pure nothrow @nogc @property @safe uint numEntries();

const pure nothrow @nogc @property @safe uint totalEntries();

Number of ArchiveMembers in the directory.

Returns:

The number of files in this archive.

const pure nothrow @nogc @property @safe bool isZip64();

pure nothrow @nogc @property @safe void isZip64(bool value);

True when the archive is in Zip64 format. Set this to true to force building a Zip64 archive.

Parameters:

bool value

True, when the archive is forced to be build in Zip64 format.

Returns:

True, when the archive is in Zip64 format.

pure nothrow @nogc @property @safe ArchiveMember[string] directory();

Associative array indexed by the name of each member of the archive.

All the members of the archive can be accessed with a foreach loop:

Example

ZipArchive archive = new ZipArchive(data);
foreach (ArchiveMember am; archive.directory)
{
    writefln("member name is '%s'", am.name);
}

Returns:

Associative array with all archive members.

pure nothrow @nogc @safe this();

Constructor to use when creating a new archive.

@safe void addMember(ArchiveMember de);

Add a member to the archive. The file is compressed on the fly.

Parameters:

ArchiveMember de

Member to be added.

Throws:

ZipException when an unsupported compression method is used or when compression failed.

@safe void deleteMember(ArchiveMember de);

Delete member de from the archive. Uses the name of the member to detect which element to delete.

Parameters:

ArchiveMember de

Member to be deleted.

pure @safe void[] build();

Construct the entire contents of the current members of the archive.

Fills in the properties data[], totalEntries, and directory[]. For each ArchiveMember, fills in properties crc32, compressedSize, compressedData[].

Returns:

Array representing the entire archive.

Throws:

ZipException when the archive could not be build.

this(void[] buffer);

Constructor to use when reading an existing archive.

Fills in the properties data[], totalEntries, comment[], and directory[]. For each ArchiveMember, fills in properties madeVersion, extractVersion, flags, compressionMethod, time, crc32, compressedSize, expandedSize, compressedData[], internalAttributes, externalAttributes, name[], extra[], comment[]. Use expand() to get the expanded data for each ArchiveMember.

Parameters:

void[] buffer

The entire contents of the archive.

Throws:

ZipException when the archive was invalid or when malware was detected.

ubyte[] expand(ArchiveMember de);

Decompress the contents of a member.

Fills in properties extractVersion, flags, compressionMethod, time, crc32, compressedSize, expandedSize, expandedData[], name[], extra[].

Parameters:

ArchiveMember de

Member to be decompressed.

Returns:

The expanded data.

Throws:

ZipException when the entry is invalid or the compression method is not supported.