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 Source

Monadic computation with a zip archive. See withArchive.

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

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

data ZipStat Source

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

Archive operations

withArchive Source

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 Source

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 Source

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

numFiles Source

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 Source

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 Source

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 Source

Arguments

:: [FileFlag]

FileUNCHANGED flag is accepted.

-> Archive [FilePath] 

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

fileSize Source

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 Source

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 Source

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 Source

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 Source

Arguments

:: [FileFlag]

Filename lookup mode (see nameLocate).

-> FilePath

Filename.

-> Archive () 

Delete file from the archive.

deleteFileIx Source

Arguments

:: Integer

Position index of a file in the archive.

-> Archive () 

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

renameFile Source

Arguments

:: [FileFlag]

Filename lookup mode (see nameLocate).

-> FilePath

Old name.

-> FilePath

New name.

-> Archive () 

Rename file in the archive.

renameFileIx Source

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 Source

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 Source

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 Source

Arguments

:: FilePath

Directory's name in the archive.

-> Archive Int

Position index of the new directory entry.

Add a directory to the archive.

addDirectoryWithFlags Source

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 Source

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 Source

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 Source

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 Source

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 Source

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

sourceFile Source

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 Source

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 Source

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 Source

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

getComment Source

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 Source

Arguments

:: String

Comment message.

-> Archive () 

Set zip archive comment.

removeComment :: Archive () Source

Remove zip archive comment.

getFileComment Source

Arguments

:: [FileFlag]

Filename lookup mode (see nameLocate).

-> FilePath

Filename

-> Archive (Maybe String) 

Get comment for a file in the archive.

getFileCommentIx Source

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 Source

Arguments

:: [FileFlag]

Filename lookup mode (see nameLocate).

-> FilePath

Filename.

-> String

New file comment.

-> Archive () 

Set comment for a file in the archive.

setFileCommentIx Source

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 Source

Arguments

:: [FileFlag]

Filename lookup mode (see nameLocate).

-> FilePath

Filename.

-> Archive () 

Remove comment for a file in the archive.

removeFileCommentIx Source

Arguments

:: Integer

Position index of a file in the archive.

-> Archive () 

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

unchangeFile Source

Arguments

:: [FileFlag]

Filename lookup mode (see nameLocate).

-> FilePath

Filename.

-> Archive () 

Undo changes to a file in the archive.

unchangeFileIx Source

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 () Source

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

unchangeAll :: Archive () Source

Undo all changes in a zip archive.

File reading operations

fromFile Source

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 Source

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 Source

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 () Source

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

readContents Source

Arguments

:: Enum a 
=> Entry [a]

Contents of the file.

Read entire file contents.

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

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

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

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

Flags and options

data OpenFlag Source

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.

Instances

data FileFlag Source

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.

Instances

data ZipCompMethod Source

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

data ZipEncryptionMethod Source

Encryption methods.

Constructors

EncryptNONE

Not encrypted.

EncryptTRAD_PKWARE

Traditional PKWARE encryption.

EncryptUNKNOWN

Unknown algorithm.

Instances

Exception handling

data ZipError Source

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

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

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.