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

Safe Haskell | None

Codec.Archive.LibZip

Contents

- Types
- Archive operations
- File reading operations
- Flags and options
- Exception handling
- Re-exports

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 `lift`ing respectingly.

Note: LibZip does not handle text encodings. Even if its API accepts `String`s (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

- type Archive a = StateT Zip IO a
- type Entry a = StateT (ZipFile, Integer, [FileFlag]) (StateT Zip IO) a
- data ZipStat = ZipStat {
  - 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
  }
- withArchive :: [OpenFlag] -> FilePath -> Archive a -> IO a
- getZip :: Archive Zip
- numFiles :: [FileFlag] -> Archive Integer
- fileName :: [FileFlag] -> Integer -> Archive FilePath
- nameLocate :: [FileFlag] -> FilePath -> Archive (Maybe Integer)
- fileNames :: [FileFlag] -> Archive [FilePath]
- fileSize :: [FileFlag] -> FilePath -> Archive Integer
- fileSizeIx :: [FileFlag] -> Integer -> Archive Integer
- fileStat :: [FileFlag] -> FilePath -> Archive ZipStat
- fileStatIx :: [FileFlag] -> Integer -> Archive ZipStat
- deleteFile :: [FileFlag] -> FilePath -> Archive ()
- deleteFileIx :: Integer -> Archive ()
- renameFile :: [FileFlag] -> FilePath -> FilePath -> Archive ()
- renameFileIx :: Integer -> FilePath -> Archive ()
- addFile :: FilePath -> ZipSource -> Archive Int
- addDirectory :: FilePath -> Archive Int
- replaceFile :: [FileFlag] -> FilePath -> ZipSource -> Archive ()
- replaceFileIx :: Integer -> ZipSource -> Archive ()
- sourceBuffer :: Enum a => [a] -> Archive ZipSource
- sourceFile :: FilePath -> Integer -> Integer -> Archive ZipSource
- sourceZip :: [FileFlag] -> Zip -> Integer -> Integer -> Integer -> Archive ZipSource
- data PureSource a st szt = PureSource {
  - srcState :: st
  - srcSize :: szt
  - srcMTime :: Maybe UTCTime
  - readSrc :: szt -> st -> Maybe (szt, [a], st)
  }
- sourcePure :: (Enum a, Storable a, Storable st, Integral szt) => PureSource a st szt -> Archive ZipSource
- getComment :: [FileFlag] -> Archive (Maybe String)
- setComment :: String -> Archive ()
- removeComment :: Archive ()
- getFileComment :: [FileFlag] -> FilePath -> Archive (Maybe String)
- getFileCommentIx :: [FileFlag] -> Integer -> Archive (Maybe String)
- setFileComment :: [FileFlag] -> FilePath -> String -> Archive ()
- setFileCommentIx :: Integer -> String -> Archive ()
- removeFileComment :: [FileFlag] -> FilePath -> Archive ()
- removeFileCommentIx :: Integer -> Archive ()
- unchangeFile :: [FileFlag] -> FilePath -> Archive ()
- unchangeFileIx :: Integer -> Archive ()
- unchangeArchive :: Archive ()
- unchangeAll :: Archive ()
- fromFile :: [FileFlag] -> FilePath -> Entry a -> Archive a
- fromFileIx :: [FileFlag] -> Integer -> Entry a -> Archive a
- readBytes :: Enum a => Integer -> Entry [a]
- skipBytes :: Integer -> Entry ()
- readContents :: Enum a => Entry [a]
- fileContents :: Enum a => [FileFlag] -> FilePath -> Archive [a]
- fileContentsIx :: Enum a => [FileFlag] -> Integer -> Archive [a]
- data OpenFlag
  - = CreateFlag
  - | ExclFlag
  - | CheckConsFlag
- data FileFlag
  - = FileNOCASE
  - | FileNODIR
  - | FileCOMPRESSED
  - | FileUNCHANGED
  - | FileRECOMPRESS
  - | FileENCRYPTED
- data ZipCompMethod
  - = CompDEFAULT
  - | CompSTORE
  - | CompSHRINK
  - | CompREDUCE_1
  - | CompREDUCE_2
  - | CompREDUCE_3
  - | CompREDUCE_4
  - | CompIMPLODE
  - | CompDEFLATE
  - | CompDEFLATE64
  - | CompPKWARE_IMPLODE
  - | CompBZIP2
  - | CompLZMA
  - | CompTERSE
  - | CompLZ77
  - | CompWAVPACK
  - | CompPPMD
- data ZipEncryptionMethod
  - = EncryptNONE
  - | EncryptTRAD_PKWARE
  - | EncryptUNKNOWN
- data ZipError
  - = ErrOK
  - | ErrMULTIDISK
  - | ErrRENAME
  - | ErrCLOSE
  - | ErrSEEK
  - | ErrREAD
  - | ErrWRITE
  - | ErrCRC
  - | ErrZIPCLOSED
  - | ErrNOENT
  - | ErrEXISTS
  - | ErrOPEN
  - | ErrTMPOPEN
  - | ErrZLIB
  - | ErrMEMORY
  - | ErrCHANGED
  - | ErrCOMPNOTSUPP
  - | ErrEOF
  - | ErrINVAL
  - | ErrNOZIP
  - | ErrINTERNAL
  - | ErrINCONS
  - | ErrREMOVE
  - | ErrDELETED
  - | ErrENCRNOTSUPP
  - | ErrRDONLY
  - | ErrNOPASSWD
  - | ErrWRONGPASSWD
- catchZipError :: IO a -> (ZipError -> IO a) -> IO a
- lift :: MonadTrans t => forall m a. Monad m => m a -> t m a

# Types

type Archive a = StateT Zip IO aSource

Monadic computation with a zip archive. See `withArchive`.

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

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

Eq ZipStat |
Show ZipStat |

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

getZip :: Archive Zip Source

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

numFiles :: [FileFlag] -> Archive Integer Source

Get the number of entries in the archive.

fileName Source

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 Source

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 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.
-> 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.
-> FilePath | Old name.
-> FilePath | New name.
-> Archive () |

Rename file in the archive.

renameFileIx Source

Arguments

:: Integer | Position index of a file in the archive.
-> FilePath | New name.
-> 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.

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.

replaceFile Source

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

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] | `FileUNCHANGED` can be used.
-> 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.
-> FilePath | Filename
-> Archive (Maybe String) |

Get comment for a file in the archive.

getFileCommentIx Source

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 Source

Arguments

:: [FileFlag] | Name lookup mode.
-> 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.
-> String | New file comment.
-> Archive () |

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

removeFileComment Source

Arguments

:: [FileFlag] | Filename lookup mode.
-> 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.
-> 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.

Instances

Enum OpenFlag |
Eq OpenFlag |
Show OpenFlag |

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

Instances

Enum FileFlag |
Eq FileFlag |
Show FileFlag |

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

Enum ZipCompMethod |
Eq ZipCompMethod |
Show ZipCompMethod |

data ZipEncryptionMethod Source

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

Enum ZipError |
Eq ZipError |
Show ZipError |
Typeable ZipError |
Exception ZipError |

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

Wrapper to catch library errors.

# Re-exports

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