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

-- | fortune-mod clone
--   
--   fortune-mod clone, in library and executable form.
@package misfortune
@version 0.1.1.2

module Data.Fortune

-- | A handle to an open fortune database.
data FortuneFile

-- | Get the path of the text part of an open fortune database.
fortuneFilePath :: FortuneFile -> FilePath

-- | Get the path of the index part of an open fortune database.
fortuneIndexPath :: FortuneFile -> FilePath

-- | openFortuneFile path delim writeMode: Open a fortune file at
--   path, using delim as the character between strings,
--   allowing writing if writeMode is set. If no file exists at
--   the specified path, an error will be thrown or the file will be
--   created, depending on writeMode.
openFortuneFile :: Char -> Bool -> FilePath -> IO FortuneFile

-- | Close a fortune file. Subsequent accesses will fail.
closeFortuneFile :: FortuneFile -> IO ()

-- | Get the Index of a FortuneFile, opening it if necessary.
getIndex :: FortuneFile -> IO Index

-- | Clear a FortuneFiles Index and rebuild it from the
--   contents of the text file.
rebuildIndex :: FortuneFile -> IO ()

-- | getFortune f i retrieves the text of the i'th
--   fortune (according to the order in the index file) in the
--   FortuneFile f.
getFortune :: FortuneFile -> Int -> IO Text

-- | Get the text of every fortune in a fortune file, in the order they
--   occur in the file. Ignores the index entirely.
getFortunes :: FortuneFile -> IO [Text]

-- | Get the number of fortunes in a fortune file, as recorded in the
--   index.
getNumFortunes :: FortuneFile -> IO Int

-- | Append a fortune to a fortune file, inserting a delimiter if needed
--   and updating the index.
appendFortune :: FortuneFile -> Text -> IO ()

-- | A handle to an open fortune index file.
data Index

-- | openIndex path writeMode: Opens the index file at
--   path. The Index will be writable if writeMode
--   is True. If there is no index file at that path, an error will
--   be thrown or the index will be created, depending on
--   writeMode.
openIndex :: FilePath -> Bool -> IO Index

-- | Create an in-memory index - useful for working with files when, for
--   whatever reason, you cannot create a valid index.
createVirtualIndex :: IO Index

-- | Close an index file. Subsequent accesses will fail.
closeIndex :: Index -> IO ()

-- | Get some cached stats about the fortunes indexed in this file.
getStats :: Index -> IO FortuneStats

-- | Errors that can be thrown when stats are read from an index file.
--   These errors describe various logical inconsistencies that generally
--   indicate that the index file is corrupted somehow.
data StatsProblem
NegativeCount :: !Int -> StatsProblem
NegativeLength :: !Int -> StatsProblem
NegativeOffset :: !Int -> StatsProblem
LengthsWithoutEntries :: StatsProblem
EntriesWithoutLengths :: StatsProblem
MaxLengthLessThanMinLength :: StatsProblem
InconsistentLengthsForOneEntry :: StatsProblem

-- | An exception type indicating things that can be wrong about an index
--   file's header.
data HeaderProblem
BadMagicNumber :: !Word32 -> HeaderProblem
UnsupportedVersion :: !Word32 -> HeaderProblem
StatsProblem :: !StatsProblem -> HeaderProblem
TableStartsBeforeHeaderEnds :: HeaderProblem

-- | Errors that can be thrown indicating a problem with an index file.
data IndexProblem
HeaderProblem :: !HeaderProblem -> IndexProblem
TableLongerThanFile :: IndexProblem
AccessToClosedIndex :: IndexProblem

-- | Force a consistency check on an index file.
checkIndex :: Index -> IO (Maybe IndexProblem)

-- | Conceptually, an Index file is just a header containing
--   FortuneStats and an array of these entries. An
--   IndexEntry stores the information needed to locate one string
--   in the fortune fiel, as well as some basic stats about that one file
--   (from which the FortuneStats will be derived).
data IndexEntry
IndexEntry :: !Int -> !Int -> !Int -> !Int -> IndexEntry

-- | The location of the string in the file, as a byte offset
[stringOffset] :: IndexEntry -> !Int

-- | The number of bytes the string occupies.
[stringBytes] :: IndexEntry -> !Int

-- | The number of characters in the string.
[stringChars] :: IndexEntry -> !Int

-- | The number of lines in the string.
[stringLines] :: IndexEntry -> !Int

-- | Convert one index entry to a FortuneStats record describing it.
indexEntryStats :: IndexEntry -> FortuneStats

-- | Read all the entries in an Index
getEntries :: Index -> IO (Vector IndexEntry)

-- | Read a specified entry from an Index.
getEntry :: Index -> Int -> IO IndexEntry

-- | Repeatedly invoke a generator for index entries until it returns
--   Nothing, appending all entries returned to the index file.
unfoldEntries :: Index -> IO (Maybe IndexEntry) -> IO ()

-- | Append all the given entries to the Index file.
appendEntries :: Index -> Vector IndexEntry -> IO ()

-- | Append a single IndexEntry to an Index file.
appendEntry :: Index -> IndexEntry -> IO ()

-- | Delete all entries from an Index.
clearIndex :: Index -> IO ()

-- | All the operations here should preserve correctness of stats, but just
--   in case... This procedure forces the stats to be recomputed.
rebuildStats :: Index -> IO ()

-- | Some statistics about the fortunes in a database. These are stored in
--   the index file and used to speed up various calculations that would
--   otherwise require re-reading lots of files.
data FortuneStats

-- | The number of fortune strings in the index
numFortunes :: FortuneStats -> Int

-- | The smallest number of characters in any string in the index
minChars :: FortuneStats -> Int

-- | The greatest number of characters in any string in the index
maxLines :: FortuneStats -> Int

