Language.Haskell.GhcMod

ghc-mod-5.6.0.0: Happy Haskell Programming

Safe Haskell | None
Language | Haskell2010

Language.Haskell.GhcMod

Contents

- Cradle
- Options
- Logging
- Types
- Monad Types
- Monad utilities
- `GhcMod` utilities
- SymbolDb
- Output
- FileMapping

Description

The ghc-mod library.

Synopsis

- data Cradle = Cradle {
  - cradleProject :: Project
  - cradleCurrentDir :: FilePath
  - cradleRootDir :: FilePath
  - cradleTempDir :: FilePath
  - cradleCabalFile :: Maybe FilePath
  - cradleDistDir :: FilePath
  }
- data Project
  - = CabalProject
  - | SandboxProject
  - | PlainProject
  - | StackProject StackEnv
- findCradle :: (GmLog m, IOish m, GmOut m) => Programs -> m Cradle
- data Options = Options {
  - optOutput :: OutputOpts
  - optPrograms :: Programs
  - optGhcUserOptions :: [GHCOption]
  - optFileMappings :: [(FilePath, Maybe FilePath)]
  - optEncoding :: String
  }
- newtype LineSeparator = LineSeparator String
- data OutputStyle
  - = LispStyle
  - | PlainStyle
- data FileMapping = FileMapping {
  - fmPath :: FilePath
  - fmTemp :: Bool
  }
- defaultOptions :: Options
- data GmLogLevel
- increaseLogLevel :: GmLogLevel -> GmLogLevel
- decreaseLogLevel :: GmLogLevel -> GmLogLevel
- gmSetLogLevel :: GmLog m => GmLogLevel -> m ()
- gmLog :: (MonadIO m, GmLog m, GmOut m) => GmLogLevel -> String -> Doc -> m ()
- data ModuleString
- newtype Expression = Expression {
  - getExpression :: String
  }
- data GhcPkgDb
- type Symbol = ByteString
- data SymbolDb
- data GhcModError
  - = GMENoMsg
  - | GMEString String
  - | GMECabalConfigure GhcModError
  - | GMEStackConfigure GhcModError
  - | GMEStackBootstrap GhcModError
  - | GMECabalCompAssignment [(Either FilePath ModuleName, Set ChComponentName)]
  - | GMEProcess String String [String] (Either Int GhcModError)
  - | GMENoCabalFile
  - | GMETooManyCabalFiles [FilePath]
- type GhcModT m = GmT (GmOutT m)
- type IOish m = (Functor m, MonadIO m, MonadBaseControl IO m, ExceptionMonad m)
- runGhcModT :: IOish m => Options -> GhcModT m a -> m (Either GhcModError a, GhcModLog)
- withOptions :: GmEnv m => (Options -> Options) -> m a -> m a
- dropSession :: IOish m => GhcModT m ()
- boot :: IOish m => GhcModT m String
- browse :: forall m. IOish m => BrowseOpts -> String -> GhcModT m String
- check :: IOish m => [FilePath] -> GhcModT m (Either String String)
- checkSyntax :: IOish m => [FilePath] -> GhcModT m String
- debugInfo :: IOish m => GhcModT m String
- componentInfo :: IOish m => [String] -> GhcModT m String
- expandTemplate :: IOish m => [FilePath] -> GhcModT m String
- info :: IOish m => FilePath -> Expression -> GhcModT m String
- lint :: IOish m => LintOpts -> FilePath -> GhcModT m String
- pkgDoc :: IOish m => String -> GhcModT m String
- rootInfo :: forall m. (IOish m, GmOut m, GmEnv m) => m String
- types :: IOish m => Bool -> FilePath -> Int -> Int -> GhcModT m String
- test :: IOish m => FilePath -> GhcModT m String
- splits :: IOish m => FilePath -> Int -> Int -> GhcModT m String
- sig :: IOish m => FilePath -> Int -> Int -> GhcModT m String
- refine :: IOish m => FilePath -> Int -> Int -> Expression -> GhcModT m String
- auto :: IOish m => FilePath -> Int -> Int -> GhcModT m String
- modules :: (IOish m, Gm m) => Bool -> m String
- languages :: IOish m => GhcModT m String
- flags :: IOish m => GhcModT m String
- findSymbol :: IOish m => String -> GhcModT m String
- lookupSymbol :: IOish m => String -> SymbolDb -> GhcModT m String
- dumpSymbol :: IOish m => GhcModT m ()
- loadSymbolDb :: IOish m => GhcModT m SymbolDb
- isOutdated :: IOish m => SymbolDb -> GhcModT m Bool
- gmPutStr :: (MonadIO m, GmOut m) => String -> m ()
- gmErrStr :: (MonadIO m, GmOut m) => String -> m ()
- gmPutStrLn :: (MonadIO m, GmOut m) => String -> m ()
- gmErrStrLn :: (MonadIO m, GmOut m) => String -> m ()
- loadMappedFile :: IOish m => FilePath -> FilePath -> GhcModT m ()
- loadMappedFileSource :: IOish m => FilePath -> String -> GhcModT m ()
- unloadMappedFile :: IOish m => FilePath -> GhcModT m ()

