-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Operations on zip archives -- -- Operations on zip archives. @package zip @version 0.1.11 -- | Types used by the package. You don't usually need to import this -- module, because Codec.Archive.Zip re-exports everything you may -- need, import that module instead. module Codec.Archive.Zip.Type -- | This data type serves for naming and selection of archive entries. It -- can be created only with the help of the smart constructor -- mkEntrySelector, and it's the only “key” that can be used to -- select files in archive or to name new files. -- -- The abstraction is crucial for ensuring that created archives are -- portable across operating systems, file systems, and different -- platforms. Since on some operating systems, file paths are -- case-insensitive, this selector is also case-insensitive. It makes -- sure that only relative paths are used to name files inside archive, -- as it's recommended in the specification. It also guarantees that -- forward slashes are used when the path is stored inside archive for -- compatibility with Unix-like operating systems (as it is recommended -- in the specification). On the other hand, in can be rendered as -- ordinary relative file path in OS-specific format, when needed. data EntrySelector -- | Create an EntrySelector from Path Rel -- File. To avoid problems with distribution of the archive, -- characters that some operating systems do not expect in paths are not -- allowed. Proper paths should pass these checks: -- -- -- -- This function can throw an EntrySelectorException. mkEntrySelector :: MonadThrow m => Path Rel File -> m EntrySelector -- | Make a relative path from EntrySelector. Every -- EntrySelector produces a single Path Rel -- File that corresponds to it. unEntrySelector :: EntrySelector -> Path Rel File -- | Get an entry name in the from that is suitable for writing to file -- header, given an EntrySelector. getEntryName :: EntrySelector -> Text -- | The exception describing various troubles you can have with -- EntrySelector. data EntrySelectorException -- | Selector cannot be created from this path InvalidEntrySelector :: (Path Rel File) -> EntrySelectorException -- | This record represents all information about archive entry that can be -- stored in a zip archive. It does not mirror local file header or -- central directory file header, but their binary representation can be -- built given this data structure and the actual archive contents. data EntryDescription EntryDescription :: Version -> Version -> CompressionMethod -> UTCTime -> Word32 -> Natural -> Natural -> Natural -> Maybe Text -> Map Word16 ByteString -> EntryDescription -- | Version made by [edVersionMadeBy] :: EntryDescription -> Version -- | Version needed to extract [edVersionNeeded] :: EntryDescription -> Version -- | Compression method [edCompression] :: EntryDescription -> CompressionMethod -- | Last modification date and time [edModTime] :: EntryDescription -> UTCTime -- | CRC32 check sum [edCRC32] :: EntryDescription -> Word32 -- | Size of compressed entry [edCompressedSize] :: EntryDescription -> Natural -- | Size of uncompressed entry [edUncompressedSize] :: EntryDescription -> Natural -- | Absolute offset of local file header [edOffset] :: EntryDescription -> Natural -- | Entry comment [edComment] :: EntryDescription -> Maybe Text -- | All extra fields found [edExtraField] :: EntryDescription -> Map Word16 ByteString -- | Supported compression methods. data CompressionMethod -- | Store file uncompressed Store :: CompressionMethod -- | Deflate Deflate :: CompressionMethod -- | Compressed using BZip2 algorithm BZip2 :: CompressionMethod -- | Information about archive as a whole. data ArchiveDescription ArchiveDescription :: Maybe Text -> Natural -> Natural -> ArchiveDescription -- | Comment of entire archive [adComment] :: ArchiveDescription -> Maybe Text -- | Absolute offset of start of central directory [adCDOffset] :: ArchiveDescription -> Natural -- | Size of central directory record [adCDSize] :: ArchiveDescription -> Natural -- | The bad things that can happen when you use the library. data ZipException -- | Thrown when you try to get contents of non-existing entry EntryDoesNotExist :: (Path Abs File) -> EntrySelector -> ZipException -- | Thrown when archive structure cannot be parsed ParsingFailed :: (Path Abs File) -> String -> ZipException instance GHC.Classes.Ord Codec.Archive.Zip.Type.ZipException instance GHC.Classes.Eq Codec.Archive.Zip.Type.ZipException instance Data.Data.Data Codec.Archive.Zip.Type.ArchiveDescription instance GHC.Classes.Ord Codec.Archive.Zip.Type.ArchiveDescription instance GHC.Classes.Eq Codec.Archive.Zip.Type.ArchiveDescription instance GHC.Read.Read Codec.Archive.Zip.Type.ArchiveDescription instance GHC.Show.Show Codec.Archive.Zip.Type.ArchiveDescription instance GHC.Classes.Eq Codec.Archive.Zip.Type.EntryDescription instance Data.Data.Data Codec.Archive.Zip.Type.CompressionMethod instance GHC.Enum.Bounded Codec.Archive.Zip.Type.CompressionMethod instance GHC.Enum.Enum Codec.Archive.Zip.Type.CompressionMethod instance GHC.Classes.Ord Codec.Archive.Zip.Type.CompressionMethod instance GHC.Classes.Eq Codec.Archive.Zip.Type.CompressionMethod instance GHC.Read.Read Codec.Archive.Zip.Type.CompressionMethod instance GHC.Show.Show Codec.Archive.Zip.Type.CompressionMethod instance GHC.Classes.Ord Codec.Archive.Zip.Type.EntrySelectorException instance GHC.Classes.Eq Codec.Archive.Zip.Type.EntrySelectorException instance GHC.Generics.Generic Codec.Archive.Zip.Type.EntrySelector instance Data.Data.Data Codec.Archive.Zip.Type.EntrySelector instance GHC.Classes.Ord Codec.Archive.Zip.Type.EntrySelector instance GHC.Classes.Eq Codec.Archive.Zip.Type.EntrySelector instance GHC.Show.Show Codec.Archive.Zip.Type.EntrySelector instance GHC.Show.Show Codec.Archive.Zip.Type.EntrySelectorException instance GHC.Exception.Exception Codec.Archive.Zip.Type.EntrySelectorException instance GHC.Show.Show Codec.Archive.Zip.Type.ZipException instance GHC.Exception.Exception Codec.Archive.Zip.Type.ZipException -- | Support for decoding of CP 437 text. module Codec.Archive.Zip.CP437 -- | Decode a ByteString containing CP 437 encoded text. decodeCP437 :: ByteString -> Text -- | The module provides everything you may need to manipulate Zip -- archives. There are three things that should be clarified right away, -- to avoid confusion in the future. -- -- First, we use the EntrySelector type that can be obtained from -- Path Rel File paths. This method may seem awkward -- at first, but it will protect you from the problems with portability -- when your archive is unpacked on a different platform. Using -- well-typed paths is also something you should consider doing in your -- projects anyway. Even if you don't want to use the Path module -- in your project, it's easy to marshal FilePath to Path -- just before using functions from the library. -- -- The second thing, that is rather a consequence of the first, is that -- there is no way to add directories, or to be precise, empty -- directories to your archive. This approach is used in Git, and I -- find it quite sane. -- -- Finally, the third feature of the library is that it does not modify -- archive instantly, because doing so on every manipulation would often -- be inefficient. Instead we maintain a collection of pending actions -- that can be turned into an optimized procedure that efficiently -- modifies archive in one pass. Normally this should be of no concern to -- you, because all actions are performed automatically when you leave -- the realm of ZipArchive monad. If, however, you ever need to -- force an update, the commit function is your friend. There are -- even “undo” functions, by the way. -- --

