-- 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

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

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

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

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

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

-- | <tt>getFortune f i</tt> retrieves the text of the <tt>i</tt>'th
--   fortune (according to the order in the index file) in the
--   <a>FortuneFile</a> <tt>f</tt>.
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

-- | <tt>openIndex path writeMode</tt>: Opens the index file at
--   <tt>path</tt>. The <a>Index</a> will be writable if <tt>writeMode</tt>
--   is <a>True</a>. If there is no index file at that path, an error will
--   be thrown or the index will be created, depending on
--   <tt>writeMode</tt>.
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 <a>Index</a> file is just a header containing
--   <a>FortuneStats</a> and an array of these entries. An
--   <a>IndexEntry</a> 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 <a>FortuneStats</a> 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 <a>FortuneStats</a> record describing it.
indexEntryStats :: IndexEntry -> FortuneStats

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

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

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

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

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

-- | Delete all entries from an <a>Index</a>.
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 <a>Bool</a> 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
--   <tt>fortune</tt>).
listFortuneFiles :: Bool -> FilePath -> IO [FilePath]

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

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

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

-- | Like <a>findFortuneFileIn</a> 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
--   <a>getFortuneSearchPath</a>)
defaultFortuneFiles :: FortuneType -> IO [FilePath]

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

-- | Get the configured search path for a specified fortune type. If the
--   environment variable <tt>MISFORTUNE_PATH_<a>TYPE</a></tt> is set, it
--   will be used. Otherwise, if <tt>MISFORTUNE_PATH</tt> is set, it will
--   be used. Otherwise, the <a>defaultFortuneSearchPath</a> will be used.
--   
--   Environment variables are interpreted by splitting on
--   <tt><tt>:</tt></tt> and checking for an optional <a>+</a> or <a>-</a>
--   prefix on each component (where <a>+</a> 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 <a>FortuneFile</a>s, compute a distrubution over them
--   weighted by the number of fortunes in each. If this distribution is
--   used with <a>randomFortuneFromRandomFile</a>, the result will be a
--   uniform selection over all the fortunes in all the files.
defaultFortuneDistribution :: [FortuneFile] -> IO (Categorical Float FortuneFile)

-- | Like <a>defaultFortuneDistribution</a>, 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 <a>FortuneFile</a>, ensuring the file
--   is closed when the action exits.
withFortuneFile :: FilePath -> Char -> Bool -> (FortuneFile -> IO a) -> IO a

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