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


-- | 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 <tt>hlint</tt> in-process and collect the results see
--   <a>hlint</a>.
--   
--   If you want to approximate the <tt>hlint</tt> experience with a more
--   structured API try:
--   
--   <pre>
--   (flags, classify, hint) &lt;- <a>autoSettings</a>
--   Right m &lt;- <a>parseModuleEx</a> flags "MyFile.hs" Nothing
--   print $ <a>applyHints</a> classify hint [m]
--   </pre>
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 <tt>hlint --help</tt> at
--   the console. This function writes to the stdout/stderr streams, unless
--   <tt>--quiet</tt> is specified.
--   
--   As an example:
--   
--   <pre>
--   do hints &lt;- hlint ["src", "--ignore=Use map","--quiet"]
--      when (length hints &gt; 3) $ error "Too many hints!"
--   </pre>
--   
--   <i>Warning:</i> 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 <a>Hint</a>, apply to a set
--   of modules generating a list of <a>Idea</a>s. The <a>Idea</a> values
--   will be ordered within a file.
--   
--   Given a set of modules, it may be faster to pass each to
--   <a>applyHints</a> 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 <tt>--cross</tt> to pass all modules together).
applyHints :: [Classify] -> Hint -> [ModuleEx] -> [Idea]

-- | An idea suggest by a <tt>Hint</tt>.
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. <a>Warning</a>.
[ideaSeverity] :: Idea -> Severity

-- | The name of the hint that generated the idea, e.g. <tt>"Use
--   reverse"</tt>.
[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 <a>Nothing</a> 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
--   <tt>--show</tt> 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
--   <tt>reverse (reverse x)</tt> with <tt>x</tt> makes the code lazier.
IncreasesLaziness :: Note

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

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

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

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

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

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

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

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

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

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

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

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

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

-- | The function produces a tuple containing <a>ParseFlags</a> (for
--   <a>parseModuleEx</a>), and <a>Classify</a> and <a>Hint</a> for
--   <a>applyHints</a>. It approximates the normal HLint configuration
--   steps, roughly:
--   
--   <ol>
--   <li>Use <a>findSettings</a> with <a>readSettingsFile</a> to find and
--   load the HLint settings files.</li>
--   <li>Use <a>parseFlagsAddFixities</a> and <tt>resolveHints</tt> to
--   transform the outputs of <a>findSettings</a>.</li>
--   </ol>
--   
--   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 <a>autoSettings</a> 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 <a>readSettingsFile</a>),
--   and a module to start from (defaults to <tt>hlint.yaml</tt>) find the
--   information from all settings files.
findSettings :: (String -> IO (FilePath, Maybe String)) -> Maybe String -> IO ([FixityInfo], [Classify], Hint)

-- | Given a directory (or <a>Nothing</a> to imply <a>getHLintDataDir</a>),
--   and a module name (e.g. <tt>HLint.Default</tt>), 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
--   <tt>HLint.</tt> 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 <a>Monoid</a>
--   instance.
data Hint

-- | Result of <a>parseModuleEx</a>, 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
--   <tt>-</tt> is treated as <tt>stdin</tt>. Requires some flags (often
--   <a>defaultParseFlags</a>), the filename, and optionally the contents
--   of that file.
--   
--   Note that certain programs, e.g. <tt>main = do</tt> 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 <a>ModuleEx</a> 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 <tt>&gt;</tt>
--   character pointing at the faulty line.
[parseErrorContents] :: ParseError -> String

-- | Default value for <a>ParseFlags</a>.
defaultParseFlags :: ParseFlags

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

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

-- | Base language (e.g. Haskell98, Haskell2010), defaults to
--   <a>Nothing</a>.
[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
--   <tt>base</tt>.
[fixities] :: ParseFlags -> [FixityInfo]

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

-- | Lines prefixed with <tt>#</tt> are stripped.
CppSimple :: CppFlags

-- | The <tt>cpphs</tt> 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:
--   
--   <pre>
--   infixr 3 `foo`
--   </pre>
--   
--   would create <tt>("foo", RightAssociative, 3)</tt>.
type FixityInfo = (String, Associativity, Int)

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