# Module Zip

    module Zip: sig .. end

Reading and writing ZIP archives

This module provides functions for reading and writing ZIP archive files. ZIP archives package one or more compressed files into a single ZIP file, along with information about the files, including file name, date and time of last modification, user-provided comments, and a checksum to verify the integrity of each entry. The entries of a ZIP file are not necessarily actual files, and can actually consist of arbitrary data.

The ZIP file format used in this module is compatible with that implemented by the popular `pkzip` archiver under Windows, and by the Info-ZIP `zip` and `unzip` commands under Unix and Windows. This format is also compatible with the JAR file format used by Java.

## Information on ZIP entries

    type compression_method =

`|` | `Stored` | `(*` | data is stored without compression | `*)`
`|` | `Deflated` | `(*` | data is compressed with the ``deflate'' algorithm | `*)`

Indicate whether the data in the entry is compressed or not.

    type entry = {

`` | `filename : `string`;` | `(*` | file name for entry | `*)`
`` | `comment : `string`;` | `(*` | comment attached to entry | `*)`
`` | `methd : `compression_method`;` | `(*` | compression method | `*)`
`` | `mtime : `float`;` | `(*` | last modification time (seconds since epoch) | `*)`
`` | `crc : `int32`;` | `(*` | cyclic redundancy check for data | `*)`
`` | `uncompressed_size : `int`;` | `(*` | size of original data in bytes | `*)`
`` | `compressed_size : `int`;` | `(*` | size of compressed data | `*)`
`` | `is_directory : `bool`;` | `(*` | whether this entry represents a directory | `*)`
`` | `file_offset : `int64`;` | `(*` | for internal use | `*)`

`}`

Description of an entry in a ZIP file.

## Reading from ZIP files

    type in_file

Abstract type representing a handle opened for reading from a ZIP file.

    val open_in : string -> in_file

`Zip.open_in zipfilename` opens the ZIP file with the given filename. The file must already exist. Return a handle opened for reading from this file.

    val entries : in_file -> entry list

Return a list of all entries in the given ZIP file.

    val comment : in_file -> string

Return the comment attached to the given ZIP file, or the empty string if none.

    val find_entry : in_file -> string -> entry

`Zip.find_entry zf filename` returns the description of the entry having name `filename` in the ZIP file `zf`. Raises `Not_found` if no such entry exists. The file name must match exactly; in particular, case is significant. File names must use `/` (slash) as the directory separator. The name of a directory must end with a trailing `/` (slash).

    val read_entry : in_file -> entry -> string

`Zip.read_entry zf e` reads and uncompresses the data (file contents) associated with entry `e` of ZIP file `zf`. The data is returned as a character string.

    val copy_entry_to_channel : in_file -> entry -> Stdlib.out_channel -> unit

`Zip.copy_entry_to_channel zf e oc` reads and uncompresses the data associated with entry `e` of ZIP file `zf`. It then writes this data to the output channel `oc`.

    val copy_entry_to_file : in_file -> entry -> string -> unit

`Zip.copy_entry_to_file zf e destfile` reads and uncompresses the data associated with entry `e` of ZIP file `zf`. It then writes this data to the file named `destfile`. The file `destfile` is created if it does not exist, and overwritten otherwise. The last modification date of the file is set to that indicated in the ZIP entry `e`, if possible.

    val close_in : in_file -> unit

Close the given ZIP file handle. If the ZIP file handle was created by `open_in_channel`, the underlying input channel is closed.

## Writing to ZIP files

    type out_file

Abstract type representing a handle opened for writing to a ZIP file.

    val open_out : ?comment:string -> string -> out_file

`Zip.open_out zipfilename` creates (or truncates to zero length) the ZIP file with the given filename. Return a handle opened for writing to this file.

`comment` : comment string attached to the ZIP file as as whole. Default: empty.

    val open_update : ?comment:string -> string -> out_file

`Zip.open_update zipfilename` opens the ZIP file with the given filename, preserving its contents. The file must already exist. Return a handle opened for writing to this file. Entries added via this handle will be added to the existing entries. If an entry is added with the same file name as an existing entry, the old entry becomes inaccessible, only the new entry remains.

`comment` : comment string attached to the ZIP file as as whole. Default: keep the comment that was attached to the original ZIP file.

    val add_entry : string ->
           out_file ->
           ?comment:string -> ?level:int -> ?mtime:float -> string -> unit

`Zip.add_entry data zf name` adds a new entry to the ZIP file `zf`. The data (file contents) associated with the entry is taken from the string `data`. It is compressed and written to the ZIP file `zf`. `name` is the file name stored along with this entry.

Under Windows, backslash characters in the `name` parameter are stored in the ZIP file as forward slashes `/`, for compatibility with other operating systems.

Several optional arguments can be provided to control the format and attached information of the entry:

`comment` : attached to the entry (a string). Default: empty.
`level` : compression level for the entry. This is an integer between 0 and 9, with 0 meaning no compression (store as is), 1 lowest compression, 9 highest compression. Higher levels result in smaller compressed data, but longer compression times. Default: 6 (moderate compression).
`mtime` : last modification time (in seconds since the epoch). Default: the current time.

    val copy_channel_to_entry : Stdlib.in_channel ->
           out_file ->
           ?comment:string -> ?level:int -> ?mtime:float -> string -> unit

Same as `Zip.add_entry`, but the data associated with the entry is read from the input channel given as first argument. The channel is read up to end of file.

    val copy_file_to_entry : string ->
           out_file ->
           ?comment:string -> ?level:int -> ?mtime:float -> string -> unit

Same as `Zip.add_entry`, but the data associated with the entry is read from the file whose name is given as first argument. Also, the default value for the `mtime` optional parameter is the time of last modification of the file.

    val add_entry_generator : out_file ->
           ?comment:string ->
           ?level:int ->
           ?mtime:float -> string -> (bytes -> int -> int -> unit) * (unit -> unit)

`Zip.add_entry_generator zf name` returns a pair of functions `(add, finish)`. It adds a new entry to the ZIP file `zf`. The file name stored along with this entry is `name`. Initially, no data is stored in this entry. To store data in this entry, the program must repeatedly call the `add` function returned by `Zip.add_entry_generator`. An invocation `add s ofs len` stores `len` characters of byte sequence `s` starting at offset `ofs` in the ZIP entry. When all the data forming the entry has been sent, the program must call the `finish` function returned by `Zip.add_entry_generator`. `finish` must be called exactly once. The optional arguments to `Zip.add_entry_generator` are as described in `Zip.add_entry`.

    val close_out : out_file -> unit

Finish writing the ZIP archive by adding the table of contents, and close it.

## Error reporting

    exception Error of string * string * string

Exception raised when an ill-formed ZIP archive is encountered, or illegal parameters are given to the functions in this module. The exception is of the form `Error(ZIP_name, entry_name, message)` where `ZIP_name` is the name of the ZIP file, `entry_name` the name of the offending entry, and `message` an explanation of the error.