-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Operations on zip archives
--   
--   Operations on zip archives.
@package zip
@version 1.2.0


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

-- | Decode a <a>ByteString</a> 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 <a>EntrySelector</a> type that can be obtained from
--   relative <a>FilePath</a>s (paths to directories are not allowed). 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.
--   
--   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 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 <a>ZipArchive</a> monad. If, however, you ever need to
--   force an update, the <a>commit</a> function is your friend. There are
--   even “undo” functions, by the way.
--   
--   <h3>Examples</h3>
--   
--   An example of a program that prints a list of archive entries:
--   
--   <pre>
--   import Codec.Archive.Zip
--   import System.Environment (getArgs)
--   import qualified Data.Map as M
--   
--   main :: IO ()
--   main = do
--     [path]  &lt;- getArgs
--     entries &lt;- withArchive path (M.keys &lt;$&gt; getEntries)
--     mapM_ print entries
--   </pre>
--   
--   Create a Zip archive with a “Hello World” file:
--   
--   <pre>
--   import Codec.Archive.Zip
--   import System.Environment (getArgs)
--   
--   main :: IO ()
--   main = do
--     [path] &lt;- getArgs
--     s      &lt;- mkEntrySelector "hello-world.txt"
--     createArchive path (addEntry Store "Hello, World!" s)
--   </pre>
--   
--   Extract contents of a specific file and print them:
--   
--   <pre>
--   import Codec.Archive.Zip
--   import System.Environment (getArgs)
--   import qualified Data.ByteString.Char8 as B
--   
--   main :: IO ()
--   main = do
--     [path,f] &lt;- getArgs
--     s        &lt;- mkEntrySelector f
--     bs       &lt;- withArchive path (getEntry s)
--     B.putStrLn bs
--   </pre>
module Codec.Archive.Zip

-- | This data type serves for naming and selection of archive entries. It
--   can be created only with help of the smart constructor
--   <a>mkEntrySelector</a>, and it's the only “key” that can be used to
--   refer to files in archive or to name new archive entries.
--   
--   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 recommended in the
--   specification). On the other hand, in can be rendered as an ordinary
--   relative file path in OS-specific format when needed.
data EntrySelector

-- | Create an <a>EntrySelector</a> from a <a>FilePath</a>. To avoid
--   problems with distribution of the archive, characters that some
--   operating systems do not expect in paths are not allowed.
--   
--   Argument to <a>mkEntrySelector</a> should pass these checks:
--   
--   <ul>
--   <li><a>isValid</a></li>
--   <li><a>isValid</a></li>
--   <li>it is a relative path without slash at the end</li>
--   <li>binary representations of normalized path should be not longer
--   than 65535 bytes</li>
--   </ul>
--   
--   This function can throw an <a>EntrySelectorException</a>.
mkEntrySelector :: MonadThrow m => FilePath -> m EntrySelector

-- | Restore a relative path from <a>EntrySelector</a>. Every
--   <a>EntrySelector</a> corresponds to a single <a>FilePath</a>.
unEntrySelector :: EntrySelector -> FilePath

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

-- | The exception represents various troubles you can have with
--   <a>EntrySelector</a>.
newtype EntrySelectorException

-- | <a>EntrySelector</a> cannot be created from this path
InvalidEntrySelector :: FilePath -> 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 representations 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 -> Word32 -> 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

-- | External file attributes
[edExternalFileAttrs] :: EntryDescription -> Word32

-- | 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 :: FilePath -> EntrySelector -> ZipException

-- | Thrown when archive structure cannot be parsed
ParsingFailed :: FilePath -> 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

-- | Internal state record used by the <a>ZipArchive</a> monad. This is
--   only exported for use with <a>MonadBaseControl</a> methods, you can't
--   look inside.
data ZipState

-- | 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 <a>withArchive</a> if you
--   want to work with an existing archive.
createArchive :: MonadIO m => FilePath -> ZipArchive a -> m a

-- | Work with an existing archive. See <a>createArchive</a> if you want to
--   create a 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 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 <a>EntrySelector</a> 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 => FilePath -> 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 <a>commit</a> for more information.
getEntries :: ZipArchive (Map EntrySelector EntryDescription)

-- | Check whether the 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 a specific archive entry as a 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

-- | Get an entry source.
--   
--   Throws: <a>EntryDoesNotExist</a>.
getEntrySource :: (PrimMonad m, MonadThrow m, MonadResource m) => EntrySelector -> ZipArchive (ConduitT () ByteString m ())

-- | Stream contents of an archive entry to the given <tt>Sink</tt>.
--   
--   Throws: <a>EntryDoesNotExist</a>.
sourceEntry :: EntrySelector -> ConduitT ByteString Void (ResourceT IO) a -> ZipArchive a

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

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

-- | Unpack the entire archive into the specified directory. The directory
--   will be created if it does not exist.
unpackInto :: FilePath -> 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 -> ConduitT () ByteString (ResourceT IO) () -> EntrySelector -> ZipArchive ()

-- | Load an entry from a given file.
loadEntry :: CompressionMethod -> EntrySelector -> FilePath -> ZipArchive ()

-- | Copy an entry “as is” from another zip archive. If the entry does not
--   exist in that archive, <a>EntryDoesNotExist</a> will be eventually
--   thrown.
copyEntry :: FilePath -> 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 <a>InvalidEntrySelector</a>.
packDirRecur :: CompressionMethod -> (FilePath -> ZipArchive EntrySelector) -> FilePath -> 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 ()

-- | Set external file attributes.
setExternalFileAttrs :: Word32 -> 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 <a>ZipArchive</a>
--   monad (i.e. as part of <a>createArchive</a> or <a>withArchive</a>), 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
instance Control.Monad.Base.MonadBase GHC.Types.IO Codec.Archive.Zip.ZipArchive
instance Control.Monad.Trans.Control.MonadBaseControl GHC.Types.IO Codec.Archive.Zip.ZipArchive