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