Codec.Archive.LibZip

Monadic interface to libzip.

Most of the operations on zip archive happen within Archive monad (see withArchive). Partial reading of the files in the archive may be performed from within Entry monad (see fromFile). Both Archive and Entry are monad transformers over IO, and allow for IO with single and double lifting respectingly.

Note: LibZip does not handle text encodings. Even if its API accepts Strings (e.g. in sourceBuffer), character codes above 255 should not be used. The user is responsible of proper encoding the text data.

Examples

List files in the zip archive:

import System.Environment (getArgs)
import Codec.Archive.LibZip

main = do
  (zipfile:_) <- getArgs
  files <- withArchive [] zipfile $ fileNames []
  mapM_ putStrLn files

Create a zip archive and a add file to the archive:

import System.Environment (getArgs)
import Codec.Archive.LibZip

main = do
  (zipfile:_) <- getArgs
  withArchive [CreateFlag] zipfile $ do
     zs <- sourceBuffer "Hello World!"
     addFile "hello.txt" zs

Extract and print a file from the zip archive:

import System.Environment (getArgs)
import Codec.Archive.LibZip

main = do
  (zipfile:file:_) <- getArgs
  bytes <- withArchive [] zipfile $ fileContents [] file
  putStrLn bytes

See also an implementation of a simple zip archiver hzip.hs in the examples/ directory of the source distribution.

Types

type Archive a = StateT Zip IO a

Monadic computation with a zip archive. See withArchive.

type Entry a = StateT (ZipFile, Integer, [FileFlag]) (StateT Zip IO) a

Monadic computation to read from open archive entries. See fromFile and fromFileIx.

data ZipStat

File statistics expressed in native Haskell types.

Constructors

ZipStat

Fields

zs'valid :: Word64

zs'name :: String

zs'index :: Integer

zs'size :: Integer

zs'comp_size :: Integer

zs'mtime :: UTCTime

zs'crc :: Word

zs'comp_method :: ZipCompMethod

zs'encryption_method :: ZipEncryptionMethod

zs'flags :: Word32

Instances

Eq ZipStat

Show ZipStat

Archive operations

withArchive

Arguments

:: [OpenFlag]

Checks for consistency or existence.

-> FilePath

Filename of the zip archive.

-> Archive a

Action to do with the archive.

-> IO a

Top-level wrapper for operations with an open archive. withArchive opens and closes the file automatically. On error it throws ZipError.

getZip :: Archive Zip

Get archive handler. Throw ErrINVAL if the archive is closed.

numFiles :: [FileFlag] -> Archive Integer

Get the number of entries in the archive.

fileName

Arguments

:: [FileFlag]

FileUNCHANGED flag can be used.

-> Integer

Position index of a file in the archive.

-> Archive FilePath

Name of the file in the archive.

Get name of an entry in the archive by its index.

nameLocate

Arguments

:: [FileFlag]

Filename lookup mode.

-> FilePath

Name of the file in the archive.

-> Archive (Maybe Integer)

Just position index if found.

Locate an entry (get its index) in the archive by its name.

fileNames

Arguments

:: [FileFlag]

FileUNCHANGED flag is accepted.

-> Archive [FilePath]

Get names of all entries (files and directories) in the archive.

fileSize

Arguments

:: [FileFlag]

Filename lookup mode, FileUNCHANGED can be used.

-> FilePath

Name of the file in the archive.

-> Archive Integer

File size.

Get size of a file in the archive.

fileSizeIx

Arguments

:: [FileFlag]

FileUNCHANGED is accepted.

-> Integer

Position index of a file in the archive.

-> Archive Integer

File size.

Get size of a file in the archive (by index).

fileStat

Arguments

:: [FileFlag]

Filename lookup mode, FileUNCHANGED can be used.

-> FilePath

Name of the file in the archive.

-> Archive ZipStat

Infomation about the file.

Get information about a file in the archive.

fileStatIx

Arguments

:: [FileFlag]

FileUNCHANGED can be used.

-> Integer

Position index of a file in the archive.

-> Archive ZipStat

Information about the file.

Get information about a file in the archive (by index).

deleteFile

Arguments

:: [FileFlag]

Filename lookup mode.

-> FilePath

Filename.

-> Archive ()

Delete file from the archive.

deleteFileIx

Arguments

:: Integer

Position index of a file in the archive.

-> Archive ()

Delete file (referenced by position index) from the archive.

renameFile

Arguments

:: [FileFlag]

Filename lookup mode.

-> FilePath

Old name.

-> FilePath

New name.

-> Archive ()

Rename file in the archive.

renameFileIx

Arguments

:: Integer

Position index of a file in the archive.

-> FilePath

New name.

-> Archive ()

