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


-- | A grab bag of modules.
--   
--   A hodge-podge of functions and modules that do not have a better home
@package Extra
@version 1.46


-- | this module provides a simple mechanism for adding IO operations to a
--   queue and running them in a single thread. This is useful if the IO
--   operations have side-effects which could collide if run from multiple
--   threads. For example, creating an image thumbnail and storing it on
--   disk, running latex, etc.
module Extra.IOThread
newtype IOThread a b
IOThread :: (Chan (a, MVar (Either SomeException b))) -> IOThread a b

-- | start the IO thread.
startIOThread :: (a -> IO b) -> IO (ThreadId, IOThread a b)

-- | issue a request to the IO thread and get back the result if the thread
--   function throws an exception <a>ioRequest</a> will rethrow the
--   exception.
ioRequest :: (IOThread a b) -> a -> IO b

module Test.QuickCheck.Properties
isIdempotentBy :: (Arbitrary a, Eq a, Show a) => (a -> a) -> Gen a -> Property
isIdempotent :: (Arbitrary a, Eq a, Show a) => (a -> a) -> Property


-- | Some glue code for running QuickCheck tests using the HUnit framework.
--   
--   This module provides an instance of Test.HUnit.Testable for
--   Test.QuickCheck.Property, which makes it trivial to use QuickCheck
--   properties in the HUnit framework:
--   
--   <pre>
--      import Test.HUnit
--      import Test.HUnit.Text
--      import Test.QuickCheck
--      import Test.QUnit
--   
--   runTestTT $ ("x /= x" ~: property (x -&gt; x /= x))
--   </pre>
--   
--   The QuickCheck Property will be run using
--   Test.QuickCheck.defaultConfig. If you need to specific an alternate
--   config, then use <a>testQuickCheck</a> like this:
--   
--   <pre>
--   runTestTT $ ("x /= x" ~: testQuickCheck myConfig (x -&gt; x /= x))
--   </pre>
module Test.QUnit

-- | turns the quickcheck test into an hunit test
--   
--   Use this if you want to provide a custom <tt>Config</tt> instead of
--   <tt>defaultConfig</tt>.
testQuickCheck :: Testable a => Args -> a -> Test
instance Testable Property


-- | Make URI an instance of Read and Ord, and add functions to manipulate
--   the uriQuery.
module Extra.URI

-- | Create a relative URI with the given query.
relURI :: FilePath -> [(String, String)] -> URI

-- | Set the port number in the URI authority, creating it if necessary.
setURIPort :: [Char] -> URI -> URI

-- | Return the pairs in a URI's query
parseURIQuery :: URI -> [(String, String)]

-- | Modify a URI's query by applying a function to the pairs
modifyURIQuery :: ([(String, String)] -> [(String, String)]) -> URI -> URI
setURIQuery :: [(String, String)] -> URI -> URI
setURIQueryAttr :: String -> String -> URI -> URI
deleteURIQueryAttr :: String -> URI -> URI
instance Read URI

module Extra.URIQuery

-- | Modify an individual URI query attributes.
modify :: String -> (Maybe String -> Maybe String) -> URI -> URI

-- | Replace a query attribute with Nothing.
del :: String -> URI -> URI

-- | Replace a query attribute with something.
put :: String -> String -> URI -> URI

-- | Copy an attribute from one query to another
copy :: String -> URI -> URI -> URI

module Extra.Time
formatDebianDate :: FormatTime t => t -> [Char]
myTimeDiffToString :: TimeDiff -> [Char]

module Extra.SSH

-- | See if we already have access to the destination (user@host).
sshVerify :: String -> Maybe Int -> IO Bool

-- | Set up access to destination (user@host).
sshExportDeprecated :: String -> Maybe Int -> IO (Either String ())

-- | Copy the ssh configuration from $HOME to the /root directory of a
--   changeroot.
sshCopy :: FilePath -> IO ExitCode

module Extra.Net

-- | Parse the text returned when a directory is listed by a web server.
--   This is currently only known to work with Apache. NOTE: there is a
--   second copy of this function in debian:Debian.URI. Please update both
--   locations if you make changes.
webServerDirectoryContents :: ByteString -> [String]

module Extra.Lock
withLock :: MonadIO m => FilePath -> m a -> m a

-- | Like withLock, but instead of giving up immediately, try n times with
--   a wait between each. awaitLock :: (MonadIO m) =&gt; Int -&gt; Int
--   -&gt; FilePath -&gt; m a -&gt; m (Either Exception a)
awaitLock :: (Num a, Ord a) => a -> Int -> [Char] -> IO b -> IO b