# Cradle

data Cradle #

The environment where this library is used.

Constructors

Cradle |
Fields cradleProject :: Project cradleCurrentDir :: FilePath The directory where this library is executed. cradleRootDir :: FilePath The project root directory. cradleTempDir :: FilePath Per-Project temporary directory cradleCabalFile :: Maybe FilePath The file name of the found cabal file. cradleDistDir :: FilePath The build info directory.

Instances

Eq Cradle # |
Methods (==) :: Cradle -> Cradle -> Bool # (/=) :: Cradle -> Cradle -> Bool #
Ord Cradle # |
Methods compare :: Cradle -> Cradle -> Ordering # (<) :: Cradle -> Cradle -> Bool # (<=) :: Cradle -> Cradle -> Bool # (>) :: Cradle -> Cradle -> Bool # (>=) :: Cradle -> Cradle -> Bool # max :: Cradle -> Cradle -> Cradle # min :: Cradle -> Cradle -> Cradle #
Show Cradle # |
Methods showsPrec :: Int -> Cradle -> ShowS # show :: Cradle -> String # showList :: [Cradle] -> ShowS #

data Project #

Constructors

CabalProject |
SandboxProject |
PlainProject |
StackProject StackEnv |

Instances

Eq Project # |
Methods (==) :: Project -> Project -> Bool # (/=) :: Project -> Project -> Bool #
Ord Project # |
Methods compare :: Project -> Project -> Ordering # (<) :: Project -> Project -> Bool # (<=) :: Project -> Project -> Bool # (>) :: Project -> Project -> Bool # (>=) :: Project -> Project -> Bool # max :: Project -> Project -> Project # min :: Project -> Project -> Project #
Show Project # |
Methods showsPrec :: Int -> Project -> ShowS # show :: Project -> String # showList :: [Project] -> ShowS #

findCradle :: (GmLog m, IOish m, GmOut m) => Programs -> m Cradle #

Finding `Cradle`. Find a cabal file by tracing ancestor directories. Find a sandbox according to a cabal sandbox config in a cabal directory.

# Options

data Options #

Constructors

Options |
Fields optOutput :: OutputOpts optPrograms :: Programs optGhcUserOptions :: [GHCOption] GHC command line options set on the `ghc-mod` command line optFileMappings :: [(FilePath, Maybe FilePath)] optEncoding :: String

Instances

Show Options # |
Methods showsPrec :: Int -> Options -> ShowS # show :: Options -> String # showList :: [Options] -> ShowS #

newtype LineSeparator #

The type for line separator. Historically, a Null string is used.

Constructors

LineSeparator String |

Instances

Show LineSeparator # |
Methods showsPrec :: Int -> LineSeparator -> ShowS # show :: LineSeparator -> String # showList :: [LineSeparator] -> ShowS #

data OutputStyle #

Output style.

Constructors

LispStyle | S expression style.
PlainStyle | Plain textstyle.

Instances

Show OutputStyle # |
Methods showsPrec :: Int -> OutputStyle -> ShowS # show :: OutputStyle -> String # showList :: [OutputStyle] -> ShowS #

data FileMapping #

Constructors

FileMapping |
Fields fmPath :: FilePath fmTemp :: Bool

Instances

Eq FileMapping # |
Methods (==) :: FileMapping -> FileMapping -> Bool # (/=) :: FileMapping -> FileMapping -> Bool #
Show FileMapping # |
Methods showsPrec :: Int -> FileMapping -> ShowS # show :: FileMapping -> String # showList :: [FileMapping] -> ShowS #

defaultOptions :: Options #

A default `Options`.

# Logging

data GmLogLevel #

Instances