Examples

-- -- An example of a program that prints a list of archive entries: -- -- 
--   import Codec.Archive.Zip
--   import Path.IO (resolveFile')
--   import System.Environment (getArgs)
--   import qualified Data.Map as M
--   
--   main :: IO ()
--   main = do
--     [fp]    <- getArgs
--     path    <- resolveFile' fp
--     entries <- withArchive path (M.keys <$> getEntries)
--     mapM_ print entries
--
-- -- Create a Zip archive with a “Hello World” file: -- -- 
--   import Codec.Archive.Zip
--   import Path (parseRelFile)
--   import Path.IO (resolveFile')
--   import System.Environment (getArgs)
--   
--   main :: IO ()
--   main = do
--     [fp]    <- getArgs
--     path    <- resolveFile' fp
--     s       <- parseRelFile "hello-world.txt" >>= mkEntrySelector
--     createArchive path (addEntry Store "Hello, World!" s)
--
-- -- Extract contents of a specific file and print them: -- -- 
--   import Codec.Archive.Zip
--   import Path (parseRelFile)
--   import Path.IO (resolveFile')
--   import System.Environment (getArgs)
--   import qualified Data.ByteString.Char8 as B
--   
--   main :: IO ()
--   main = do
--     [fp,f]  <- getArgs
--     path    <- resolveFile' fp
--     s       <- parseRelFile f >>= mkEntrySelector
--     bs      <- withArchive path (getEntry s)
--     B.putStrLn bs
--
module Codec.Archive.Zip -- | This data type serves for naming and selection of archive entries. It -- can be created only with the help of the smart constructor -- mkEntrySelector, and it's the only “key” that can be used to -- select files in archive or to name new files. -- -- The abstraction is crucial for ensuring that created archives are -- portable across operating systems, file systems, and different -- platforms. Since on some operating systems, file paths are -- case-insensitive, this selector is also case-insensitive. It makes -- sure that only relative paths are used to name files inside archive, -- as it's recommended in the specification. It also guarantees that -- forward slashes are used when the path is stored inside archive for -- compatibility with Unix-like operating systems (as it is recommended -- in the specification). On the other hand, in can be rendered as -- ordinary relative file path in OS-specific format, when needed. data EntrySelector -- | Create an EntrySelector from Path Rel -- File. To avoid problems with distribution of the archive, -- characters that some operating systems do not expect in paths are not -- allowed. Proper paths should pass these checks: -- -- -- -- This function can throw an EntrySelectorException. mkEntrySelector :: MonadThrow m => Path Rel File -> m EntrySelector -- | Make a relative path from EntrySelector. Every -- EntrySelector produces a single Path Rel -- File that corresponds to it. unEntrySelector :: EntrySelector -> Path Rel File -- | Get an entry name in the from that is suitable for writing to file -- header, given an EntrySelector. getEntryName :: EntrySelector -> Text -- | The exception describing various troubles you can have with -- EntrySelector. data EntrySelectorException -- | Selector cannot be created from this path InvalidEntrySelector :: (Path Rel File) -> EntrySelectorException -- | This record represents all information about archive entry that can be -- stored in a zip archive. It does not mirror local file header or -- central directory file header, but their binary representation can be -- built given this data structure and the actual archive contents. data EntryDescription EntryDescription :: Version -> Version -> CompressionMethod -> UTCTime -> Word32 -> Natural -> Natural -> Natural -> Maybe Text -> Map Word16 ByteString -> EntryDescription -- | Version made by [edVersionMadeBy] :: EntryDescription -> Version -- | Version needed to extract [edVersionNeeded] :: EntryDescription -> Version -- | Compression method [edCompression] :: EntryDescription -> CompressionMethod -- | Last modification date and time [edModTime] :: EntryDescription -> UTCTime -- | CRC32 check sum [edCRC32] :: EntryDescription -> Word32 -- | Size of compressed entry [edCompressedSize] :: EntryDescription -> Natural -- | Size of uncompressed entry [edUncompressedSize] :: EntryDescription -> Natural -- | Absolute offset of local file header [edOffset] :: EntryDescription -> Natural -- | Entry comment [edComment] :: EntryDescription -> Maybe Text -- | All extra fields found [edExtraField] :: EntryDescription -> Map Word16 ByteString -- | Supported compression methods. data CompressionMethod -- | Store file uncompressed Store :: CompressionMethod -- | Deflate Deflate :: CompressionMethod -- | Compressed using BZip2 algorithm BZip2 :: CompressionMethod -- | Information about archive as a whole. data ArchiveDescription ArchiveDescription :: Maybe Text -> Natural -> Natural -> ArchiveDescription -- | Comment of entire archive [adComment] :: ArchiveDescription -> Maybe Text -- | Absolute offset of start of central directory [adCDOffset] :: ArchiveDescription -> Natural -- | Size of central directory record [adCDSize] :: ArchiveDescription -> Natural -- | The bad things that can happen when you use the library. data ZipException -- | Thrown when you try to get contents of non-existing entry EntryDoesNotExist :: (Path Abs File) -> EntrySelector -> ZipException -- | Thrown when archive structure cannot be parsed ParsingFailed :: (Path Abs File) -> String -> ZipException -- | Monad that provides context necessary for performing operations on zip -- archives. It's intentionally opaque and not a monad transformer to -- limit the actions that can be performed in it to those provided by -- this module and their combinations. data ZipArchive a -- | Create a new archive given its location and an action that describes -- how to create contents of the archive. This will silently overwrite -- the specified file if it already exists. See withArchive if you -- want to work with an existing archive. createArchive :: (MonadIO m, MonadCatch m) => Path b File -> ZipArchive a -> m a -- | Work with an existing archive. See createArchive if you want to -- create a new archive instead. -- -- This operation may fail with: -- -- -- -- Please note that entries with invalid (non-portable) file names may be -- missing in the list of entries. Files that are compressed with -- unsupported compression methods are skipped as well. Also, if several -- entries would collide on some operating systems (such as Windows, -- because of its case-insensitivity), only one of them will be -- available, because EntrySelector is case-insensitive. These are -- the consequences of the design decision to make it impossible to -- create non-portable archives with this library. withArchive :: (MonadIO m, MonadThrow m) => Path b File -> ZipArchive a -> m a -- | Retrieve description of all archive entries. This is an efficient -- operation that can be used for example to list all entries in an -- archive. Do not hesitate to use the function frequently: scanning of -- archive happens only once anyway. -- -- Please note that the returned value only reflects actual contents of -- the archive in file system, non-committed actions do not influence the -- list of entries, see commit for more information. getEntries :: ZipArchive (Map EntrySelector EntryDescription) -- | Check whether the specified entry exists in the archive. This is a -- simple shortcut defined as: -- -- 
--   doesEntryExist s = M.member s <$> getEntries
--
doesEntryExist :: EntrySelector -> ZipArchive Bool -- | Get EntryDescription for specified entry. This is a simple -- shortcut defined as: -- -- 
--   getEntryDesc s = M.lookup s <$> getEntries
--
getEntryDesc :: EntrySelector -> ZipArchive (Maybe EntryDescription) -- | Get contents of a specific archive entry as a strict -- ByteString. It's not recommended to use this on big entries, -- because it will suck out a lot of memory. For big entries, use -- conduits: sourceEntry. -- -- Throws: EntryDoesNotExist. getEntry :: EntrySelector -> ZipArchive ByteString -- | Get an entry source. -- -- Throws: EntryDoesNotExist. getEntrySource :: MonadResource m => EntrySelector -> ZipArchive (Source m ByteString) -- | Stream contents of an archive entry to the given Sink. -- -- Throws: EntryDoesNotExist. sourceEntry :: EntrySelector -> Sink ByteString (ResourceT IO) a -> ZipArchive a -- | Save a specific archive entry as a file in the file system. -- -- Throws: EntryDoesNotExist. saveEntry :: EntrySelector -> Path b File -> ZipArchive () -- | Calculate CRC32 check sum and compare it with the value read from the -- archive. The function returns True when the check sums are the -- same—that is, the data is not corrupted. -- -- Throws: EntryDoesNotExist. checkEntry :: EntrySelector -> ZipArchive Bool -- | Unpack the entire archive into the specified directory. The directory -- will be created if it does not exist. unpackInto :: Path b Dir -> ZipArchive () -- | Get the archive comment. getArchiveComment :: ZipArchive (Maybe Text) -- | Get the archive description record. getArchiveDescription :: ZipArchive ArchiveDescription -- | Add a new entry to the archive given its contents in binary form. addEntry :: CompressionMethod -> ByteString -> EntrySelector -> ZipArchive () -- | Stream data from the specified source to an archive entry. sinkEntry :: CompressionMethod -> Source (ResourceT IO) ByteString -> EntrySelector -> ZipArchive () -- | Load an entry from a given file. loadEntry :: CompressionMethod -> (Path Abs File -> ZipArchive EntrySelector) -> Path b File -> ZipArchive () -- | Copy an entry “as is” from another zip archive. If the entry does not -- exist in that archive, EntryDoesNotExist will be eventually -- thrown. copyEntry :: Path b File -> EntrySelector -> EntrySelector -> ZipArchive () -- | Add an entire directory to the archive. Please note that due to the -- design of the library, empty sub-directories won't be added. -- -- The action can throw the same exceptions as listDirRecur and -- InvalidEntrySelector. packDirRecur :: CompressionMethod -> (Path Abs File -> ZipArchive EntrySelector) -> Path b Dir -> ZipArchive () -- | Rename an entry in the archive. If the entry does not exist, nothing -- will happen. renameEntry :: EntrySelector -> EntrySelector -> ZipArchive () -- | Delete an entry from the archive, if it does not exist, nothing will -- happen. deleteEntry :: EntrySelector -> ZipArchive () -- | Change compression method of an entry, if it does not exist, nothing -- will happen. recompress :: CompressionMethod -> EntrySelector -> ZipArchive () -- | Set an entry comment, if that entry does not exist, nothing will -- happen. Note that if binary representation of the comment is longer -- than 65535 bytes, it will be truncated on writing. setEntryComment :: Text -> EntrySelector -> ZipArchive () -- | Delete an entry's comment, if that entry does not exist, nothing will -- happen. deleteEntryComment :: EntrySelector -> ZipArchive () -- | Set the “last modification” date/time. The specified entry may be -- missing, in that case the action has no effect. setModTime :: UTCTime -> EntrySelector -> ZipArchive () -- | Add an extra field. The specified entry may be missing, in that case -- this action has no effect. addExtraField :: Word16 -> ByteString -> EntrySelector -> ZipArchive () -- | Delete an extra field by its type (tag). The specified entry may be -- missing, in that case this action has no effect. deleteExtraField :: Word16 -> EntrySelector -> ZipArchive () -- | Perform an action on every entry in the archive. forEntries :: (EntrySelector -> ZipArchive ()) -> ZipArchive () -- | Set comment of the entire archive. setArchiveComment :: Text -> ZipArchive () -- | Delete the archive comment if it's present. deleteArchiveComment :: ZipArchive () -- | Undo changes to a specific archive entry. undoEntryChanges :: EntrySelector -> ZipArchive () -- | Undo changes to the archive as a whole (archive's comment). undoArchiveChanges :: ZipArchive () -- | Undo all changes made in this editing session. undoAll :: ZipArchive () -- | Archive contents are not modified instantly, but instead changes are -- collected as “pending actions” that should be committed, in order to -- efficiently modify the archive in one pass. The actions are committed -- automatically when the program leaves the realm of ZipArchive -- monad (i.e. as part of createArchive or withArchive), or -- can be forced explicitly with the help of this function. Once -- committed, changes take place in the file system and cannot be undone. commit :: ZipArchive () instance Control.Monad.Catch.MonadMask Codec.Archive.Zip.ZipArchive instance Control.Monad.Catch.MonadCatch Codec.Archive.Zip.ZipArchive instance Control.Monad.Catch.MonadThrow Codec.Archive.Zip.ZipArchive instance Control.Monad.IO.Class.MonadIO Codec.Archive.Zip.ZipArchive instance GHC.Base.Monad Codec.Archive.Zip.ZipArchive instance GHC.Base.Applicative Codec.Archive.Zip.ZipArchive instance GHC.Base.Functor Codec.Archive.Zip.ZipArchive