LibZip-1.0.1: Bindings to libzip, a library for manipulating zip archives.

Safe HaskellSafe
LanguageHaskell98

Codec.Archive.LibZip

Contents

Description

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.

Synopsis

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.

Instances

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.

withEncryptedArchive #

Arguments

:: [OpenFlag]

Checks for consistency or existence.

-> String

Encryption password.

-> FilePath

Filename of the zip archive.

-> Archive a

Action to don with the archive.

-> IO a 

Top-level wrapper for operations with an open encrypted archive. withEncryptedArchive 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 #

Arguments

:: [FileFlag]

FileUNCHANGED can be used to return the original unchanged number of entries.

-> Archive Integer 

Get the number of entries in the archive.

fileName #

Arguments

:: [FileFlag]

FileUNCHANGED flag can be used to return the original unchanged filename.

-> 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. FileNOCASE: ignore case distinctions (only for ASCII). FileNODIR: ignore directory part of the file name. FileENC_RAW: compare against unmodified names as it is in the ZIP archive. FileENC_GUESS: (default) guess encoding of the name in the ZIP archive and convert it to UTF-8, if necessary. FileENC_STRICT: follow the ZIP specification and expect CP-437 encoded names in the ZIP archive (except if they are explicitly marked as UTF-8). Convert it to UTF-8 before comparing.

-> 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 (see nameLocate).

-> 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 (see nameLocate).

-> FilePath

Old name.

-> FilePath

New name.

-> Archive () 

Rename file in the archive.

renameFileIx #

Arguments

:: Integer

Position index of a file in the archive.

-> ByteString

New name.

-> [FileFlag]

Name encoding flags. FileENC_GUESS: guess encoding of the name (default). FileENC_UTF_8: interpret name as UTF-8. FileENC_CP437: interpret name as CP-437.

-> 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.

addFileWithFlags #

Arguments

:: [FileFlag]

Can be a combination of FileOVERWRITE and/or one of filename encoding flags: FileENC_GUESS (default), FileENC_UTF_8, FileENC_CP437.

-> ByteString

Name of the file to create.

-> ZipSource

Source where file data is obtained from.

-> Archive Int

Position index of the new file.

addDirectory #

Arguments

:: FilePath

Directory's name in the archive.

-> Archive Int

Position index of the new directory entry.

Add a directory to the archive.

addDirectoryWithFlags #

Arguments

:: [FileFlag]

Can be one of filename encoding flags: 'FileENC_GUESS (default), FileENC_UTF_8, FileENC_CP437.

-> ByteString

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 (see nameLocate).

-> 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).

setFileCompression #

Arguments

:: [FileFlag]

Filename lookup mode (see nameLocate).

-> FilePath

Filename.

-> ZipCompMethod

Compression method. As of libzip 0.11, the following methods are supported: CompDEFAULT, CompSTORE, CompDEFLATE.

-> Archive () 

Set compression method for a file in the archive.

setFileCompressionIx #

Arguments

:: Integer

Position index of a file in the archive.

-> ZipCompMethod

Compression method. As of libzip 0.11, the following methods are supported: CompDEFAULT, CompSTORE, CompDEFLATE.

-> Archive () 

Set compression method for a file in the archive.

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]

Can be a combination of FileUNCHANGED and/or one of FileENC_GUESS (default), FileENC_STRICT (CP-437).

-> 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 (see nameLocate).

-> FilePath

Filename

-> Archive (Maybe String) 

Get comment for a file in the archive.

getFileCommentIx #

Arguments

:: [FileFlag]

Comment lookup flags. FileUNCHANGED: return the original unchanged comment. FileENC_RAW: return the unmodified commment as it is. FileENC_GUESS: (default) guess the encoding of the comment and convert it to UTF-8, if necessary. FileENC_STRICT: follow the ZIP specification for file names and extend it to file comments, expect them to be encoded in CP-437. Convert it to UTF-8.

-> Integer

Position index of the file.

-> Archive (Maybe ByteString) 

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

setFileComment #

Arguments

:: [FileFlag]

Filename lookup mode (see nameLocate).

-> 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.

-> ByteString

New file comment.

-> [FileFlag]

Comment encoding flags. FileENC_GUESS: guess encoding of the comment (default). FileENC_UTF_8: interpret comment as UTF-8. FileENC_CP437: interpret comment as CP-437.

-> Archive () 

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

removeFileComment #

Arguments

:: [FileFlag]

Filename lookup mode (see nameLocate).

-> 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 (see nameLocate).

-> 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.

TruncateFlag

If archive exists, ignore its current content.

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).

FileENC_GUESS

Guess string encoding (default).

FileENC_RAW

Get unmodified string.

FileENC_STRICT

Follow specification strictly.

FileLOCAL

In local header.

FileCENTRAL

In central directory.

FileENC_UTF_8

String is UTF-8 encoded.

FileENC_CP437

String is CP437 encoded.

FileOVERWRITE

When adding files: if file name exists, overwrite.

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.

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.

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.