Rename file (referenced by position index) in the archive.

addFile

Arguments

:: FilePath

Name of the file to create.

-> ZipSource

Source where file data is obtained from.

-> Archive Int

Position index of the new file.

Add a file to the archive.

addDirectory

Arguments

:: FilePath

Directory's name in the archive.

-> Archive Int

Position index of the new directory entry.

Add a directory to the archive.

replaceFile

Arguments

:: [FileFlag]

Filename lookup mode.

-> FilePath

File to replace.

-> ZipSource

Source where the new file data is obtained from.

-> Archive ()

Replace a file in the archive.

replaceFileIx

Arguments

:: Integer

Position index of a file in the archive.

-> ZipSource

Source where the new file data is obtained from

-> Archive ()

Replace a file in the archive (referenced by position index).

sourceBuffer :: Enum a => [a] -> Archive ZipSource

Create a data source. Note: input is converted to [Word8] internally.

sourceFile

Arguments

:: FilePath

File to open.

-> Integer

Offset from the beginning of the file.

-> Integer

The number of bytes to read. If 0 or -1, the read till the end of file.

-> Archive ZipSource

Create a data source from a file.

sourceZip

Arguments

:: [FileFlag]

FileUNCHANGED and FileRECOMPRESS can be used.

-> Zip

Source archive.

-> Integer

Position index of a file in the source archive.

-> Integer

Offset from the beginning of the file.

-> Integer

The number of bytes to read. If 0 or -1, then read till the end of file.

-> Archive ZipSource

Create a data source from a file in the zip archive.

data PureSource a st szt

Wrapper for a user-provided pure function to be used with sourcePure. Data size should be known in advance (srcSize). The function should support reading by chunks (readSrc).

Constructors

PureSource

Fields

srcState :: st

Initial state of the source.

srcSize :: szt

Total size of the data.

srcMTime :: Maybe UTCTime

Modification time (current time if Nothing).

readSrc :: szt -> st -> Maybe (szt, [a], st)

Read a chunk of the data, return Just the size of data read, the data themselves and the new state of the source, or Nothing on error.

sourcePure :: (Enum a, Storable a, Storable st, Integral szt) => PureSource a st szt -> Archive ZipSource

Create a data source from a PureSource. Note: input of [a] is converted to [Word8] internally.

getComment

Arguments

:: [FileFlag]

FileUNCHANGED can be used.

-> Archive (Maybe String)

Get zip archive comment.

setComment

Arguments

:: String

Comment message.

-> Archive ()

Set zip archive comment.

removeComment :: Archive ()

Remove zip archive comment.

getFileComment

Arguments

:: [FileFlag]

Filename lookup mode.

-> FilePath

Filename

-> Archive (Maybe String)

Get comment for a file in the archive.

getFileCommentIx

Arguments

:: [FileFlag]

FileUNCHANGED can be used.

-> Integer

Position index of the file.

-> Archive (Maybe String)

Get comment for a file in the archive (referenced by position index).

setFileComment

Arguments

:: [FileFlag]

Name lookup mode.

-> FilePath

Filename.

-> String

New file comment.

-> Archive ()

Set comment for a file in the archive.

setFileCommentIx

Arguments

:: Integer

Position index of a file in the archive.

-> String

New file comment.

-> Archive ()

Set comment for a file in the archive (referenced by position index).

removeFileComment

Arguments

:: [FileFlag]

Filename lookup mode.

-> FilePath

Filename.

-> Archive ()

Remove comment for a file in the archive.

removeFileCommentIx

Arguments

:: Integer

Position index of a file in the archive.

-> Archive ()

Remove comment for a file in the archive (referenced by position index).

unchangeFile

Arguments

:: [FileFlag]

Filename lookup mode.

-> FilePath

Filename.

-> Archive ()

Undo changes to a file in the archive.

unchangeFileIx

Arguments

:: Integer

Position index of a file in the archive.

-> Archive ()

Undo changes to a file in the archive (referenced by position index).

unchangeArchive :: Archive ()

Undo global changes to zip archive (revert changes to the archive comment and global flags).

unchangeAll :: Archive ()

Undo all changes in a zip archive.

File reading operations

fromFile

Arguments

:: [FileFlag]

Filename lookup mode, FileCOMPRESSED and FileUNCHANGED can be used.

-> FilePath

Name of the file in the arhive.

-> Entry a

Action with the file.

-> Archive a

Wrapper for operations with a file in the archive. fromFile is normally called from within an Archive action (see also withArchive). fromFile can be replaced with fileContents to read an entire file at once.

fromFileIx

Arguments

:: [FileFlag]

FileCOMPRESSED and FileUNCHANGED can be used.

-> Integer

Position index of a file in the archive.

-> Entry a

Action with the file.

