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


-- | Extract and create tar files using conduit for streaming
--   
--   Please see README.md. This is just filler to avoid warnings.
@package tar-conduit
@version 0.4.1


-- | Module contains all the types necessary for tarball processing.
module Data.Conduit.Tar.Types
data Header
Header :: !FileOffset -> !FileOffset -> !ShortByteString -> !CMode -> !UserID -> !GroupID -> !FileOffset -> !EpochTime -> !Word8 -> !ShortByteString -> !ShortByteString -> !ShortByteString -> !ShortByteString -> !DeviceID -> !DeviceID -> !ShortByteString -> Header
[headerOffset] :: Header -> !FileOffset
[headerPayloadOffset] :: Header -> !FileOffset
[headerFileNameSuffix] :: Header -> !ShortByteString
[headerFileMode] :: Header -> !CMode
[headerOwnerId] :: Header -> !UserID
[headerGroupId] :: Header -> !GroupID
[headerPayloadSize] :: Header -> !FileOffset
[headerTime] :: Header -> !EpochTime
[headerLinkIndicator] :: Header -> !Word8
[headerLinkName] :: Header -> !ShortByteString
[headerMagicVersion] :: Header -> !ShortByteString
[headerOwnerName] :: Header -> !ShortByteString
[headerGroupName] :: Header -> !ShortByteString
[headerDeviceMajor] :: Header -> !DeviceID
[headerDeviceMinor] :: Header -> !DeviceID
[headerFileNamePrefix] :: Header -> !ShortByteString

-- | Type synonym representing a pax extended header.
type PaxHeader = Map ByteString ByteString

-- | Type representing states (global, next file) given pax extended
--   headers.
data PaxState
PaxState :: PaxHeader -> PaxHeader -> PaxState

-- | The initial state before applying any pax extended headers.
initialPaxState :: PaxState
data TarChunk
ChunkHeader :: Header -> TarChunk
ChunkPayload :: !FileOffset -> !ByteString -> TarChunk
ChunkException :: TarException -> TarChunk

-- | This the the exception type that is used in this module.
--   
--   More constructors are susceptible to be added without bumping the
--   major version of this module.
data TarException
NoMoreHeaders :: TarException
UnexpectedPayload :: !FileOffset -> TarException
IncompleteHeader :: !FileOffset -> TarException
IncompletePayload :: !FileOffset -> !ByteCount -> TarException
ShortTrailer :: !FileOffset -> TarException
BadTrailer :: !FileOffset -> TarException
InvalidHeader :: !FileOffset -> TarException
BadChecksum :: !FileOffset -> TarException
FileTypeError :: !FileOffset -> !Char -> !String -> TarException
UnsupportedType :: !FileType -> TarException
data TarCreateException
FileNameTooLong :: !FileInfo -> TarCreateException
TarCreationError :: !String -> TarCreateException
data FileType
FTNormal :: FileType
FTHardLink :: !ByteString -> FileType
FTSymbolicLink :: !ByteString -> FileType
FTCharacterSpecial :: FileType
FTBlockSpecial :: FileType
FTDirectory :: FileType
FTFifo :: FileType
FTOther :: !Word8 -> FileType
data FileInfo
FileInfo :: !ByteString -> !UserID -> !ByteString -> !GroupID -> !ByteString -> !FileMode -> !FileOffset -> !FileType -> !EpochTime -> FileInfo

-- | File path.
[filePath] :: FileInfo -> !ByteString

-- | Unix user id.
[fileUserId] :: FileInfo -> !UserID

-- | Unix user name.
[fileUserName] :: FileInfo -> !ByteString

-- | Unix group id.
[fileGroupId] :: FileInfo -> !GroupID

-- | Unix group name.
[fileGroupName] :: FileInfo -> !ByteString

-- | Unix file permissions
[fileMode] :: FileInfo -> !FileMode

-- | File size
[fileSize] :: FileInfo -> !FileOffset

-- | File type. <a>FTNormal</a>, <a>FTHardLink</a> (@since 0.3.0),
--   <a>FTSymbolicLink</a> and <a>FTDirectory</a> are the only ones
--   supported for now
[fileType] :: FileInfo -> !FileType