module Extra.Terminal
c_get_window_size :: IO CLong
getWinSize :: IO (Int, Int)
getWidth :: IO (Maybe Int)

module Extra.List

-- | The mighty consperse function - e.g. consperse <a>,</a> [<a>a</a>,
--   <a>b</a>] -&gt; <a>a,b</a> consperse = MissingH.List.join

-- | <i>Deprecated: Use intercalate</i>
consperse :: [a] -> [[a]] -> [a]

-- | surround each element of a list - e.g. surround <a>(</a> <a>)</a>
--   [<a>a</a>, <a>b</a>] -&gt; [<a>(a)(b)</a>]
surround :: [a] -> [a] -> [[a]] -> [a]

-- | Replace the prefix of s, return Nothing if it doesn't match.
changePrefix :: Eq a => [a] -> [a] -> [a] -> Maybe [a]

-- | Remove a prefix of s, return nothing if it doesn't match.
dropPrefix :: Eq a => [a] -> [a] -> Maybe [a]

-- | cartesianProduct [[1,2,3], [4,5],[6]] -&gt;
--   [[1,4,6],[1,5,6],[2,4,6],[2,5,6],[3,4,6],[3,5,6]]
cartesianProduct :: [[a]] -> [[a]]

-- | FIXME: implement for a string
wordsBy :: Eq a => (a -> Bool) -> [a] -> [[a]]

-- | Like maybe, but with empty vs. non-empty list
empty :: b -> ([a] -> b) -> [a] -> b

-- | Sort a list using the compare function on the list elements mapped
--   over f. This is like <a>sortBy ( a b -&gt; compare (f a) (f b))</a>
--   except that f is applied O(n) times instead of O(n log n)
sortByMapped :: (a -> b) -> (b -> b -> Ordering) -> [a] -> [a]

-- | Monadic version of sortByMapped
sortByMappedM :: (a -> IO b) -> (b -> b -> Ordering) -> [a] -> IO [a]
partitionM :: Monad m => (a -> m Bool) -> [a] -> m ([a], [a])
listIntersection :: Eq a => [[a]] -> [a]
isSublistOf :: Eq a => [a] -> [a] -> Maybe Int

module Extra.Misc

-- | Pad strings so the columns line up. The argument and return value
--   elements are the rows of a table. Do not pad the rightmost column.
columns :: [[String]] -> [[String]]

-- | Group words into lines of length n or less.
justify :: String -> Int -> [[String]]
mapSnd :: (b -> c) -> (a, b) -> (a, c)

-- | dirname
parentPath :: FilePath -> FilePath

-- | Weak attempt at canonicalizing a file path.
canon :: FilePath -> FilePath

-- | Turn a list of (k, a) pairs into a map from k -&gt; [a]. The order of
--   the elements in the a list is preserved.
listMap :: Ord k => [(k, a)] -> Map k [a]
listDiff :: Ord a => [a] -> [a] -> [a]
checkSuperUser :: IO Bool

-- | Run md5sum on a file and return the resulting checksum as text.

-- | <i>Deprecated: Use Data.ByteString.Lazy.Char8.readFile path &gt;&gt;=
--   return . show . Data.Digest.Pure.MD5.md5</i>
md5sum :: FilePath -> IO String

-- | Predicate to decide if two files have the same inode.
sameInode :: FilePath -> FilePath -> IO Bool

-- | Predicate to decide if two files have the same md5 checksum.
sameMd5sum :: FilePath -> FilePath -> IO Bool

-- | Given a tarball, return the name of the top directory.
tarDir :: FilePath -> IO (Maybe String)
cd :: FilePath -> IO a -> IO a

-- | A version of read with a more helpful error message.
read' :: Read a => String -> a

module Extra.GPGSign
sign :: PGPKey'' -> FilePath -> IO FilePath
data PGPKey
Key :: String -> PGPKey
Default :: PGPKey
pgpSignFiles :: FilePath -> PGPKey -> [FilePath] -> IO [Bool]
pgpSignFile :: PGPKey -> FilePath -> IO Bool
cd :: FilePath -> IO a -> IO a
instance Show PGPKey


-- | Some extra operations on files. The functions here generally return
--   (Right ()) on success, Left [messages] on failure, and throw an
--   exception when a failure leaves things in an inconsistant state. An
--   example of an inconsistant state would be if we got a failure when
--   writing out a file, but were unable to restore the original file to
--   its original position.
module Extra.Files