Bounded GmLogLevel # |
Methods minBound :: GmLogLevel # maxBound :: GmLogLevel #
Enum GmLogLevel # |
Methods succ :: GmLogLevel -> GmLogLevel # pred :: GmLogLevel -> GmLogLevel # toEnum :: Int -> GmLogLevel # fromEnum :: GmLogLevel -> Int # enumFrom :: GmLogLevel -> [GmLogLevel] # enumFromThen :: GmLogLevel -> GmLogLevel -> [GmLogLevel] # enumFromTo :: GmLogLevel -> GmLogLevel -> [GmLogLevel] # enumFromThenTo :: GmLogLevel -> GmLogLevel -> GmLogLevel -> [GmLogLevel] #
Eq GmLogLevel # |
Methods (==) :: GmLogLevel -> GmLogLevel -> Bool # (/=) :: GmLogLevel -> GmLogLevel -> Bool #
Ord GmLogLevel # |
Methods compare :: GmLogLevel -> GmLogLevel -> Ordering # (<) :: GmLogLevel -> GmLogLevel -> Bool # (<=) :: GmLogLevel -> GmLogLevel -> Bool # (>) :: GmLogLevel -> GmLogLevel -> Bool # (>=) :: GmLogLevel -> GmLogLevel -> Bool # max :: GmLogLevel -> GmLogLevel -> GmLogLevel # min :: GmLogLevel -> GmLogLevel -> GmLogLevel #
Read GmLogLevel # |
Methods readsPrec :: Int -> ReadS GmLogLevel # readList :: ReadS [GmLogLevel] # readPrec :: ReadPrec GmLogLevel # readListPrec :: ReadPrec [GmLogLevel] #
Show GmLogLevel # |
Methods showsPrec :: Int -> GmLogLevel -> ShowS # show :: GmLogLevel -> String # showList :: [GmLogLevel] -> ShowS #

increaseLogLevel :: GmLogLevel -> GmLogLevel #

decreaseLogLevel :: GmLogLevel -> GmLogLevel #

gmSetLogLevel :: GmLog m => GmLogLevel -> m () #

gmLog :: (MonadIO m, GmLog m, GmOut m) => GmLogLevel -> String -> Doc -> m () #

    >>> Just GmDebug <= Nothing
    False
    >>> Just GmException <= Just GmDebug
    True
    >>> Just GmDebug <= Just GmException
    False

# Types

data ModuleString #

Module name.

Instances

Eq ModuleString # |
Methods (==) :: ModuleString -> ModuleString -> Bool # (/=) :: ModuleString -> ModuleString -> Bool #
Ord ModuleString # |
Methods compare :: ModuleString -> ModuleString -> Ordering # (<) :: ModuleString -> ModuleString -> Bool # (<=) :: ModuleString -> ModuleString -> Bool # (>) :: ModuleString -> ModuleString -> Bool # (>=) :: ModuleString -> ModuleString -> Bool # max :: ModuleString -> ModuleString -> ModuleString # min :: ModuleString -> ModuleString -> ModuleString #
Show ModuleString # |
Methods showsPrec :: Int -> ModuleString -> ShowS # show :: ModuleString -> String # showList :: [ModuleString] -> ShowS #
Binary ModuleString # |
Methods put :: ModuleString -> Put # get :: Get ModuleString # putList :: [ModuleString] -> Put #
NFData ModuleString # |
Methods rnf :: ModuleString -> () #

newtype Expression #

Haskell expression.

Constructors

Expression |
Fields getExpression :: String

Instances

Eq Expression # |
Methods (==) :: Expression -> Expression -> Bool # (/=) :: Expression -> Expression -> Bool #
Ord Expression # |
Methods compare :: Expression -> Expression -> Ordering # (<) :: Expression -> Expression -> Bool # (<=) :: Expression -> Expression -> Bool # (>) :: Expression -> Expression -> Bool # (>=) :: Expression -> Expression -> Bool # max :: Expression -> Expression -> Expression # min :: Expression -> Expression -> Expression #
Show Expression # |
Methods showsPrec :: Int -> Expression -> ShowS # show :: Expression -> String # showList :: [Expression] -> ShowS #

data GhcPkgDb #

GHC package database flags.

Instances

Eq GhcPkgDb # |
Methods (==) :: GhcPkgDb -> GhcPkgDb -> Bool # (/=) :: GhcPkgDb -> GhcPkgDb -> Bool #
Show GhcPkgDb # |
Methods showsPrec :: Int -> GhcPkgDb -> ShowS # show :: GhcPkgDb -> String # showList :: [GhcPkgDb] -> ShowS #
Generic GhcPkgDb # |
Associated Types type Rep GhcPkgDb :: * -> * # Methods from :: GhcPkgDb -> Rep GhcPkgDb x # to :: Rep GhcPkgDb x -> GhcPkgDb #
Binary GhcPkgDb # |
Methods put :: GhcPkgDb -> Put # get :: Get GhcPkgDb # putList :: [GhcPkgDb] -> Put #
type Rep GhcPkgDb # |
type Rep GhcPkgDb = D1 (MetaData "GhcPkgDb" "Language.Haskell.GhcMod.Types" "ghc-mod-5.6.0.0-3hnVvvX6z805aFKL1S2QmL" False) ((:+:) (C1 (MetaCons "GlobalDb" PrefixI False) U1) ((:+:) (C1 (MetaCons "UserDb" PrefixI False) U1) (C1 (MetaCons "PackageDb" PrefixI False) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String)))))

