From b68465494bdc75fc6dec1803e04b3205092faaca Mon Sep 17 00:00:00 2001 From: Bodigrim Date: Wed, 3 Jan 2024 20:58:44 +0000 Subject: [PATCH] More documentation fixes --- Codec/Archive/Tar.hs | 23 +++++++------ Codec/Archive/Tar/Check/Internal.hs | 18 ++++++----- Codec/Archive/Tar/Index.hs | 2 +- Codec/Archive/Tar/Index/IntTrie.hs | 1 + Codec/Archive/Tar/Index/Internal.hs | 13 ++++---- Codec/Archive/Tar/Index/StringTable.hs | 1 + Codec/Archive/Tar/LongNames.hs | 1 + Codec/Archive/Tar/Pack.hs | 18 +++++------ Codec/Archive/Tar/PackAscii.hs | 1 + Codec/Archive/Tar/Read.hs | 1 + Codec/Archive/Tar/Types.hs | 45 ++++++++++++++++---------- Codec/Archive/Tar/Unpack.hs | 1 + Codec/Archive/Tar/Write.hs | 1 + 13 files changed, 72 insertions(+), 54 deletions(-) diff --git a/Codec/Archive/Tar.hs b/Codec/Archive/Tar.hs index 38ab3d4..4e5448c 100644 --- a/Codec/Archive/Tar.hs +++ b/Codec/Archive/Tar.hs @@ -85,7 +85,8 @@ module Codec.Archive.Tar ( -- vulnerabilities have been common in packages handling tar archives. -- -- The 'extract' and 'unpack' functions check for bad file names. See the - -- 'checkSecurity' function for more details. If you need to do any custom + -- 'Codec.Archive.Tar.Check.checkSecurity' function for more details. + -- If you need to do any custom -- unpacking then you should use this. -- ** Tarbombs @@ -125,7 +126,7 @@ module Codec.Archive.Tar ( -- * Types -- ** Tar entry type -- | This module provides only very simple and limited read-only access to - -- the 'Entry' type. If you need access to the details or if you need to + -- the 'GenEntry' type. If you need access to the details or if you need to -- construct your own entries then also import "Codec.Archive.Tar.Entry". GenEntry, Entry, @@ -163,17 +164,15 @@ module Codec.Archive.Tar ( FormatError(..), ) where -import Codec.Archive.Tar.LongNames -import Codec.Archive.Tar.Types - -import Codec.Archive.Tar.Read -import Codec.Archive.Tar.Write - -import Codec.Archive.Tar.Pack -import Codec.Archive.Tar.Unpack -import Codec.Archive.Tar.Index (hSeekEndEntryOffset) - import Codec.Archive.Tar.Check +import Codec.Archive.Tar.Entry +import Codec.Archive.Tar.Index (hSeekEndEntryOffset) +import Codec.Archive.Tar.LongNames (decodeLongNames, encodeLongNames, DecodeLongNamesError(..)) +import Codec.Archive.Tar.Pack (pack, packAndCheck) +import Codec.Archive.Tar.Read (read, FormatError(..)) +import Codec.Archive.Tar.Types (unfoldEntries, foldlEntries, foldEntries, mapEntriesNoFail, mapEntries, Entries, GenEntries(..)) +import Codec.Archive.Tar.Unpack (unpack, unpackAndCheck) +import Codec.Archive.Tar.Write (write) import Control.Applicative ((<|>)) import Control.Exception (Exception, throw, catch, SomeException(..)) diff --git a/Codec/Archive/Tar/Check/Internal.hs b/Codec/Archive/Tar/Check/Internal.hs index 395f7cb..b603846 100644 --- a/Codec/Archive/Tar/Check/Internal.hs +++ b/Codec/Archive/Tar/Check/Internal.hs @@ -1,10 +1,10 @@ {-# LANGUAGE BangPatterns #-} {-# LANGUAGE DeriveDataTypeable #-} {-# LANGUAGE ViewPatterns #-} -{-# LANGUAGE TypeApplications #-} {-# LANGUAGE RankNTypes #-} {-# LANGUAGE ScopedTypeVariables #-} {-# OPTIONS_GHC -Wno-orphans #-} +{-# OPTIONS_HADDOCK hide #-} ----------------------------------------------------------------------------- -- | -- Module : Codec.Archive.Tar.Check.Internal @@ -70,9 +70,10 @@ import qualified System.FilePath.Posix as FilePath.Posix -- link target. A failure in any entry terminates the sequence of entries with -- an error. -- --- Whenever possible, consider fusing 'checkSecurity' with packing / unpacking by using +-- Whenever possible, consider fusing 'Codec.Archive.Tar.Check.checkSecurity' +-- with packing / unpacking by using -- 'Codec.Archive.Tar.packAndCheck' / 'Codec.Archive.Tar.unpackAndCheck' --- with 'checkEntrySecurity'. +-- with 'Codec.Archive.Tar.Check.checkEntrySecurity'. -- Not only it is faster, but also alleviates issues with lazy I/O -- such as exhaustion of file handlers. checkSecurity @@ -80,7 +81,7 @@ checkSecurity -> GenEntries FilePath FilePath (Either (Either e DecodeLongNamesError) FileNameError) checkSecurity = checkEntries checkEntrySecurity . decodeLongNames --- | Worker of 'checkSecurity'. +-- | Worker of 'Codec.Archive.Tar.Check.checkSecurity'. -- -- @since 0.6.0.0 checkEntrySecurity :: GenEntry FilePath FilePath -> Maybe FileNameError @@ -156,12 +157,13 @@ showFileNameError mb_plat err = case err of -- Given the expected subdirectory, this function checks all entries are within -- that subdirectroy. -- --- Note: This check must be used in conjunction with 'checkSecurity' --- (or 'checkPortability'). +-- Note: This check must be used in conjunction with 'Codec.Archive.Tar.Check.checkSecurity' +-- (or 'Codec.Archive.Tar.Check.checkPortability'). -- --- Whenever possible, consider fusing 'checkTarbomb' with packing / unpacking by using +-- Whenever possible, consider fusing 'Codec.Archive.Tar.Check.checkTarbomb' +-- with packing / unpacking by using -- 'Codec.Archive.Tar.packAndCheck' / 'Codec.Archive.Tar.unpackAndCheck' --- with 'checkEntryTarbomb'. +-- with 'Codec.Archive.Tar.Check.checkEntryTarbomb'. -- Not only it is faster, but also alleviates issues with lazy I/O -- such as exhaustion of file handlers. checkTarbomb diff --git a/Codec/Archive/Tar/Index.hs b/Codec/Archive/Tar/Index.hs index 433aa6c..af92794 100644 --- a/Codec/Archive/Tar/Index.hs +++ b/Codec/Archive/Tar/Index.hs @@ -26,7 +26,7 @@ module Codec.Archive.Tar.Index ( -- 'lookup' paths in the @tar@ file, and then use 'hReadEntry' to -- seek to the right part of the file and read the entry. -- - -- An index cannot be used to lookup 'Directory' entries in a tar file; + -- An index cannot be used to lookup 'Codec.Archive.Tar.Directory' entries in a tar file; -- instead, you will get 'TarDir' entry listing all the entries in the -- directory. diff --git a/Codec/Archive/Tar/Index/IntTrie.hs b/Codec/Archive/Tar/Index/IntTrie.hs index 1dad238..1d8d162 100644 --- a/Codec/Archive/Tar/Index/IntTrie.hs +++ b/Codec/Archive/Tar/Index/IntTrie.hs @@ -1,5 +1,6 @@ {-# LANGUAGE CPP, BangPatterns, PatternGuards #-} {-# LANGUAGE DeriveDataTypeable, ScopedTypeVariables #-} +{-# OPTIONS_HADDOCK hide #-} module Codec.Archive.Tar.Index.IntTrie ( diff --git a/Codec/Archive/Tar/Index/Internal.hs b/Codec/Archive/Tar/Index/Internal.hs index ba8714b..b81e9f9 100644 --- a/Codec/Archive/Tar/Index/Internal.hs +++ b/Codec/Archive/Tar/Index/Internal.hs @@ -1,5 +1,6 @@ {-# LANGUAGE CPP, BangPatterns, PatternGuards #-} {-# LANGUAGE GeneralizedNewtypeDeriving, DeriveDataTypeable #-} +{-# OPTIONS_HADDOCK hide #-} ----------------------------------------------------------------------------- -- | @@ -213,14 +214,14 @@ data IndexBuilder deriving (Eq, Show) instance NFData IndexBuilder where - rnf (IndexBuilder _ _ _) = () -- fully strict by construction + rnf IndexBuilder{} = () -- fully strict by construction -- | The initial empty 'IndexBuilder'. -- empty :: IndexBuilder empty = IndexBuilder StringTable.empty IntTrie.empty 0 --- | Add the next 'Entry' into the 'IndexBuilder'. +-- | Add the next t'Entry' into the 'IndexBuilder'. -- addNextEntry :: Entry -> IndexBuilder -> IndexBuilder addNextEntry entry (IndexBuilder stbl itrie nextOffset) = @@ -238,7 +239,7 @@ skipNextEntry :: Entry -> IndexBuilder -> IndexBuilder skipNextEntry entry (IndexBuilder stbl itrie nextOffset) = IndexBuilder stbl itrie (nextEntryOffset entry nextOffset) --- | Finish accumulating 'Entry' information and build the compact 'TarIndex' +-- | Finish accumulating t'Entry' information and build the compact 'TarIndex' -- lookup structure. -- finalise :: IndexBuilder -> TarIndex @@ -321,7 +322,7 @@ unfinalise (TarIndex pathTable pathTrie finalOffset) = -- I/O operations -- --- | Reads an entire 'Entry' at the given 'TarEntryOffset' in the tar file. +-- | Reads an entire t'Entry' at the given 'TarEntryOffset' in the tar file. -- The 'Handle' must be open for reading and be seekable. -- -- This reads the whole entry into memory strictly, not incrementally. For more @@ -341,7 +342,7 @@ hReadEntry hnd off = do } _ -> return entry --- | Read the header for a 'Entry' at the given 'TarEntryOffset' in the tar +-- | Read the header for a t'Entry' at the given 'TarEntryOffset' in the tar -- file. The 'entryContent' will contain the correct metadata but an empty file -- content. The 'Handle' must be open for reading and be seekable. -- @@ -409,7 +410,7 @@ hSeekEntryContentOffset hnd blockOff = -- -- After this action, the 'Handle' position is not in any useful place. If -- you want to skip to the next entry, take the 'TarEntryOffset' returned and --- use 'hReadEntryHeaderOrEof' again. Or if having inspected the 'Entry' +-- use 'hReadEntryHeaderOrEof' again. Or if having inspected the t'Entry' -- header you want to read the entry content (if it has one) then use -- 'hSeekEntryContentOffset' on the original input 'TarEntryOffset'. -- diff --git a/Codec/Archive/Tar/Index/StringTable.hs b/Codec/Archive/Tar/Index/StringTable.hs index 75f93cb..5ef3a58 100644 --- a/Codec/Archive/Tar/Index/StringTable.hs +++ b/Codec/Archive/Tar/Index/StringTable.hs @@ -1,5 +1,6 @@ {-# LANGUAGE CPP, BangPatterns, PatternGuards, DeriveDataTypeable #-} {-# OPTIONS_GHC -Wno-incomplete-uni-patterns #-} +{-# OPTIONS_HADDOCK hide #-} module Codec.Archive.Tar.Index.StringTable ( diff --git a/Codec/Archive/Tar/LongNames.hs b/Codec/Archive/Tar/LongNames.hs index 1165eb6..e349990 100644 --- a/Codec/Archive/Tar/LongNames.hs +++ b/Codec/Archive/Tar/LongNames.hs @@ -1,5 +1,6 @@ {-# LANGUAGE LambdaCase #-} {-# LANGUAGE PackageImports #-} +{-# OPTIONS_HADDOCK hide #-} module Codec.Archive.Tar.LongNames ( encodeLongNames diff --git a/Codec/Archive/Tar/Pack.hs b/Codec/Archive/Tar/Pack.hs index 3bf8860..3ee08d5 100644 --- a/Codec/Archive/Tar/Pack.hs +++ b/Codec/Archive/Tar/Pack.hs @@ -3,6 +3,7 @@ {-# LANGUAGE LambdaCase #-} {-# LANGUAGE RankNTypes #-} {-# LANGUAGE ScopedTypeVariables #-} +{-# OPTIONS_HADDOCK hide #-} ----------------------------------------------------------------------------- -- | -- Module : Codec.Archive.Tar @@ -59,9 +60,6 @@ import Codec.Archive.Tar.Check.Internal (checkEntrySecurity) -- entries. Hard links are treated like ordinary files. Special files like -- FIFOs (named pipes), sockets or device files will cause problems. -- --- An exception will be thrown for any file names that are too long to --- represent as a 'TarPath'. --- -- * This function returns results lazily. Subdirectories are scanned -- and files are read one by one as the list of entries is consumed. -- Do not change their contents before the output of 'pack' was consumed in full. @@ -75,7 +73,7 @@ pack = packAndCheck (const Nothing) -- | Like 'pack', but allows to specify additional sanity/security -- checks on the input filenames. This is useful if you know which -- check will be used on client side --- in 'Codec.Tar.Check.unpack' / 'Codec.Tar.Check.unpackAndCheck'. +-- in 'Codec.Archive.Tar.unpack' / 'Codec.Archive.Tar.unpackAndCheck'. -- -- @since 0.6.0.0 packAndCheck @@ -128,7 +126,7 @@ interleave = unsafeInterleaveIO . go xs' <- interleave xs return (x':xs') --- | Construct a tar 'Entry' based on a local file. +-- | Construct a tar entry based on a local file. -- -- This sets the entry size, the data contained in the file and the file's -- modification time. If the file is executable then that information is also @@ -138,7 +136,7 @@ interleave = unsafeInterleaveIO . go -- packFileEntry :: FilePath -- ^ Full path to find the file on the local disk - -> tarPath -- ^ Path to use for the tar 'Entry' in the archive + -> tarPath -- ^ Path to use for the tar 'GenEntry' in the archive -> IO (GenEntry tarPath linkTarget) packFileEntry filepath tarpath = do mtime <- getModTime filepath @@ -171,14 +169,14 @@ packFileEntry filepath tarpath = do , entryTime = mtime } --- | Construct a tar 'Entry' based on a local directory (but not its contents). +-- | Construct a tar entry based on a local directory (but not its contents). -- -- The only attribute of the directory that is used is its modification time. -- Directory ownership and detailed permissions are not preserved. -- packDirectoryEntry :: FilePath -- ^ Full path to find the file on the local disk - -> tarPath -- ^ Path to use for the tar 'Entry' in the archive + -> tarPath -- ^ Path to use for the tar 'GenEntry' in the archive -> IO (GenEntry tarPath linkTarget) packDirectoryEntry filepath tarpath = do mtime <- getModTime filepath @@ -186,14 +184,14 @@ packDirectoryEntry filepath tarpath = do entryTime = mtime } --- | Construct a tar 'Entry' based on a local symlink. +-- | Construct a tar entry based on a local symlink. -- -- This automatically checks symlink safety via 'checkEntrySecurity'. -- -- @since 0.6.0.0 packSymlinkEntry :: FilePath -- ^ Full path to find the file on the local disk - -> tarPath -- ^ Path to use for the tar 'Entry' in the archive + -> tarPath -- ^ Path to use for the tar 'GenEntry' in the archive -> IO (GenEntry tarPath FilePath) packSymlinkEntry filepath tarpath = do linkTarget <- getSymbolicLinkTarget filepath diff --git a/Codec/Archive/Tar/PackAscii.hs b/Codec/Archive/Tar/PackAscii.hs index 506d646..3538a56 100644 --- a/Codec/Archive/Tar/PackAscii.hs +++ b/Codec/Archive/Tar/PackAscii.hs @@ -1,4 +1,5 @@ {-# LANGUAGE PackageImports #-} +{-# OPTIONS_HADDOCK hide #-} module Codec.Archive.Tar.PackAscii ( toPosixString diff --git a/Codec/Archive/Tar/Read.hs b/Codec/Archive/Tar/Read.hs index 55b2e09..8a11365 100644 --- a/Codec/Archive/Tar/Read.hs +++ b/Codec/Archive/Tar/Read.hs @@ -1,5 +1,6 @@ {-# LANGUAGE BangPatterns #-} {-# LANGUAGE PackageImports #-} +{-# OPTIONS_HADDOCK hide #-} ----------------------------------------------------------------------------- -- | -- Module : Codec.Archive.Tar.Read diff --git a/Codec/Archive/Tar/Types.hs b/Codec/Archive/Tar/Types.hs index 59bceac..02810a9 100644 --- a/Codec/Archive/Tar/Types.hs +++ b/Codec/Archive/Tar/Types.hs @@ -5,6 +5,7 @@ {-# LANGUAGE QuasiQuotes #-} {-# LANGUAGE RankNTypes #-} {-# LANGUAGE ScopedTypeVariables #-} +{-# OPTIONS_HADDOCK hide #-} ----------------------------------------------------------------------------- -- | @@ -100,17 +101,27 @@ import qualified "os-string" System.OsString.Posix as PS import Codec.Archive.Tar.PackAscii +-- | File size in bytes. type FileSize = Int64 --- | The number of seconds since the UNIX epoch + +-- | The number of seconds since the UNIX epoch. type EpochTime = Int64 + +-- | Major device number. type DevMajor = Int + +-- | Minor device number. type DevMinor = Int + +-- | User-defined tar format expansion. type TypeCode = Char + +-- | Permissions information for 'GenEntry'. type Permissions = FileMode -- | Polymorphic tar archive entry. High-level interfaces -- commonly work with 'GenEntry' 'FilePath' 'FilePath', --- while low level uses 'GenEntry' 'TarPath' 'LinkTarget'. +-- while low-level ones use 'GenEntry' 'TarPath' 'LinkTarget'. -- -- @since 0.6.0.0 data GenEntry tarPath linkTarget = Entry { @@ -143,14 +154,14 @@ type Entry = GenEntry TarPath LinkTarget -- | Low-level function to get a native 'FilePath' of the file or directory -- within the archive, not accounting for long names. It's likely -- that you want to apply 'Codec.Archive.Tar.decodeLongNames' --- and use 'entryTarPath' afterwards instead of 'entryPath'. +-- and use 'Codec.Archive.Tar.Entry.entryTarPath' afterwards instead of 'entryPath'. -- entryPath :: GenEntry TarPath linkTarget -> FilePath entryPath = fromTarPath . entryTarPath -- | Polymorphic content of a tar archive entry. High-level interfaces -- commonly work with 'GenEntryContent' 'FilePath', --- while low level uses 'GenEntryContent' 'LinkTarget'. +-- while low-level ones use 'GenEntryContent' 'LinkTarget'. -- -- Portable archives should contain only 'NormalFile' and 'Directory'. -- @@ -173,6 +184,7 @@ data GenEntryContent linkTarget -- ready for serialization / deserialization. type EntryContent = GenEntryContent LinkTarget +-- | Ownership information for 'GenEntry'. data Ownership = Ownership { -- | The owner user name. Should be set to @\"\"@ if unknown. ownerName :: String, @@ -241,7 +253,7 @@ executableFilePermissions = 0o0755 directoryPermissions :: Permissions directoryPermissions = 0o0755 --- | An 'Entry' with all default values except for the file name and type. It +-- | An entry with all default values except for the file name and type. It -- uses the portable USTAR/POSIX format (see 'UstarFormat'). -- -- You can use this as a basis and override specific fields, eg: @@ -261,7 +273,7 @@ simpleEntry tarpath content = Entry { entryFormat = UstarFormat } --- | A tar 'Entry' for a file. +-- | A tar entry for a file. -- -- Entry fields such as file permissions and ownership have default values. -- @@ -274,16 +286,16 @@ fileEntry :: tarPath -> LBS.ByteString -> GenEntry tarPath linkTarget fileEntry name fileContent = simpleEntry name (NormalFile fileContent (LBS.length fileContent)) --- | A tar 'Entry' for a symbolic link. +-- | A tar entry for a symbolic link. symlinkEntry :: tarPath -> linkTarget -> GenEntry tarPath linkTarget symlinkEntry name targetLink = simpleEntry name (SymbolicLink targetLink) -- | [GNU extension](https://www.gnu.org/software/tar/manual/html_node/Standard.html) --- to store a filepath too long to fit into 'entryTarPath' +-- to store a filepath too long to fit into 'Codec.Archive.Tar.Entry.entryTarPath' -- as 'OtherEntryType' @\'L\'@ with the full filepath as 'entryContent'. -- The next entry must contain the actual --- data with truncated 'entryTarPath'. +-- data with truncated 'Codec.Archive.Tar.Entry.entryTarPath'. -- -- See [What exactly is the GNU tar ././@LongLink "trick"?](https://stackoverflow.com/questions/2078778/what-exactly-is-the-gnu-tar-longlink-trick) -- @@ -299,10 +311,10 @@ longLinkEntry tarpath = Entry { } -- | [GNU extension](https://www.gnu.org/software/tar/manual/html_node/Standard.html) --- to store a link target too long to fit into 'entryTarPath' +-- to store a link target too long to fit into 'Codec.Archive.Tar.Entry.entryTarPath' -- as 'OtherEntryType' @\'K\'@ with the full filepath as 'entryContent'. -- The next entry must contain the actual --- data with truncated 'entryTarPath'. +-- data with truncated 'Codec.Archive.Tar.Entry.entryTarPath'. -- -- @since 0.6.0.0 longSymLinkEntry :: FilePath -> GenEntry TarPath linkTarget @@ -315,7 +327,7 @@ longSymLinkEntry linkTarget = Entry { entryFormat = GnuFormat } --- | A tar 'Entry' for a directory. +-- | A tar entry for a directory. -- -- Entry fields such as file permissions and ownership have default values. -- @@ -416,7 +428,6 @@ fromTarPathInternal sep = go -- | Convert a native 'FilePath' to a 'TarPath'. -- -- The conversion may fail if the 'FilePath' is empty or too long. --- Use 'toTarPath'' for a structured output. toTarPath :: Bool -- ^ Is the path for a directory? This is needed because for -- directories a 'TarPath' must always use a trailing @\/@. -> FilePath @@ -570,7 +581,7 @@ fromFilePathInternal fromSep toSep = adjustSeps -- | Polymorphic sequence of archive entries. -- High-level interfaces -- commonly work with 'GenEntries' 'FilePath' 'FilePath', --- while low level uses 'GenEntries' 'TarPath' 'LinkTarget'. +-- while low-level ones use 'GenEntries' 'TarPath' 'LinkTarget'. -- -- The point of this type as opposed to just using a list is that it makes the -- failure case explicit. We need this because the sequence of entries we get @@ -635,7 +646,7 @@ unfoldEntriesM interleave f = unfold Right Nothing -> pure Done Right (Just e) -> Next e <$> interleave unfold --- | This is like the standard 'foldr' function on lists, but for 'Entries'. +-- | This is like the standard 'Data.List.foldr' function on lists, but for 'Entries'. -- Compared to 'foldr' it takes an extra function to account for the -- possibility of failure. -- @@ -653,7 +664,7 @@ foldEntries next done fail' = fold fold Done = done fold (Fail err) = fail' err --- | A 'foldl'-like function on Entries. It either returns the final +-- | A 'Data.List.foldl'-like function on Entries. It either returns the final -- accumulator result, or the failure along with the intermediate accumulator -- value. -- @@ -668,7 +679,7 @@ foldlEntries f = go go !acc Done = Right acc go !acc (Fail err) = Left (err, acc) --- | This is like the standard 'map' function on lists, but for 'Entries'. It +-- | This is like the standard 'Data.List.map' function on lists, but for 'Entries'. It -- includes failure as a extra possible outcome of the mapping function. -- -- If your mapping function cannot fail it may be more convenient to use diff --git a/Codec/Archive/Tar/Unpack.hs b/Codec/Archive/Tar/Unpack.hs index 20b15aa..7ff458c 100644 --- a/Codec/Archive/Tar/Unpack.hs +++ b/Codec/Archive/Tar/Unpack.hs @@ -4,6 +4,7 @@ {-# LANGUAGE RankNTypes #-} {-# OPTIONS_GHC -Wno-unrecognised-pragmas #-} +{-# OPTIONS_HADDOCK hide #-} {-# HLINT ignore "Use for_" #-} ----------------------------------------------------------------------------- diff --git a/Codec/Archive/Tar/Write.hs b/Codec/Archive/Tar/Write.hs index c3b615d..3f5e9f1 100644 --- a/Codec/Archive/Tar/Write.hs +++ b/Codec/Archive/Tar/Write.hs @@ -1,4 +1,5 @@ {-# LANGUAGE PackageImports #-} +{-# OPTIONS_HADDOCK hide #-} ----------------------------------------------------------------------------- -- | -- Module : Codec.Archive.Tar.Write