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


-- | Support for decoding of CP437 text.
module Codec.Archive.Zip.CP437

-- | Decode a <a>ByteString</a> containing CP 437 encoded text.
decodeCP437 :: ByteString -> Text


-- | Types used by the package. You don't usually need to import this
--   module, because <a>Codec.Archive.Zip</a> 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 help of smart constructor
--   <a>mkEntrySelector</a>, 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 <a>EntrySelector</a> from <tt>Path Rel File</tt>. 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:
--   
--   <ul>
--   <li><a>isValid</a></li>
--   <li><a>isValid</a></li>
--   <li>binary representation of normalized path should be not longer than
--   65535 bytes</li>
--   </ul>
--   
--   This function can throw <a>EntrySelectorException</a> exception.
mkEntrySelector :: MonadThrow m => Path Rel File -> m EntrySelector

-- | Make a relative path from <a>EntrySelector</a>. Every
--   <a>EntrySelector</a> produces single <tt>Path Rel File</tt> that
--   corresponds to it.
unEntrySelector :: EntrySelector -> Path Rel File

-- | Get entry name given <a>EntrySelector</a> in from that is suitable for
--   writing to file header.
getEntryName :: EntrySelector -> Text

-- | Exception describing various troubles you can have with
--   <a>EntrySelector</a>.
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 date structure and 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

-- | 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.Show.Show Codec.Archive.Zip.Type.ArchiveDescription
instance GHC.Classes.Eq Codec.Archive.Zip.Type.ArchiveDescription
instance GHC.Classes.Eq Codec.Archive.Zip.Type.EntryDescription
instance GHC.Show.Show Codec.Archive.Zip.Type.CompressionMethod
instance GHC.Read.Read Codec.Archive.Zip.Type.CompressionMethod
instance GHC.Enum.Enum Codec.Archive.Zip.Type.CompressionMethod
instance GHC.Classes.Eq Codec.Archive.Zip.Type.CompressionMethod
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


-- | The module provides everything you need to manipulate Zip archives.
--   There are three things that should be clarified right away, to avoid
--   confusion in the future.
--   
--   First, we use <a>EntrySelector</a> type that can be obtained from
--   <a>Path</a> <a>Rel</a> <a>File</a> paths. This method may seem awkward
--   at first, but it will protect you from problems with portability when
--   your archive is unpacked on a different platform. Using of well-typed
--   paths is also something you should consider doing in your projects
--   anyway. Even if you don't want to use <a>Path</a> module in your
--   project, it's easy to marshal <a>FilePath</a> to <a>Path</a> 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, <i>empty
--   directories</i> 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 collection of pending actions that
--   can be turned into 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 <a>ZipArchive</a> monad. If, however, you ever need to force
--   update, <a>commit</a> function is your friend. There are even “undo”
--   functions, by the way.
module Codec.Archive.Zip

-- | This data type serves for naming and selection of archive entries. It
--   can be created only with help of smart constructor
--   <a>mkEntrySelector</a>, 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 <a>EntrySelector</a> from <tt>Path Rel File</tt>. 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:
--   
--   <ul>
--   <li><a>isValid</a></li>
--   <li><a>isValid</a></li>
--   <li>binary representation of normalized path should be not longer than
--   65535 bytes</li>
--   </ul>
--   
--   This function can throw <a>EntrySelectorException</a> exception.
mkEntrySelector :: MonadThrow m => Path Rel File -> m EntrySelector

-- | Make a relative path from <a>EntrySelector</a>. Every
--   <a>EntrySelector</a> produces single <tt>Path Rel File</tt> that
--   corresponds to it.
unEntrySelector :: EntrySelector -> Path Rel File

-- | Get entry name given <a>EntrySelector</a> in from that is suitable for
--   writing to file header.
getEntryName :: EntrySelector -> Text

-- | Exception describing various troubles you can have with
--   <a>EntrySelector</a>.
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 date structure and 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

-- | 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
--   archives. It's intentionally opaque and not a monad transformer to
--   limit number of actions that can be performed in it to those provided
--   by this module and their combinations.
data ZipArchive a

-- | Create new archive given its location and action that describes how to
--   create content in the archive. This will silently overwrite specified
--   file if it already exists. See <a>withArchive</a> if you want to work
--   with existing archive.
createArchive :: (MonadIO m, MonadCatch m) => Path b File -> ZipArchive a -> m a

-- | Work with an existing archive. See <a>createArchive</a> if you want to
--   create new archive instead.
--   
--   This operation may fail with:
--   
--   <ul>
--   <li><tt>isAlreadyInUseError</tt> if the file is already open and
--   cannot be reopened;</li>
--   <li><tt>isDoesNotExistError</tt> if the file does not exist;</li>
--   <li><tt>isPermissionError</tt> if the user does not have permission to
--   open the file;</li>
--   <li><a>ParsingFailed</a> when specified archive is something this
--   library cannot parse (this includes multi-disk archives, for
--   example).</li>
--   </ul>
--   
--   Please note that entries with invalid (non-portable) file names may be
--   missing in 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
--   <a>EntrySelector</a> is case-insensitive. These are 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 archive.
--   Do not hesitate to use the function frequently: scanning of archive
--   happens only once anyway.
--   
--   Please note that returned value only reflects actual contents of
--   archive in file system, non-committed actions cannot influence list of
--   entries, see <a>commit</a> for more information.
getEntries :: ZipArchive (Map EntrySelector EntryDescription)

