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

-- | Source code suggestions
--   
--   HLint gives suggestions on how to improve your source code.
@package hlint
@version 3.10

-- | This module provides a way to apply HLint hints. If you want to just
--   run hlint in-process and collect the results see
--   hlint.
--   
--   If you want to approximate the hlint experience with a more
--   structured API try:
--   
--   
--   (flags, classify, hint) <- autoSettings
--   Right m <- parseModuleEx flags "MyFile.hs" Nothing
--   print $ applyHints classify hint [m]
--   
module Language.Haskell.HLint

-- | This function takes a list of command line arguments, and returns the
--   given hints. To see a list of arguments type hlint --help at
--   the console. This function writes to the stdout/stderr streams, unless
--   --quiet is specified.
--   
--   As an example:
--   
--   
--   do hints <- hlint ["src", "--ignore=Use map","--quiet"]
--      when (length hints > 3) $ error "Too many hints!"
--   
--   
--   Warning: The flags provided by HLint are relatively stable, but
--   do not have the same API stability guarantees as the rest of the
--   strongly-typed API. Do not run this function on your server with
--   untrusted input.
hlint :: [String] -> IO [Idea]

-- | Given a way of classifying results, and a Hint, apply to a set
--   of modules generating a list of Ideas. The Idea values
--   will be ordered within a file.
--   
--   Given a set of modules, it may be faster to pass each to
--   applyHints in a singleton list. When given multiple modules at
--   once this function attempts to find hints between modules, which is
--   slower and often pointless (by default HLint passes modules
--   singularly, using --cross to pass all modules together).
applyHints :: [Classify] -> Hint -> [ModuleEx] -> [Idea]

-- | An idea suggest by a Hint.
data Idea
Idea :: [String] -> [String] -> Severity -> String -> SrcSpan -> String -> Maybe String -> [Note] -> [Refactoring SrcSpan] -> Idea

-- | The modules the idea is for, usually a singleton.
[ideaModule] :: Idea -> [String]

-- | The declarations the idea is for, usually a singleton, typically the
--   function name, but may be a type name.
[ideaDecl] :: Idea -> [String]

-- | The severity of the idea, e.g. Warning.
[ideaSeverity] :: Idea -> Severity

-- | The name of the hint that generated the idea, e.g. "Use
--   reverse".
[ideaHint] :: Idea -> String

-- | The source code the idea relates to.
[ideaSpan] :: Idea -> SrcSpan

-- | The contents of the source code the idea relates to.
[ideaFrom] :: Idea -> String

-- | The suggested replacement, or Nothing for no replacement (e.g.
--   on parse errors).
[ideaTo] :: Idea -> Maybe String

-- | Notes about the effect of applying the replacement.
[ideaNote] :: Idea -> [Note]

-- | How to perform this idea
[ideaRefactoring] :: Idea -> [Refactoring SrcSpan]

-- | How severe an issue is.
data Severity

-- | The issue has been explicitly ignored and will usually be hidden (pass
--   --show on the command line to see ignored ideas).
Ignore :: Severity

-- | Suggestions are things that some people may consider improvements, but
--   some may not.
Suggestion :: Severity

-- | Warnings are suggestions that are nearly always a good idea to apply.
Warning :: Severity

-- | Available as a setting for the user. Only parse errors have this
--   setting by default.
Error :: Severity

-- | A note describing the impact of the replacement.
data Note

-- | The replacement is increases laziness, for example replacing
--   reverse (reverse x) with x makes the code lazier.
IncreasesLaziness :: Note

-- | The replacement is decreases laziness, for example replacing (fst
--   x, snd x) with x makes the code stricter.
DecreasesLaziness :: Note

-- | The replacement removes errors, for example replacing foldr1
--   (+) with sum removes an error on [], and might
--   contain the text "on []".
RemovesError :: String -> Note

-- | The replacement assumes standard type class lemmas, a hint with the
--   note ValidInstance "Eq" "x" might only be valid if the
--   x variable has a reflexive Eq instance.
ValidInstance :: String -> String -> Note

-- | The replacement requires this extension to be available.
RequiresExtension :: String -> Note

-- | An arbitrary note.
Note :: String -> Note

-- | Unpack a SrcSpan value. Useful to allow using the Idea
--   information without adding a dependency on ghc or
--   ghc-lib-parser. Unpacking gives:
--   
--   
--   (filename, (startLine, startCol), (endLine, endCol))
--   
--   
--   Following the GHC API, end column is the column after the end
--   of the error. Lines and columns are 1-based. Returns Nothing if
--   there is no helpful location information.
unpackSrcSpan :: SrcSpan -> Maybe (FilePath, (Int, Int), (Int, Int))

-- | Show an Idea with ANSI color codes to give syntax coloring to
--   the Haskell code.
showIdeaANSI :: Idea -> String

-- | How to classify an Idea. If any matching field is ""
--   then it matches everything.
data Classify
Classify :: Severity -> String -> String -> String -> Classify

-- | Severity to set the Idea to.
[classifySeverity] :: Classify -> Severity