-- | Return the list of subdirectories, omitting . and .. and ignoring
--   symbolic links.
getSubDirectories :: FilePath -> IO [String]

-- | Change a file's name, removing any existing file with the new name.
renameAlways :: FilePath -> FilePath -> IO (Either [String] ())

-- | Change a file's name only if the new name doesn't exist.
renameMissing :: FilePath -> FilePath -> IO (Either [String] ())

-- | Delete a file if it exists
deleteMaybe :: FilePath -> IO (Either [String] ())

-- | Atomically install a list of files. Returns a list of what went wrong
--   on failure. Will throw an error if it fails and is unable to restore
--   the original files to their original states.
installFiles :: [(FilePath, FilePath)] -> IO (Either [String] ())

-- | Write out three versions of a file, regular, gzipped, and bzip2ed.
writeAndZipFileWithBackup :: FilePath -> ByteString -> IO (Either [String] ())

-- | Write out three versions of a file, regular, gzipped, and bzip2ed.
--   This new version assumes the files are written to temporary locations,
--   so any existing file there can be removed.
writeAndZipFile :: FilePath -> ByteString -> IO (Either [String] ())
backupFile :: FilePath -> IO (Either [String] ())

-- | Like writeFile, but if the file already exists don't touch it.
--   Example: writeFileIfMissing True "/var/lib/dpkg/status" ""
writeFileIfMissing :: Bool -> FilePath -> String -> IO ()

-- | Write a file if its content is different from the given text.
maybeWriteFile :: FilePath -> String -> IO ()

-- | Add-on for System.Posix.Files
createSymbolicLinkIfMissing :: String -> FilePath -> IO ()
prepareSymbolicLink :: FilePath -> FilePath -> IO ()

-- | like removeLink, but does not fail if link did not exist
forceRemoveLink :: FilePath -> IO ()
replaceFile :: FilePath -> String -> IO ()

module Extra.HughesPJ

-- | render a Doc using the current terminal width
renderWidth :: Doc -> IO String

module Extra.Exit

-- | exitFailure with nicely formatted help text on stderr
exitWithHelp :: (String -> Doc) -> IO a

module Extra.Either
isRight :: Either t t1 -> Bool
isLeft :: Either t t1 -> Bool

-- | Turn a list of eithers into an either of lists
concatEithers :: [Either a b] -> Either [a] [b]

-- | <i>Deprecated: Use rights</i>
rightOnly :: [Either a b] -> [b]

-- | <i>Deprecated: Use concatEithers</i>
eitherFromList :: [Either a b] -> Either [a] [b]


-- | CIO is a type class for the TIO monad, which tracks the cursor
--   position of the console so that indentation and prefixes can be added
--   to the output. TIO also has a style component which lets you control
--   the output verbosity and the appearance of the prefix. There is an
--   instance for the regular IO monad which doesn't use any of these
--   features, to allow functions which do not use the TIO monad call
--   functions in the Debian library.
--   
--   NOTE: a copy of this library is in the Extra library as well. Please
--   update both locations.
--   
--   This code is provided for backwards compatibility, I don't endorse its
--   use in new projects.

-- | <i>Deprecated: Use System.Unix.QIO in Unixutils.</i>
module Extra.CIO

-- | Class representing ways of doing console (terminal?) output.
class MonadIO m => CIO m
hPutStr :: CIO m => Handle -> String -> m ()
hBOL :: CIO m => Handle -> m ()
ev :: CIO m => Int -> m Int
setStyle :: CIO m => (TStyle -> TStyle) -> m a -> m a
tryCIO :: CIO m => m a -> m (Either SomeException a)

-- | A record used to hold the output style information for a task. This
--   The prefixes that will appear at the beginning of each line, and the
--   desired verbosity level. Suggested verbosity level policy:
--   
--   <ul>
--   <li>-1: No output of any kind, as if you were directing all output to
--   <i>dev</i>null</li>
--   <li>0: Error output only, suitable for a run whose log you might
--   examine later</li>
--   <li>1: casual progress reporting - if you were running on a console
--   but didn't expect anything to go wrong</li>
--   <li>2: detailed progress reporting - show more progress, particularly
--   things that might fail during the normal operation of the autobuilder:
--   patches that fail to apply, dpkg-buildpackage runs that return errors,
--   etc.</li>
--   <li>3: Debugging output - use this level or higher if you suspect the
--   autobuilder itself is failing, or you are doing development work on
--   the autobuilder.</li>
--   </ul>
data TStyle
TStyle :: String -> Int -> [(Handle, String)] -> TStyle

