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

-- | The Hoogle API. To perform a search you call search with a
--   Database (obtained by loadDatabase) and a Query
--   (obtained by parseQuery).
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
--   TagColor should be black.
TagColor :: Int -> TagStr -> TagStr

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

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

-- | Show a TagStr 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 TagEmph
--   to indicate which part was incorrect.
parseInput :: ParseError -> TagStr

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

-- | The languages supported by Hoogle.
data Language

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

-- | A Hoogle database, containing a set of functions/items which can be
--   searched. The Database type is used for a variety of purposes:
--   
--   
--   
- Creation A database is created by merging existing
--   databases with the Monoid instance and mappend, or by
--   creating a new Database from an input file with
--   createDatabase.
--   
- Serialization A database is saved to disk with
--   saveDatabase and loaded from disk with
--   loadDatabase.
--   
- Searching A database is searched using search.
--   
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
--   hSetEncoding and utf8.
createDatabase :: Language -> [Database] -> String -> ([ParseError], Database)

-- | Show debugging information on some parts of the database. If the
--   second argument is Nothing 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 TagColor 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
--   False) or included (paired with True) in the query.
queryPackages :: Query -> [(Bool, String)]

-- | Set the state of a package within a query. Nothing means delete
--   the package, Just True for add it, and Just
--   False 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
--   IO 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)])]

-- | Rendered view for the entry, including namekeywordstype as
--   appropriate, colors matching renderQuery
self :: Result -> TagStr

-- | Documentation for the entry
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]

-- | Given a query, set whether it is an exact query.
queryExact :: Maybe ItemKind -> Query -> Query
data ItemKind
PackageItem :: ItemKind
ModuleItem :: ItemKind
FunctionItem :: ItemKind
DataCtorItem :: ItemKind
TypeCtorItem :: ItemKind
TypeSynonymItem :: ItemKind
ClassItem :: ItemKind
InstanceItem :: ItemKind
UnclassifiedItem :: ItemKind
instance Eq Result
instance Show Result
instance Show Database
instance Monoid Database
instance NFData Database