-> Archive a

Wrapper for operations with a file in the archive. File is referenced by index (position). fromFileIx is normally called from within an Archive action (see also withArchive). fromFileIx can be replaced with fileContentsIx to read an entire file at once.

readBytes

Arguments

:: Enum a

=> Integer

The number of bytes to read.

-> Entry [a]

Bytes read.

Read at most n bytes from the file.

skipBytes :: Integer -> Entry ()

Skip n bytes from the open file. Note: this is not faster than reading.

readContents

Arguments

:: Enum a

=> Entry [a]

Contents of the file.

Read entire file contents.

fileContents :: Enum a => [FileFlag] -> FilePath -> Archive [a]

Read entire file. Shortcut for readContents from within Archive monad.

fileContentsIx :: Enum a => [FileFlag] -> Integer -> Archive [a]

Read entire file (referenced by position index). Shortcut for readContents from within Archive monad.

Flags and options

data OpenFlag

Flags for opening an archive.

Constructors

CreateFlag

Create an archive if it does not exist.

ExclFlag

Error if the archive already exists.

CheckConsFlag

Check archive's consistency and error on failure.

Instances

Enum OpenFlag

Eq OpenFlag

Show OpenFlag

data FileFlag

Flags for accessing files in the archive. Please consult libzip documentation about their use.

Constructors

FileNOCASE

Ignore case on name lookup.

FileNODIR

Ignore directory component.

FileCOMPRESSED

Read the compressed data.

FileUNCHANGED

Read the original data, ignore changes.

FileRECOMPRESS

Force recompression of data.

FileENCRYPTED

Read encrypted data (implies FileCOMPRESSED).

Instances

Enum FileFlag

Eq FileFlag

Show FileFlag

data ZipCompMethod

Compression methods.

Constructors

CompDEFAULT

Better of deflate or store.

CompSTORE

Stored (uncompressed).

CompSHRINK

Shrunk.

CompREDUCE_1

Reduced with factor 1

CompREDUCE_2

Reduced with factor 2

CompREDUCE_3

Reduced with factor 3

CompREDUCE_4

Reduced with factor 4

CompIMPLODE

Imploded.

CompDEFLATE

Deflated.

CompDEFLATE64

Deflate64.

CompPKWARE_IMPLODE

PKWARE imploding.

CompBZIP2

Compressed using BZIP2 algorithm.

CompLZMA

LZMA (EFS)

CompTERSE

Compressed using IBM TERSE (new).

CompLZ77

IBM LZ77 z Architecture (PFS).

CompWAVPACK

WavPack compressed data.

CompPPMD

PPMd version I, Rev 1.

Instances

Enum ZipCompMethod

Eq ZipCompMethod

Show ZipCompMethod

data ZipEncryptionMethod

Encryption methods.

Constructors

EncryptNONE

Not encrypted.

EncryptTRAD_PKWARE

Traditional PKWARE encryption.

EncryptUNKNOWN

Unknown algorithm.

Instances

Enum ZipEncryptionMethod

Eq ZipEncryptionMethod

Show ZipEncryptionMethod

Exception handling

data ZipError

libzip error codes.

Constructors

ErrOK

No error.

ErrMULTIDISK

Multi-disk zip archives not supported.

ErrRENAME

Renaming temporary file failed.

ErrCLOSE

Closing zip archive failed.

ErrSEEK

Seek error.

ErrREAD

Read error.

ErrWRITE

Write error.

ErrCRC

CRC error.

ErrZIPCLOSED

Containing zip archive was closed.

ErrNOENT

No such file.

ErrEXISTS

File already exists.

ErrOPEN

Can't open file.

ErrTMPOPEN

Failure to create temporary file.

ErrZLIB

Zlib error.

ErrMEMORY

Malloc error.

ErrCHANGED

Entry has been changed.

ErrCOMPNOTSUPP

Compression method not supported.

ErrEOF

Premature EOF.

ErrINVAL

Invalid argument.

ErrNOZIP

Not a zip archive.

ErrINTERNAL

Internal error.

ErrINCONS

Zip archive inconsistent.

ErrREMOVE

Can't remove file.

ErrDELETED

Entry has been deleted.

ErrENCRNOTSUPP

Encryption method not supported.

ErrRDONLY

Read-only archive.

ErrNOPASSWD

No password provided.

ErrWRONGPASSWD

Wrong password provided.

Instances

Enum ZipError

Eq ZipError

Show ZipError

Typeable ZipError

Exception ZipError

catchZipError :: IO a -> (ZipError -> IO a) -> IO a

Wrapper to catch library errors.

Re-exports

lift :: MonadTrans t => forall m a. Monad m => m a -> t m a

Lift a computation from the argument monad to the constructed monad.