-- | File modification timestamp
[fileModTime] :: FileInfo -> !EpochTime
type FileOffset = COff
type ByteCount = CSize
type UserID = CUid
type GroupID = CGid
type DeviceID = CDev
type EpochTime = CTime
newtype CUid
CUid :: Word32 -> CUid
newtype CGid
CGid :: Word32 -> CGid

-- | Convert <a>FilePath</a> into a UTF-8 encoded <a>ByteString</a>
encodeFilePath :: FilePath -> ByteString

-- | Convert UTF-8 encoded <a>ByteString</a> back into the <a>FilePath</a>.
decodeFilePath :: ByteString -> FilePath

-- | Get the <a>FilePath</a>.
getFileInfoPath :: FileInfo -> FilePath
instance GHC.Classes.Eq Data.Conduit.Tar.Types.FileInfo
instance GHC.Classes.Eq Data.Conduit.Tar.Types.FileType
instance GHC.Internal.Exception.Type.Exception Data.Conduit.Tar.Types.TarCreateException
instance GHC.Internal.Exception.Type.Exception Data.Conduit.Tar.Types.TarException
instance GHC.Internal.Show.Show Data.Conduit.Tar.Types.FileInfo
instance GHC.Internal.Show.Show Data.Conduit.Tar.Types.FileType
instance GHC.Internal.Show.Show Data.Conduit.Tar.Types.Header
instance GHC.Internal.Show.Show Data.Conduit.Tar.Types.TarChunk
instance GHC.Internal.Show.Show Data.Conduit.Tar.Types.TarCreateException
instance GHC.Internal.Show.Show Data.Conduit.Tar.Types.TarException


-- | This module is about stream-processing tar archives. It is currently
--   not very well tested. See the documentation of <a>withEntries</a> for
--   an usage sample.
module Data.Conduit.Tar

-- | Create a tar archive by suppying a stream of <a>Left</a>
--   <a>FileInfo</a>s. Whenever a file type is <a>FTNormal</a>, it must be
--   immediately followed by its content as <a>Right</a> <a>ByteString</a>.
--   The produced <a>ByteString</a> is in the raw tar format and is
--   properly terminated at the end, therefore it can not be extended
--   afterwards. Returned is the total size of the bytestring as a
--   <a>FileOffset</a>.
tar :: forall (m :: Type -> Type). MonadThrow m => ConduitM (Either FileInfo ByteString) ByteString m FileOffset

-- | Just like <a>tar</a>, except gives you the ability to work at a lower
--   <a>Header</a> level, versus more user friendly <a>FileInfo</a>. A
--   deeper understanding of tar format is necessary in order to work
--   directly with <a>Header</a>s.
tarEntries :: forall (m :: Type -> Type). MonadThrow m => ConduitM (Either Header ByteString) ByteString m FileOffset

-- | Just like <a>withFileInfo</a>, but works directly on the stream of
--   bytes. Applies pax header blocks and extended headers. However, only
--   the 'comment', 'gid', 'gname', 'linkpath', 'path', 'size', 'uid' and
--   'uname' pax keywords are supported.
untar :: forall (m :: Type -> Type) o. MonadThrow m => (FileInfo -> ConduitM ByteString o m ()) -> ConduitM ByteString o m ()

-- | Like <a>untar</a> but does not apply pax header blocks and extended
--   headers.
untarRaw :: forall (m :: Type -> Type) o. MonadThrow m => (FileInfo -> ConduitM ByteString o m ()) -> ConduitM ByteString o m ()

-- | Just like <a>untar</a>, except that each <a>FileInfo</a> handling
--   function can produce a finalizing action, all of which will be
--   executed after the whole tarball has been processed in the opposite
--   order. Very useful with <a>restoreFile</a> and <a>restoreFileInto</a>,
--   since they restore direcory modification timestamps only after files
--   have been fully written to disk.
untarWithFinalizers :: forall (m :: Type -> Type) c. (MonadThrow m, MonadIO m) => (FileInfo -> ConduitM ByteString (IO ()) m ()) -> ConduitM ByteString c m ()