-- | The smallest number of lines in any string in the index
minLines :: FortuneStats -> Int

-- | The greatest number of lines in any string in the index
maxChars :: FortuneStats -> Int

-- | List all the fortune files in a directory. The Bool value
--   specifies whether to search subtrees as well.
--   
--   Any file which does not have an extension of ".ix" or ".dat" will be
--   reported as a fortune file (".dat" is not used by misfortune, but is
--   ignored so that misfortune can share fortune databases with
--   fortune).
listFortuneFiles :: Bool -> FilePath -> IO [FilePath]

-- | List all the fortune files in several directories. Each directory will
--   be searched by listFortuneFiles (using the corresponding
--   Bool value to control whether the directory is searched
--   recursively) and all results will be combined.
listFortuneFilesIn :: [(FilePath, Bool)] -> IO [FilePath]

-- | Like listFortuneFiles except only returning paths with the
--   specified file name.
findFortuneFile :: Bool -> FilePath -> String -> IO [FilePath]

-- | Like listFortuneFilesIn except only returning paths with the
--   specified file name.
findFortuneFileIn :: [(String, Bool)] -> String -> IO [FilePath]

-- | Like findFortuneFileIn but searches for multiple files in
--   multiple directories.
findFortuneFilesIn :: [(String, Bool)] -> [String] -> IO [FilePath]

-- | Three different search paths are supported, depending on the "type" of
--   fortune requested. These are the types that can be requested.
data FortuneType
All :: FortuneType
Normal :: FortuneType
Offensive :: FortuneType

-- | Get the path of the directory containing built-in fortunes of the
--   specified type.
getFortuneDir :: FortuneType -> IO FilePath

-- | Get a list of all fortune files on the configured search path (see
--   getFortuneSearchPath)
defaultFortuneFiles :: FortuneType -> IO [FilePath]

-- | Get the default search path for a specified fortune type (ignoring the
--   MISFORTUNE_PATH environment variables)
defaultFortuneSearchPath :: FortuneType -> IO [(FilePath, Bool)]

-- | Get the configured search path for a specified fortune type. If the
--   environment variable MISFORTUNE_PATH_TYPE is set, it
--   will be used. Otherwise, if MISFORTUNE_PATH is set, it will
--   be used. Otherwise, the defaultFortuneSearchPath will be used.
--   
--   Environment variables are interpreted by splitting on
--   : and checking for an optional + or -
--   prefix on each component (where + indicates recursive search of
--   that directory). The default is non-recursive search for each
--   component.
getFortuneSearchPath :: FortuneType -> IO [(FilePath, Bool)]

-- | Search for all fortune files in the configured search path with the
--   given name.
resolveFortuneFile :: FortuneType -> String -> IO [FilePath]

-- | Search for all fortune files in the configured search path with any of
--   the given names.
resolveFortuneFiles :: FortuneType -> [String] -> IO [FilePath]

-- | Select a random fortune from all files matching any of a list of names
--   (or if the list is empty, all fortune files on the search path). Every
--   fortune string will have an equal probability of being selected.
randomFortune :: [String] -> IO String

-- | Select a random fortune file from a specified distribution and then
--   select a random fortune from that file (unformly).
randomFortuneFromRandomFile :: RVar FortuneFile -> IO String

-- | Given a list of FortuneFiles, compute a distrubution over them
--   weighted by the number of fortunes in each. If this distribution is
--   used with randomFortuneFromRandomFile, the result will be a
--   uniform selection over all the fortunes in all the files.
defaultFortuneDistribution :: [FortuneFile] -> IO (Categorical Float FortuneFile)

-- | Like defaultFortuneDistribution, but filtering the fortunes. In
--   addition to the fortune file, the tuples in the distribution include a
--   distribution over the matching fortune indices in that file, assigning
--   equal weight to each.
fortuneDistributionWhere :: (FortuneFile -> Int -> IndexEntry -> IO Bool) -> [FortuneFile] -> IO (Categorical Float (FortuneFile, Categorical Float Int))

-- | Perform an action with an open FortuneFile, ensuring the file
--   is closed when the action finishes.
withFortuneFile :: Char -> Bool -> FilePath -> (FortuneFile -> IO a) -> IO a

-- | Perform an action with many open FortuneFiles, ensuring the
--   files are closed when the action finishes.
withFortuneFiles :: Char -> Bool -> [FilePath] -> ([FortuneFile] -> IO a) -> IO a
mapFortunesWithIndexM :: (Enum a, Num a) => (a -> IndexEntry -> IO b) -> FortuneFile -> IO [b]
mapFortunesWithIndex :: (Num a, Enum a) => (a -> IO b) -> FortuneFile -> IO [b]
mapFortunesM :: (IndexEntry -> IO b) -> FortuneFile -> IO [b]
mapFortunes :: (IndexEntry -> b) -> FortuneFile -> IO [b]
filterFortunesWithIndexM :: (Num a, Enum a) => (a -> IndexEntry -> IO Bool) -> FortuneFile -> IO [a]
filterFortunesWithIndex :: (Enum t, Num t) => (t -> IndexEntry -> Bool) -> FortuneFile -> IO [t]
filterFortunesM :: (Enum b, Num b) => (IndexEntry -> IO Bool) -> FortuneFile -> IO [b]
filterFortunes :: (Num b, Enum b) => (IndexEntry -> Bool) -> FortuneFile -> IO [b]
instance GHC.Enum.Bounded Data.Fortune.FortuneType
instance GHC.Enum.Enum Data.Fortune.FortuneType
instance GHC.Show.Show Data.Fortune.FortuneType
instance GHC.Read.Read Data.Fortune.FortuneType
instance GHC.Classes.Ord Data.Fortune.FortuneType
instance GHC.Classes.Eq Data.Fortune.FortuneType