-- | Check whether specified entry exists in the archive. This is a simple
--   shortcut defined as:
--   
--   <pre>
--   doesEntryExist s = M.member s &lt;$&gt; getEntries
--   </pre>
doesEntryExist :: EntrySelector -> ZipArchive Bool

-- | Get <a>EntryDescription</a> for specified entry. This is a simple
--   shortcut defined as:
--   
--   <pre>
--   getEntryDesc s = M.lookup s &lt;$&gt; getEntries
--   </pre>
getEntryDesc :: EntrySelector -> ZipArchive (Maybe EntryDescription)

-- | Get contents of specific archive entry as strict <a>ByteString</a>.
--   It's not recommended to use this on big entries, because it will suck
--   out a lot of memory. For big entries, use conduits:
--   <a>sourceEntry</a>.
--   
--   Throws: <a>EntryDoesNotExist</a>.
getEntry :: EntrySelector -> ZipArchive ByteString

-- | Stream contents of archive entry to specified <a>Sink</a>.
--   
--   Throws: <a>EntryDoesNotExist</a>.
sourceEntry :: EntrySelector -> Sink ByteString (ResourceT IO) a -> ZipArchive a

-- | Save specific archive entry as a file in the file system.
--   
--   Throws: <a>EntryDoesNotExist</a>.
saveEntry :: EntrySelector -> Path b File -> ZipArchive ()

-- | Calculate CRC32 check sum and compare it with value read from archive.
--   The function returns <a>True</a> when the check sums are the same —
--   that is, data is not corrupted.
--   
--   Throws: <a>EntryDoesNotExist</a>.
checkEntry :: EntrySelector -> ZipArchive Bool

-- | Unpack entire archive into specified directory. The directory will be
--   created if it does not exist.
unpackInto :: Path b Dir -> ZipArchive ()

-- | Get archive comment.
getArchiveComment :: ZipArchive (Maybe Text)

-- | Get archive description record.
getArchiveDescription :: ZipArchive ArchiveDescription

-- | Add a new entry to 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 entry from given file.
loadEntry :: CompressionMethod -> (Path Abs File -> ZipArchive EntrySelector) -> Path b File -> ZipArchive ()

-- | Copy entry “as is” from another .ZIP archive. If the entry does not
--   exists in that archive, <a>EntryDoesNotExist</a> will be eventually
--   thrown.
copyEntry :: Path b File -> EntrySelector -> EntrySelector -> ZipArchive ()

-- | Add entire directory to archive. Please note that due to design of the
--   library, empty sub-directories won't be added.
--   
--   The action can throw the same exceptions as <a>listDirRecur</a> and
--   <a>InvalidEntrySelector</a>.
packDirRecur :: CompressionMethod -> (Path Abs File -> ZipArchive EntrySelector) -> Path b Dir -> ZipArchive ()

-- | Rename entry in archive. If the entry does not exist, nothing will
--   happen.
renameEntry :: EntrySelector -> EntrySelector -> ZipArchive ()

-- | Delete entry from 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 entry comment, if that entry does not exist, nothing will happen.
--   Note that if binary representation of comment is longer than 65535
--   bytes, it will be truncated on writing.
setEntryComment :: Text -> EntrySelector -> ZipArchive ()

-- | Delete entry's comment, if that entry does not exist, nothing will
--   happen.
deleteEntryComment :: EntrySelector -> ZipArchive ()

-- | Set “last modification” date/time. Specified entry may be missing, in
--   that case this action has no effect.
setModTime :: UTCTime -> EntrySelector -> ZipArchive ()

-- | Add an extra field. 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). Specified entry may be
--   missing, in that case this action has no effect.
deleteExtraField :: Word16 -> EntrySelector -> ZipArchive ()

-- | Perform an action on every entry in archive.
forEntries :: (EntrySelector -> ZipArchive ()) -> ZipArchive ()

-- | Set comment of entire archive.
setArchiveComment :: Text -> ZipArchive ()

-- | Delete archive comment if it's present.
deleteArchiveComment :: ZipArchive ()

-- | Undo changes to specific archive entry.
undoEntryChanges :: EntrySelector -> ZipArchive ()

-- | Undo changes to 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 archive in one pass. The actions are committed
--   automatically when program leaves the realm of <a>ZipArchive</a> monad
--   (i.e. as part of <a>createArchive</a> or <a>withArchive</a>), or can
--   be forced explicitly with 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