-- | Match on Idea field ideaHint.
[classifyHint] :: Classify -> String

-- | Match on Idea field ideaModule.
[classifyModule] :: Classify -> String

-- | Match on Idea field ideaDecl.
[classifyDecl] :: Classify -> String

-- | Get the Cabal configured data directory of HLint.
getHLintDataDir :: IO FilePath

-- | The function produces a tuple containing ParseFlags (for
--   parseModuleEx), and Classify and Hint for
--   applyHints. It approximates the normal HLint configuration
--   steps, roughly:
--   
--   
--   
- Use findSettings with readSettingsFile to find and
--   load the HLint settings files.
--   
- Use parseFlagsAddFixities and resolveHints to
--   transform the outputs of findSettings.
--   
--   
--   If you want to do anything custom (e.g. using a different data
--   directory, storing intermediate outputs, loading hints from a
--   database) you are expected to copy and paste this function, then
--   change it to your needs.
autoSettings :: IO (ParseFlags, [Classify], Hint)

-- | A version of autoSettings which respects some of the arguments
--   supported by HLint. If arguments unrecognised by HLint are used it
--   will result in an error. Arguments which have no representation in the
--   return type are silently ignored.
argsSettings :: [String] -> IO (ParseFlags, [Classify], Hint)

-- | Given a function to load a module (typically readSettingsFile),
--   and a module to start from (defaults to hlint.yaml) find the
--   information from all settings files.
findSettings :: (String -> IO (FilePath, Maybe String)) -> Maybe String -> IO ([FixityInfo], [Classify], Hint)

-- | Given a directory (or Nothing to imply getHLintDataDir),
--   and a module name (e.g. HLint.Default), find the settings
--   file associated with it, returning the name of the file, and
--   (optionally) the contents.
--   
--   This function looks for all settings files starting with
--   HLint. in the directory argument, and all other files
--   relative to the current directory.
readSettingsFile :: Maybe FilePath -> String -> IO (FilePath, Maybe String)

-- | Functions to generate hints, combined using the Monoid
--   instance.
data Hint

-- | Result of parseModuleEx, representing a parsed module.
data ModuleEx

-- | Parse a Haskell module. Applies the C pre processor, and uses
--   best-guess fixity resolution if there are ambiguities. The filename
--   - is treated as stdin. Requires some flags (often
--   defaultParseFlags), the filename, and optionally the contents
--   of that file.
--   
--   Note that certain programs, e.g. main = do successfully parse
--   with GHC, but then fail with an error in the renamer. These programs
--   will return a successful parse.
parseModuleEx :: ParseFlags -> FilePath -> Maybe String -> IO (Either ParseError ModuleEx)

-- | Create a ModuleEx from a GHC module. It is assumed the incoming
--   parsed module has not been adjusted to account for operator fixities
--   (it uses the HLint default fixities).
createModuleEx :: Located (HsModule GhcPs) -> ModuleEx
createModuleExWithFixities :: [(String, Fixity)] -> Located (HsModule GhcPs) -> ModuleEx

-- | A parse error.
data ParseError
ParseError :: SrcSpan -> String -> String -> ParseError

-- | Location of the error.
[parseErrorLocation] :: ParseError -> SrcSpan

-- | Message about the cause of the error.
[parseErrorMessage] :: ParseError -> String

-- | Snippet of several lines (typically 5) including a >
--   character pointing at the faulty line.
[parseErrorContents] :: ParseError -> String

-- | Default value for ParseFlags.
defaultParseFlags :: ParseFlags

-- | Created with defaultParseFlags, used by parseModuleEx.
data ParseFlags
ParseFlags :: CppFlags -> Maybe Language -> [Extension] -> [Extension] -> [FixityInfo] -> ParseFlags

-- | How the file is preprocessed (defaults to NoCpp).
[cppFlags] :: ParseFlags -> CppFlags

-- | Base language (e.g. Haskell98, Haskell2010), defaults to
--   Nothing.
[baseLanguage] :: ParseFlags -> Maybe Language

-- | List of extensions enabled for parsing, defaults to many
--   non-conflicting extensions.
[enabledExtensions] :: ParseFlags -> [Extension]

-- | List of extensions disabled for parsing, usually empty.
[disabledExtensions] :: ParseFlags -> [Extension]

-- | List of fixities to be aware of, defaults to those defined in
--   base.
[fixities] :: ParseFlags -> [FixityInfo]

-- | What C pre processor should be used.
data CppFlags

-- | Lines prefixed with # are stripped.
CppSimple :: CppFlags

-- | The cpphs library is used.
Cpphs :: CpphsOptions -> CppFlags

-- | A Fixity definition, comprising the name the fixity applies to, the
--   direction and the precedence. As an example, a source file containing:
--   
--   
--   infixr 3 `foo`
--   
--   
--   would create ("foo", RightAssociative, 3).
type FixityInfo = (String, Associativity, Int)

-- | Given some fixities, add them to the existing fixities in
--   ParseFlags.
parseFlagsAddFixities :: [FixityInfo] -> ParseFlags -> ParseFlags
