-- 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 2.0.9


-- | <i>WARNING: This module represents the old version of the HLint
--   API.</i> <i>It will be deleted in favour of
--   <a>Language.Haskell.HLint3</a> in the next major version.</i>
--   
--   This module provides a library interface to HLint, strongly modelled
--   on the command line interface.
module Language.Haskell.HLint

-- | This function takes a list of command line arguments, and returns the
--   given suggestions. 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>
hlint :: [String] -> IO [Suggestion]

-- | A suggestion - the <tt>Show</tt> instance is of particular use.
data Suggestion

-- | From a suggestion, extract the file location it refers to.
suggestionLocation :: Suggestion -> SrcLoc

-- | From a suggestion, determine how severe it is.
suggestionSeverity :: Suggestion -> Severity

-- | 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.
Error :: Severity
instance GHC.Classes.Ord Language.Haskell.HLint.Suggestion
instance GHC.Classes.Eq Language.Haskell.HLint.Suggestion
instance GHC.Show.Show Language.Haskell.HLint.Suggestion


-- | <i>WARNING: This module represents the evolving second version of the
--   HLint API.</i> <i>It will be renamed to drop the "3" in the next major
--   version.</i>
--   
--   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.HLint3

-- | 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 a 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 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 -> [(Module_, [Comment])] -> [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 module the idea applies to, may be <tt>""</tt> if the module
--   cannot be determined or is a result of cross-module hints.
[ideaModule] :: Idea -> String

-- | The declaration the idea applies to, 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.
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

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

-- | 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 containg <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 <a>resolveHints</a> 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 ([Fixity], [Classify], [Either HintBuiltin HintRule])

-- | 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)

-- | A list of the builtin hints wired into HLint. This list is likely to
--   grow over time.
data HintBuiltin
HintList :: HintBuiltin
HintListRec :: HintBuiltin
HintMonad :: HintBuiltin
HintLambda :: HintBuiltin
HintBracket :: HintBuiltin
HintNaming :: HintBuiltin
HintPattern :: HintBuiltin
HintImport :: HintBuiltin
HintExport :: HintBuiltin
HintPragma :: HintBuiltin
HintExtensions :: HintBuiltin
HintUnsafe :: HintBuiltin
HintDuplicate :: HintBuiltin
HintRestrict :: HintBuiltin
HintComment :: HintBuiltin
HintNewType :: HintBuiltin

-- | A <tt>LHS ==&gt; RHS</tt> style hint rule.
data HintRule
HintRule :: Severity -> String -> Scope -> Exp_ -> Exp_ -> Maybe Exp_ -> [Note] -> HintRule

-- | Default severity for the hint.
[hintRuleSeverity] :: HintRule -> Severity

-- | Name for the hint.
[hintRuleName] :: HintRule -> String

-- | Module scope in which the hint operates.
[hintRuleScope] :: HintRule -> Scope

-- | LHS
[hintRuleLHS] :: HintRule -> Exp_

-- | RHS
[hintRuleRHS] :: HintRule -> Exp_

-- | Side condition, typically specified with <tt>where _ = ...</tt>.
[hintRuleSide] :: HintRule -> Maybe Exp_

-- | Notes about application of the hint.
[hintRuleNotes] :: HintRule -> [Note]

-- | Functions to generate hints, combined using the <a>Monoid</a>
--   instance.
data Hint
Hint :: ([Setting] -> [(Scope, Module_)] -> [Idea]) -> ([Setting] -> Scope -> Module_ -> [Idea]) -> ([Setting] -> Scope -> Module_ -> Decl_ -> [Idea]) -> ([Setting] -> Comment -> [Idea]) -> Hint

-- | Given a list of modules (and their scope information) generate some
--   <a>Idea</a>s.
[hintModules] :: Hint -> [Setting] -> [(Scope, Module_)] -> [Idea]

-- | Given a single module and its scope information generate some
--   <a>Idea</a>s.
[hintModule] :: Hint -> [Setting] -> Scope -> Module_ -> [Idea]

-- | Given a declaration (with a module and scope) generate some
--   <a>Idea</a>s. This function will be partially applied with one
--   module/scope, then used on multiple <a>Decl</a> values.
[hintDecl] :: Hint -> [Setting] -> Scope -> Module_ -> Decl_ -> [Idea]

-- | Given a comment generate some <a>Idea</a>s.
[hintComment] :: Hint -> [Setting] -> Comment -> [Idea]

-- | Transform a list of <a>HintBuiltin</a> or <a>HintRule</a> into a
--   <a>Hint</a>.
resolveHints :: [Either HintBuiltin HintRule] -> Hint

-- | Data type representing the modules in scope within a module. Created
--   with <a>scopeCreate</a> and queried with <a>scopeMatch</a> and
--   <a>scopeMove</a>. Note that the <a>mempty</a> <a>Scope</a> is not
--   equivalent to <a>scopeCreate</a> on an empty module, due to the
--   implicit import of <tt>Prelude</tt>.
data Scope

-- | Create a <a>Scope</a> value from a module, based on the modules
--   imports.
scopeCreate :: Module_ -> Scope

-- | Given a two names in scopes, could they possibly refer to the same
--   thing. This property is reflexive.
scopeMatch :: (Scope, QName S) -> (Scope, QName S) -> Bool

-- | Given a name in a scope, and a new scope, create a name for the new
--   scope that will refer to the same thing. If the resulting name is
--   ambiguous, it picks a plausible candidate.
scopeMove :: (Scope, QName S) -> Scope -> QName S

-- | 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.
parseModuleEx :: ParseFlags -> FilePath -> Maybe String -> IO (Either ParseError (Module_, [Comment]))

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

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

-- | A parse error from <a>parseModuleEx</a>.
data ParseError
ParseError :: SrcLoc -> String -> String -> ParseError

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

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

-- | Created with <a>defaultParseFlags</a>, used by <a>parseModuleEx</a>.
data ParseFlags
ParseFlags :: CppFlags -> ParseMode -> ParseFlags

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

-- | How the file is parsed (defaults to all fixities in the <tt>base</tt>
--   package and most non-conflicting extensions).
[hseFlags] :: ParseFlags -> ParseMode

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

-- | No pre processing is done.
NoCpp :: CppFlags

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

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