-- | Same as <a>untarWithFinalizers</a>, but will also produce a list of
--   any exceptions that might have occured during restoration process.
untarWithExceptions :: forall (m :: Type -> Type) c. (MonadThrow m, MonadIO m) => (FileInfo -> ConduitM ByteString (IO (FileInfo, [SomeException])) m ()) -> ConduitM ByteString c m [(FileInfo, [SomeException])]

-- | Restore files onto the file system. Produces actions that will set the
--   modification time on the directories, which can be executed after the
--   pipeline has finished and all files have been written to disk.
restoreFile :: forall (m :: Type -> Type). MonadResource m => FileInfo -> ConduitM ByteString (IO ()) m ()

-- | Restore all files into a folder. Absolute file paths will be turned
--   into relative to the supplied folder.
restoreFileInto :: forall (m :: Type -> Type). MonadResource m => FilePath -> FileInfo -> ConduitM ByteString (IO ()) m ()

-- | Restore all files into a folder. Absolute file paths will be turned
--   into relative to the supplied folder. Yields a list with exceptions
--   instead of throwing them.
restoreFileIntoLenient :: forall (m :: Type -> Type). MonadResource m => FilePath -> FileInfo -> ConduitM ByteString (IO (FileInfo, [SomeException])) m ()

-- | Restore files onto the file system, much in the same way
--   <a>restoreFile</a> does it, except with ability to ignore restoring
--   problematic files and report errors that occured as a list of
--   exceptions, which will be returned as a list when finilizer executed.
--   If a list is empty, it means, that no errors occured and a file only
--   had a finilizer associated with it.
restoreFileWithErrors :: forall (m :: Type -> Type). MonadResource m => Bool -> FileInfo -> ConduitM ByteString (IO (FileInfo, [SomeException])) m ()

-- | Convert a stream of raw bytes into a stream of <a>TarChunk</a>s, after
--   applying any pax header blocks and extended headers. This stream can
--   further be passed into <a>withFileInfo</a> or <tt>withHeaders</tt>
--   functions. Only the 'comment', 'gid', 'gname', 'linkpath', 'path',
--   'size', 'uid' and 'uname' pax keywords are supported. For a component
--   that produces unprocessed <a>TarChunk</a>s, see <a>untarChunksRaw</a>.
untarChunks :: forall (m :: Type -> Type). Monad m => ConduitM ByteString TarChunk m ()

-- | Convert a stream of raw bytes into a stream of raw <a>TarChunk</a>s.
--   This stream can further be passed into <a>withFileInfo</a> or
--   <tt>withHeaders</tt> functions. For a component that further processes
--   raw <a>TarChunk</a>s to apply pax header blocks and extended headers,
--   see <tt>untarChunk</tt>.
untarChunksRaw :: forall (m :: Type -> Type). Monad m => ConduitM ByteString TarChunk m ()

-- | Applies tar chunks that are pax header blocks and extended headers to
--   the tar chunks that follow. However, only the 'comment', 'gid',
--   'gname', 'linkpath', 'path', 'size', 'uid' and 'uname' pax keywords
--   are supported.
applyPaxChunkHeaders :: forall (m :: Type -> Type). Monad m => ConduitM TarChunk TarChunk (StateT PaxState m) ()

-- | Process a single tar entry. See <a>withEntries</a> for more details.
withEntry :: forall (m :: Type -> Type) o r. MonadThrow m => (Header -> ConduitM ByteString o m r) -> ConduitM TarChunk o m r

