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


-- | Haskell API Search
--   
--   Hoogle is a Haskell API search engine, which allows you to search many
--   standard Haskell libraries by either function name, or by approximate
--   type signature.
@package hoogle
@version 4.2


-- | The Hoogle API. To perform a search you call <a>search</a> with a
--   <a>Database</a> (obtained by <a>loadDatabase</a>) and a <a>Query</a>
--   (obtained by <a>parseQuery</a>).
module Hoogle
data TagStr

-- | Plain text.
Str :: String -> TagStr

-- | A list of tags one after another.
Tags :: [TagStr] -> TagStr

-- | Bold text.
TagBold :: TagStr -> TagStr

-- | Underlined/italic text.
TagEmph :: TagStr -> TagStr

-- | A hyperlink to a URL.
TagLink :: String -> TagStr -> TagStr

-- | Colored text. Index into a 0-based palette. Text without any
--   <a>TagColor</a> should be black.
TagColor :: Int -> TagStr -> TagStr

-- | Show a <a>TagStr</a> as a string, without any formatting.
showTagText :: TagStr -> String

-- | Show a <a>TagStr</a> on a console with ANSI escape sequences.
showTagANSI :: TagStr -> String

-- | Show a <a>TagStr</a> as HTML, using CSS classes for color styling.
showTagHTML :: TagStr -> String

-- | Show TagStr with an override for specific tags.
showTagHTMLWith :: (TagStr -> Maybe String) -> TagStr -> String

-- | Data type representing a parse error. All indecies are 1-based.
data ParseError
ParseError :: Int -> Int -> String -> TagStr -> ParseError

-- | Line number on which the error occured, 1 for the first line of a
--   file.
lineNo :: ParseError -> Int

-- | Column number on which the error occured, 1 for the first character of
--   a line.
columnNo :: ParseError -> Int

-- | Error message caused by the parse error.
errorMessage :: ParseError -> String

-- | Input string which caused the error - sometimes with a <a>TagEmph</a>
--   to indicate which part was incorrect.
parseInput :: ParseError -> TagStr

-- | A URL, or internet address. These addresses will usually start with
--   either <tt>http://</tt> or <tt>file://</tt>.
type URL = String

-- | The languages supported by Hoogle.
data Language

-- | The Haskell language (<a>http://haskell.org/</a>), along with many GHC
--   specific extensions.
Haskell :: Language

-- | A Hoogle database, containing a set of functions/items which can be
--   searched. The <a>Database</a> type is used for a variety of purposes:
--   
--   <ul>
--   <li><i>Creation</i> A database is created by merging existing
--   databases with the <a>Monoid</a> instance and <a>mappend</a>, or by
--   creating a new <a>Database</a> from an input file with
--   <a>createDatabase</a>.</li>
--   <li><i>Serialization</i> A database is saved to disk with
--   <a>saveDatabase</a> and loaded from disk with
--   <a>loadDatabase</a>.</li>
--   <li><i>Searching</i> A database is searched using <a>search</a>.</li>
--   </ul>
data Database

-- | Load a database from a file. If the database was not saved with the
--   same version of Hoogle, it will probably throw an error.
loadDatabase :: FilePath -> IO Database

-- | Save a database to a file.
saveDatabase :: FilePath -> Database -> IO ()

-- | Create a database from an input definition. Source files for Hoogle
--   databases are usually stored in UTF8 format, and should be read using
--   <a>hSetEncoding</a> and <a>utf8</a>.
createDatabase :: Language -> [Database] -> String -> ([ParseError], Database)

-- | Show debugging information on some parts of the database. If the
--   second argument is <a>Nothing</a> the whole database will be shown.
--   Otherwise, the listed parts will be shown.
showDatabase :: Database -> Maybe [String] -> String

-- | A query, representing a user input.
data Query

-- | Parse a query for a given language, returning either a parse error, or
--   a query.
parseQuery :: Language -> String -> Either ParseError Query

-- | Render a query, in particular using <a>TagColor</a> for any type
--   signature argument positions.
renderQuery :: Query -> TagStr

-- | Given a query, return the list of packages that should be searched.
--   Each package will be the name of a database, without any file path or
--   extension included.
queryDatabases :: Query -> [String]

-- | Return those packages which are explicitly excluded (paired with
--   <a>False</a>) or included (paired with <a>True</a>) in the query.
queryPackages :: Query -> [(Bool, String)]

-- | Set the state of a package within a query. <a>Nothing</a> means delete
--   the package, <a>Just</a> <a>True</a> for add it, and <a>Just</a>
--   <a>False</a> for remove it.
querySetPackage :: Maybe Bool -> String -> Query -> Query

-- | A score, representing how close a match is. Lower scores are better.
data Score

-- | Given a set of scores, where the first is lower than the second,
--   returns details for how to rank scores. This function is in the
--   <a>IO</a> monad since it may require randomness, and it may output
--   status messages while solving, particularly if in Verbose mode.
scoring :: [(Score, Score)] -> IO String
data Result
Result :: [(URL, [(URL, String)])] -> TagStr -> TagStr -> Result
locations :: Result -> [(URL, [(URL, String)])]
self :: Result -> TagStr
docs :: Result -> TagStr

-- | Perform a search. The results are returned lazily.
search :: Database -> Query -> [(Score, Result)]

-- | Given a query and a database optionally give a list of what the user
--   might have meant.
suggestions :: Database -> Query -> Maybe TagStr

-- | Given a query string and a database return a list of the possible
--   completions for the search.
completions :: Database -> String -> [String]
instance Show Database
instance Monoid Database