type Symbol = ByteString #

Type of function and operation names.

data SymbolDb #

Database from `Symbol` to \['ModuleString'\].

Instances

Generic SymbolDb # |
Associated Types type Rep SymbolDb :: * -> * # Methods from :: SymbolDb -> Rep SymbolDb x # to :: Rep SymbolDb x -> SymbolDb #
Binary SymbolDb # |
Methods put :: SymbolDb -> Put # get :: Get SymbolDb # putList :: [SymbolDb] -> Put #
NFData SymbolDb # |
Methods rnf :: SymbolDb -> () #
type Rep SymbolDb # |
type Rep SymbolDb

data GhcModError #

Constructors

GMENoMsg | Unknown error
GMEString String | Some Error with a message. These are produced mostly by `fail` calls on GhcModT.
GMECabalConfigure GhcModError | Configuring a cabal project failed.
GMEStackConfigure GhcModError | Configuring a stack project failed.
GMEStackBootstrap GhcModError | Bootstrapping `stack` environment failed (process exited with failure)
GMECabalCompAssignment [(Either FilePath ModuleName, Set ChComponentName)] | Could not find a consistent component assignment for modules
GMEProcess String String [String] (Either Int GhcModError) | Launching an operating system process failed. Fields in order: function, command, arguments, (stdout, stderr, exitcode)
GMENoCabalFile | No cabal file found.
GMETooManyCabalFiles [FilePath] | Too many cabal files found.

Instances

Eq GhcModError # |
Methods (==) :: GhcModError -> GhcModError -> Bool # (/=) :: GhcModError -> GhcModError -> Bool #
Show GhcModError # |
Methods showsPrec :: Int -> GhcModError -> ShowS # show :: GhcModError -> String # showList :: [GhcModError] -> ShowS #
Exception GhcModError # |
Methods toException :: GhcModError -> SomeException # fromException :: SomeException -> Maybe GhcModError # displayException :: GhcModError -> String #
Error GhcModError # |
Methods noMsg :: GhcModError # strMsg :: String -> GhcModError #
Monad m => MonadError GhcModError (GmlT m) # |
Methods throwError :: GhcModError -> GmlT m a # catchError :: GmlT m a -> (GhcModError -> GmlT m a) -> GmlT m a #
Monad m => MonadError GhcModError (GmT m) # |
Methods throwError :: GhcModError -> GmT m a # catchError :: GmT m a -> (GhcModError -> GmT m a) -> GmT m a #
GmEnv m => GmEnv (ErrorT GhcModError m) # |
Methods gmeAsk :: ErrorT GhcModError m GhcModEnv # gmeReader :: (GhcModEnv -> a) -> ErrorT GhcModError m a # gmeLocal :: (GhcModEnv -> GhcModEnv) -> ErrorT GhcModError m a -> ErrorT GhcModError m a #

# Monad Types

type GhcModT m = GmT (GmOutT m) #

type IOish m = (Functor m, MonadIO m, MonadBaseControl IO m, ExceptionMonad m) #

A constraint alias (-XConstraintKinds) to make functions dealing with `GhcModT` somewhat cleaner.

Basicially an `IOish m => m` is a `Monad` supporting arbitrary `IO` and exception handling. Usually this will simply be `IO` but we parametrise it in the exported API so users have the option to use a custom inner monad.

# Monad utilities

runGhcModT :: IOish m => Options -> GhcModT m a -> m (Either GhcModError a, GhcModLog) #

Run a `GhcModT m` computation.

withOptions :: GmEnv m => (Options -> Options) -> m a -> m a #

dropSession :: IOish m => GhcModT m () #

Drop the currently active GHC session, the next that requires a GHC session will initialize a new one.

# `GhcMod` utilities

boot :: IOish m => GhcModT m String #

Printing necessary information for front-end booting.

browse #

Arguments

:: IOish m |
=> BrowseOpts | Configuration parameters
-> String | A module name. (e.g. "Data.List", "base:Prelude")
-> GhcModT m String |

Getting functions, classes, etc from a module.

check #

Arguments

:: IOish m |
=> [FilePath] | The target files.
-> GhcModT m (Either String String) |