-- | This function handles each entry of the tar archive according to the
--   behaviour of the function passed as first argument.
--   
--   Here is a full example function, that reads a compressed tar archive
--   and for each entry that is a simple file, it prints its file path and
--   SHA256 digest. Note that this function can throw exceptions!
--   
--   <pre>
--   import qualified Crypto.Hash.Conduit as CH
--   import qualified Data.Conduit.Tar    as CT
--   
--   import Conduit
--   import Crypto.Hash (Digest, SHA256)
--   import Control.Monad (when)
--   import Data.Conduit.Zlib (ungzip)
--   import Data.ByteString (ByteString)
--   
--   filedigests :: FilePath -&gt; IO ()
--   filedigests fp = runConduitRes (  sourceFileBS fp          -- read the raw file
--                                  .| ungzip                   -- gunzip
--                                  .| CT.untarChunks           -- decode the tar archive
--                                  .| CT.withEntries hashentry -- process each file
--                                  .| printC                   -- print the results
--                                  )
--       where
--           hashentry :: Monad m =&gt; CT.Header -&gt; Conduit ByteString m (FilePath, Digest SHA256)
--           hashentry hdr = when (CT.headerFileType hdr == CT.FTNormal) $ do
--               hash &lt;- CH.sinkHash
--               yield (CT.headerFilePath hdr, hash)
--   </pre>
--   
--   The <tt>hashentry</tt> function handles a single entry, based on its
--   first <a>Header</a> argument. In this example, a <a>Consumer</a> is
--   used to process the whole entry.
--   
--   Note that the benefits of stream processing are easily lost when
--   working with a <a>Consumer</a>. For example, the following
--   implementation would have used an unbounded amount of memory:
--   
--   <pre>
--   hashentry hdr = when (CT.headerFileType hdr == CT.FTNormal) $ do
--       content &lt;- mconcat &lt;$&gt; sinkList
--       yield (CT.headerFilePath hdr, hash content)
--   </pre>
withEntries :: forall (m :: Type -> Type) o. MonadThrow m => (Header -> ConduitM ByteString o m ()) -> ConduitM TarChunk o m ()

-- | Extract a tarball, similarly to <a>withEntries</a>, but instead of
--   dealing directly with tar format, this conduit allows you to work
--   directly on file abstractions <a>FileInfo</a>. For now support is
--   minimal:
--   
--   <ul>
--   <li>Old v7 tar format.</li>
--   <li>ustar: POSIX 1003.1-1988 format</li>
--   <li>and only some portions of GNU format:</li>
--   <li>Larger values for <a>fileUserId</a>, <a>fileGroupId</a>,
--   <a>fileSize</a> and <a>fileModTime</a>.</li>
--   <li><tt>L</tt> type - long file names, but only up to 4096 chars to
--   prevent DoS attack</li>
--   <li>other types are simply discarded</li>
--   </ul>
--   
--   <i>Note</i> - Here is a really good reference for specifics of
--   different tar formats:
--   <a>https://github.com/libarchive/libarchive/wiki/ManPageTar5</a>
withFileInfo :: forall (m :: Type -> Type) o. MonadThrow m => (FileInfo -> ConduitM ByteString o m ()) -> ConduitM TarChunk o m ()

-- | Get Header file type.
headerFileType :: Header -> FileType

-- | Construct a <a>FilePath</a> from <a>headerFileNamePrefix</a> and
--   <a>headerFileNameSuffix</a>.
headerFilePath :: Header -> FilePath

-- | Recursively tar all of the files and directories. There will be no
--   conversion between relative and absolute paths, so just like with GNU
--   <tt>tar</tt> cli tool, it may be necessary to
--   <tt>setCurrentDirectory</tt> in order to get the paths relative. Using
--   <a>filePathConduit</a> directly, while modifying the <a>filePath</a>,
--   would be another approach to handling the file paths.
tarFilePath :: forall (m :: Type -> Type). (MonadThrow m, MonadResource m) => ConduitM FilePath ByteString m FileOffset

-- | Turn a stream of file paths into a stream of <a>FileInfo</a> and file
--   content. All paths will be decended into recursively.
filePathConduit :: forall (m :: Type -> Type). (MonadThrow m, MonadResource m) => ConduitM FilePath (Either FileInfo ByteString) m ()

-- | Uses <a>tarFilePath</a> to create a tarball, that will recursively
--   include the supplied list of all the files and directories
createTarball :: FilePath -> [FilePath] -> IO ()

-- | Take a list of files and paths, recursively tar them and write output
--   into supplied handle.
writeTarball :: Handle -> [FilePath] -> IO ()

-- | Extract a tarball while using <tt>restoreFileInfo</tt> for writing
--   files onto the file system. Restoration process is cross platform and
--   should work concistently both on Windows and Posix systems.
extractTarball :: FilePath -> Maybe FilePath -> IO ()

-- | Same as <a>extractTarball</a>, but ignores possible extraction errors.
--   It can still throw a <a>TarException</a> if the tarball is corrupt or
--   malformed.
extractTarballLenient :: FilePath -> Maybe FilePath -> IO [(FileInfo, [SomeException])]