-- | Add this string at the beginning of each line
prefix :: TStyle -> String

-- | Ignore v functions whose argument is more than this
verbosity :: TStyle -> Int

-- | Per-handle prefix
hPrefix :: TStyle -> [(Handle, String)]
defStyle :: TStyle

-- | Use a new style for the TIO action
withStyle :: CIO m => TStyle -> m a -> m a
setVerbosity :: Int -> TStyle -> TStyle
addVerbosity :: Int -> TStyle -> TStyle

-- | Set the output style for a handle to prefixed.
setPrefix :: String -> TStyle -> TStyle

-- | Prepend some text to the prefix.
addPrefix :: String -> TStyle -> TStyle

-- | Append some text to the prefix.
appPrefix :: String -> TStyle -> TStyle

-- | Set the output style for the stdout and stderr handle to prefixed,
--   using whatever prefixes were most recently set (default is [1] and
--   [2].)
setPrefixes :: String -> String -> TStyle -> TStyle

-- | Switch to prefixed mode and modify both the stdout and stderr
--   prefixes.
addPrefixes :: String -> String -> TStyle -> TStyle
appPrefixes :: String -> String -> TStyle -> TStyle

-- | Get the current prefix for a particular handle
hGetPrefix :: Handle -> TStyle -> String

-- | Write a string to stdout.
putStr :: CIO m => String -> m ()

-- | Write a string to stderr.
ePutStr :: CIO m => String -> m ()

-- | Write a string to stdout depending on the verbosity level.
vPutStr :: CIO m => Int -> String -> m ()

-- | Verbosity controlled version of ePutStr
vEPutStr :: CIO m => Int -> String -> m ()

-- | Write a character.
hPutChar :: CIO m => Handle -> Char -> m ()

-- | Write a character to stdout.
putChar :: CIO m => Char -> m ()

-- | Write a character to stderr.
ePutChar :: CIO m => Char -> m ()

-- | Verbosity controlled version of hPutChar.
vHPutChar :: CIO m => Handle -> Int -> Char -> m ()

-- | Verbosity controlled version of putChar
vPutChar :: CIO m => Int -> Char -> m ()

-- | Verbosity controlled version of ePutChar
vEPutChar :: CIO m => Int -> Char -> m ()

-- | Move to beginning of next line (if necessary) and output a string.
hPutStrBl :: CIO m => Handle -> String -> m ()

-- | hPutStrBl to stdout.
putStrBl :: CIO m => String -> m ()

-- | hPutStrBl to stderr.
ePutStrBl :: CIO m => String -> m ()

-- | Verbosity controlled version of hPutStrBl
vHPutStrBl :: CIO m => Handle -> Int -> String -> m ()

-- | Verbosity controlled version of putStrBl
vPutStrBl :: CIO m => Int -> String -> m ()

-- | Verbosity controlled version of ePutStrBl
vEPutStrBl :: CIO m => Int -> String -> m ()

-- | Write a newline character and a string.
hPutStrLn :: CIO m => Handle -> String -> m ()

-- | hPutStrLn to stdout.
putStrLn :: CIO m => String -> m ()

-- | hPutStrLn to stderr.
ePutStrLn :: CIO m => String -> m ()

-- | Verbosity controlled version of hPutStrLn.
vHPutStrLn :: CIO m => Handle -> Int -> String -> m ()

-- | Verbosity controlled version of putStrLn
vPutStrLn :: CIO m => Int -> String -> m ()

-- | Verbosity controlled version of ePutStrLn
vEPutStrLn :: CIO m => Int -> String -> m ()

-- | hBOL to stdout.
bol :: CIO m => m ()

-- | hBOL to stderr.
eBOL :: CIO m => m ()
vHBOL :: CIO m => Handle -> Int -> m ()

-- | Verbosity controlled version of BOL
vBOL :: CIO m => Int -> m ()

-- | Verbosity controlled version of eBOL
vEBOL :: CIO m => Int -> m ()
hColor :: Handle -> [Char] -> [Char]
blue :: [Char] -> [Char]
green :: [Char] -> [Char]
red :: [Char] -> [Char]
magenta :: [Char] -> [Char]
instance Show TStyle


-- | <i>Deprecated: CIO is deprecated</i>
module Extra.IO
instance CIO IO

module Extra.Bool
cond :: a -> a -> Bool -> a