Checking syntax of a target file using GHC. Warnings and errors are returned.

checkSyntax #

Arguments

:: IOish m |
=> [FilePath] | The target files.
-> GhcModT m String |

Checking syntax of a target file using GHC. Warnings and errors are returned.

debugInfo :: IOish m => GhcModT m String #

Obtaining debug information.

componentInfo :: IOish m => [String] -> GhcModT m String #

expandTemplate #

Arguments

:: IOish m |
=> [FilePath] | The target files.
-> GhcModT m String |

Expanding Haskell Template.

info #

Arguments

:: IOish m |
=> FilePath | A target file.
-> Expression | A Haskell expression.
-> GhcModT m String |

Obtaining information of a target expression. (GHCi's info:)

lint #

Arguments

:: IOish m |
=> LintOpts | Configuration parameters
-> FilePath | A target file.
-> GhcModT m String |

Checking syntax of a target file using hlint. Warnings and errors are returned.

pkgDoc :: IOish m => String -> GhcModT m String #

Obtaining the package name and the doc path of a module.

rootInfo :: forall m. (IOish m, GmOut m, GmEnv m) => m String #

Obtaining root information.

types #

Arguments

:: IOish m |
=> Bool | Include constraints into type signature
-> FilePath | A target file.
-> Int | Line number.
-> Int | Column number.
-> GhcModT m String |

Obtaining type of a target expression. (GHCi's type:)

test :: IOish m => FilePath -> GhcModT m String #

splits #

Arguments

:: IOish m |
=> FilePath | A target file.
-> Int | Line number.
-> Int | Column number.
-> GhcModT m String |

Splitting a variable in a equation.

sig #

Arguments

:: IOish m |
=> FilePath | A target file.
-> Int | Line number.
-> Int | Column number.
-> GhcModT m String |

Create a initial body from a signature.

refine #

Arguments

:: IOish m |
=> FilePath | A target file.
-> Int | Line number.
-> Int | Column number.
-> Expression | A Haskell expression.
-> GhcModT m String |

auto #

Arguments

:: IOish m |
=> FilePath | A target file.
-> Int | Line number.
-> Int | Column number.
-> GhcModT m String |

modules #

Arguments

:: (IOish m, Gm m) |
=> Bool | `detailed`, if `True`, also prints packages that modules belong to.
-> m String |

Listing installed modules.

languages :: IOish m => GhcModT m String #

Listing language extensions.

flags :: IOish m => GhcModT m String #

Listing of GHC flags, same as `ghc`'s `--show-options` with `ghc >= 7.10`.

findSymbol :: IOish m => String -> GhcModT m String #

Looking up `SymbolDb` with `Symbol` to \['ModuleString'\] which will be concatenated. `loadSymbolDb` is called internally.

lookupSymbol :: IOish m => String -> SymbolDb -> GhcModT m String #

Looking up `SymbolDb` with `Symbol` to \['ModuleString'\] which will be concatenated.

dumpSymbol :: IOish m => GhcModT m () #

Dumps a `Binary` representation of `SymbolDb` to stdout

# SymbolDb

loadSymbolDb :: IOish m => GhcModT m SymbolDb #

Loading a file and creates `SymbolDb`.

isOutdated :: IOish m => SymbolDb -> GhcModT m Bool #

# Output

gmPutStr :: (MonadIO m, GmOut m) => String -> m () #

gmErrStr :: (MonadIO m, GmOut m) => String -> m () #

gmPutStrLn :: (MonadIO m, GmOut m) => String -> m () #

gmErrStrLn :: (MonadIO m, GmOut m) => String -> m () #

# FileMapping

loadMappedFile #

Arguments

:: IOish m |
=> FilePath | 'from', file that will be mapped
-> FilePath | 'to', file to take source from
-> GhcModT m () |

maps `FilePath`, given as first argument to take source from `FilePath` given as second argument. Works exactly the same as first form of `--map-file` CLI option.

'from' can be either full path, or path relative to project root. 'to' has to be either relative to project root, or full path (preferred)

loadMappedFileSource #

Arguments

:: IOish m |
=> FilePath | 'from', file that will be mapped
-> String | 'src', source
-> GhcModT m () |

maps `FilePath`, given as first argument to have source as given by second argument.

'from' may or may not exist, and should be either full path, or relative to project root.

unloadMappedFile #

Arguments

:: IOish m |
=> FilePath | 'file', file to unmap
-> GhcModT m () |

unloads previously mapped file 'file', so that it's no longer mapped, and removes any temporary files created when file was mapped.

'file' should be either full path, or relative to project root.