ghc-lib-parser-9.14.1.20251220: The GHC API, decoupled from GHC versions

Safe Haskell | Ignore
Language | GHC2021

GHC.Utils.Logger

Contents

- Logger setup
  - Hooks
  - Flags
- Logging
- Dumping
- Tracing

Description

Logger

The Logger is an configurable entity that is used by the compiler to output messages on the console (stdout, stderr) and in dump files.

The behaviour of default Logger returned by `initLogger` can be modified with hooks. The compiler itself uses hooks in multithreaded code (--make) and it is also probably used by ghc-api users (IDEs, etc.).

In addition to hooks, the Logger supports LogFlags: basically a subset of the command-line flags that control the logger behaviour at a higher level than hooks.

1. Hooks are used to define how to generate a infowarningerror/dump messages
2. LogFlags are used to decide when and how to generate messages

Synopsis

- data Logger
- class HasLogger (m :: Type -> Type) where
  - getLogger :: m Logger
- class ContainsLogger t where
  - extractLogger :: t -> Logger
- initLogger :: IO Logger
- type LogAction = LogFlags -> MessageClass -> SrcSpan -> SDoc -> IO ()
- type LogJsonAction = LogFlags -> MessageClass -> JsonDoc -> IO ()
- type DumpAction = LogFlags -> PprStyle -> DumpFlag -> String -> DumpFormat -> SDoc -> IO ()
- type TraceAction a = LogFlags -> String -> SDoc -> a -> a
- data DumpFormat
  - = FormatHaskell
  - | FormatCore
  - | FormatSTG
  - | FormatByteCode
  - | FormatCMM
  - | FormatASM
  - | FormatC
  - | FormatLLVM
  - | FormatJS
  - | FormatText
- popLogHook :: Logger -> Logger
- pushLogHook :: (LogAction -> LogAction) -> Logger -> Logger
- popJsonLogHook :: Logger -> Logger
- pushJsonLogHook :: (LogJsonAction -> LogJsonAction) -> Logger -> Logger
- popDumpHook :: Logger -> Logger
- pushDumpHook :: (DumpAction -> DumpAction) -> Logger -> Logger
- popTraceHook :: Logger -> Logger
- pushTraceHook :: (forall a. TraceAction a -> TraceAction a) -> Logger -> Logger
- makeThreadSafe :: Logger -> IO Logger
- data LogFlags = LogFlags {
  - log_default_user_context :: SDocContext
  - log_default_dump_context :: SDocContext
  - log_dump_flags :: !(EnumSet DumpFlag)
  - log_show_caret :: !Bool
  - log_diagnostics_as_json :: !Bool
  - log_show_warn_groups :: !Bool
  - log_enable_timestamps :: !Bool
  - log_dump_to_file :: !Bool
  - log_dump_dir :: !(Maybe FilePath)
  - log_dump_prefix :: !FilePath
  - log_dump_prefix_override :: !(Maybe FilePath)
  - log_with_ways :: !Bool
  - log_enable_debug :: !Bool
  - log_verbosity :: !Int
  - log_ways :: !(Maybe Ways)
  }
- defaultLogFlags :: LogFlags
- log_dopt :: DumpFlag -> LogFlags -> Bool
- log_set_dopt :: DumpFlag -> LogFlags -> LogFlags
- setLogFlags :: Logger -> LogFlags -> Logger
- updateLogFlags :: Logger -> (LogFlags -> LogFlags) -> Logger
- logFlags :: Logger -> LogFlags
- logHasDumpFlag :: Logger -> DumpFlag -> Bool
- logVerbAtLeast :: Logger -> Int -> Bool
- putLogMsg :: Logger -> LogAction
- defaultLogAction :: LogAction
- defaultLogActionWithHandles :: Handle -> Handle -> LogAction
- defaultLogJsonAction :: LogJsonAction
- defaultLogActionHPrintDoc :: LogFlags -> Bool -> Handle -> SDoc -> IO ()
- defaultLogActionHPutStrDoc :: LogFlags -> Bool -> Handle -> SDoc -> IO ()
- logMsg :: Logger -> MessageClass -> SrcSpan -> SDoc -> IO ()
- logJsonMsg :: ToJson a => Logger -> MessageClass -> a -> IO ()
- logDumpMsg :: Logger -> String -> SDoc -> IO ()
- defaultDumpAction :: DumpCache -> LogAction -> DumpAction
- putDumpFile :: Logger -> DumpAction
- putDumpFileMaybe :: Logger -> DumpFlag -> String -> DumpFormat -> SDoc -> IO ()
- putDumpFileMaybe' :: Logger -> NamePprCtx -> DumpFlag -> String -> DumpFormat -> SDoc -> IO ()
- withDumpFileHandle :: DumpCache -> LogFlags -> DumpFlag -> (Maybe Handle -> IO ()) -> IO ()
- touchDumpFile :: Logger -> DumpFlag -> IO ()
- logDumpFile :: Logger -> PprStyle -> DumpFlag -> String -> DumpFormat -> SDoc -> IO ()
- defaultTraceAction :: TraceAction a
- putTraceMsg :: Logger -> TraceAction a
- loggerTraceFlushUpdate :: Logger -> (IO () -> IO ()) -> Logger
- loggerTraceFlush :: Logger -> IO ()
- logTraceMsg :: Logger -> String -> SDoc -> a -> a

# Documentation

data Logger #

class HasLogger (m :: Type -> Type) where #

Methods

getLogger :: m Logger #

#### Instances

Instances details

HasLogger CoreM # |
Instance details Defined in GHC.Core.Opt.Monad Methods getLogger :: CoreM Logger #
HasLogger SimplM # |
Instance details Defined in GHC.Core.Opt.Simplify.Monad Methods getLogger :: SimplM Logger #
HasLogger Hsc # |
Instance details Defined in GHC.Driver.Env.Types Methods getLogger :: Hsc Logger #
HasLogger Ghc # |
Instance details Defined in GHC.Driver.Monad Methods getLogger :: Ghc Logger #
ContainsLogger env => HasLogger (IOEnv env) # |
Instance details Defined in GHC.Data.IOEnv Methods getLogger :: IOEnv env Logger #
MonadIO m => HasLogger (GhcT m) # |
Instance details Defined in GHC.Driver.Monad Methods getLogger :: GhcT m Logger #

class ContainsLogger t where #

Methods

extractLogger :: t -> Logger #

#### Instances

Instances details

ContainsLogger (Env gbl lcl) # |
Instance details Defined in GHC.Tc.Types Methods extractLogger :: Env gbl lcl -> Logger #

# Logger setup

initLogger :: IO Logger #

type LogAction = LogFlags -> MessageClass -> SrcSpan -> SDoc -> IO () #

type LogJsonAction = LogFlags -> MessageClass -> JsonDoc -> IO () #

type DumpAction = LogFlags -> PprStyle -> DumpFlag -> String -> DumpFormat -> SDoc -> IO () #

type TraceAction a = LogFlags -> String -> SDoc -> a -> a #

data DumpFormat #

Format of a dump

Dump formats are loosely defined: dumps may contain various additional headers and annotations and they may be partial. `DumpFormat` is mainly a hint (e.g. for syntax highlighters).

Constructors

FormatHaskell | Haskell
FormatCore | Core
FormatSTG | STG
FormatByteCode | ByteCode
FormatCMM | Cmm
FormatASM | Assembly code
FormatC | C code/header
FormatLLVM | LLVM bytecode
FormatJS | JavaScript code
FormatText | Unstructured dump

#### Instances

Instances details

Show DumpFormat # |
Instance details Defined in GHC.Utils.Logger Methods showsPrec :: Int -> DumpFormat -> ShowS # show :: DumpFormat -> String # showList :: [DumpFormat] -> ShowS #
Eq DumpFormat # |
Instance details Defined in GHC.Utils.Logger Methods (==) :: DumpFormat -> DumpFormat -> Bool # (/=) :: DumpFormat -> DumpFormat -> Bool #

## Hooks

popLogHook :: Logger -> Logger #

Pop a log hook

pushLogHook :: (LogAction -> LogAction) -> Logger -> Logger #

Push a log hook

popJsonLogHook :: Logger -> Logger #

pushJsonLogHook :: (LogJsonAction -> LogJsonAction) -> Logger -> Logger #

Push a json log hook

popDumpHook :: Logger -> Logger #

Pop a dump hook

pushDumpHook :: (DumpAction -> DumpAction) -> Logger -> Logger #

Push a dump hook

popTraceHook :: Logger -> Logger #

Pop a trace hook

pushTraceHook :: (forall a. TraceAction a -> TraceAction a) -> Logger -> Logger #

Push a trace hook

makeThreadSafe :: Logger -> IO Logger #

Make the logger thread-safe

## Flags

data LogFlags #

Logger flags

Constructors

LogFlags |
Fields log_default_user_context :: SDocContext log_default_dump_context :: SDocContext log_dump_flags :: !(EnumSet DumpFlag) Dump flags log_show_caret :: !Bool Show caret in diagnostics log_diagnostics_as_json :: !Bool Format diagnostics as JSON log_show_warn_groups :: !Bool Show warning flag groups log_enable_timestamps :: !Bool Enable timestamps log_dump_to_file :: !Bool Enable dump to file log_dump_dir :: !(Maybe FilePath) Dump directory log_dump_prefix :: !FilePath Normal dump path ("basename.") log_dump_prefix_override :: !(Maybe FilePath) Overriden dump path log_with_ways :: !Bool Use different dump files names for different ways log_enable_debug :: !Bool Enable debug output log_verbosity :: !Int Verbosity level log_ways :: !(Maybe Ways) Current ways (to name dump files)

defaultLogFlags :: LogFlags #

Default LogFlags

log_dopt :: DumpFlag -> LogFlags -> Bool #

Test if a DumpFlag is enabled

log_set_dopt :: DumpFlag -> LogFlags -> LogFlags #

Enable a DumpFlag

setLogFlags :: Logger -> LogFlags -> Logger #

Set LogFlags

updateLogFlags :: Logger -> (LogFlags -> LogFlags) -> Logger #

Update LogFlags

logFlags :: Logger -> LogFlags #

Logger flags

logHasDumpFlag :: Logger -> DumpFlag -> Bool #

Test if a DumpFlag is set

logVerbAtLeast :: Logger -> Int -> Bool #

Test if verbosity is >= to the given value

# Logging

putLogMsg :: Logger -> LogAction #

Log something

defaultLogAction :: LogAction #

The default `LogAction` prints to `stdout` and `stderr`.

To replicate the default log action behaviour with different `out` and `err` handles, see `defaultLogActionWithHandles`.

defaultLogActionWithHandles #

Arguments

:: Handle | Handle for standard output
-> Handle | Handle for standard errors
-> LogAction |

The default `LogAction` parametrized over the standard output and standard error handles. Allows clients to replicate the log message formatting of GHC with custom handles.

defaultLogJsonAction :: LogJsonAction #

defaultLogActionHPrintDoc :: LogFlags -> Bool -> Handle -> SDoc -> IO () #

Like `defaultLogActionHPutStrDoc` but appends an extra newline.

defaultLogActionHPutStrDoc :: LogFlags -> Bool -> Handle -> SDoc -> IO () #

The boolean arguments let's the pretty printer know if it can optimize indent by writing ascii ' ' characters without going through decoding.

logMsg :: Logger -> MessageClass -> SrcSpan -> SDoc -> IO () #

Log something

logJsonMsg :: ToJson a => Logger -> MessageClass -> a -> IO () #

logDumpMsg :: Logger -> String -> SDoc -> IO () #

Log a dump message (not a dump file)

# Dumping

defaultDumpAction :: DumpCache -> LogAction -> DumpAction #

Default action for `dumpAction` hook

putDumpFile :: Logger -> DumpAction #

Dump something

putDumpFileMaybe :: Logger -> DumpFlag -> String -> DumpFormat -> SDoc -> IO () #

Dump if the given DumpFlag is set

putDumpFileMaybe' :: Logger -> NamePprCtx -> DumpFlag -> String -> DumpFormat -> SDoc -> IO () #

Dump if the given DumpFlag is set

Unlike `putDumpFileMaybe`, has a NamePprCtx argument

withDumpFileHandle :: DumpCache -> LogFlags -> DumpFlag -> (Maybe Handle -> IO ()) -> IO () #

Run an action with the handle of a `DumpFlag` if we are outputting to a file, otherwise `Nothing`.

touchDumpFile :: Logger -> DumpFlag -> IO () #

Ensure that a dump file is created even if it stays empty

logDumpFile :: Logger -> PprStyle -> DumpFlag -> String -> DumpFormat -> SDoc -> IO () #

Dump something

# Tracing

defaultTraceAction :: TraceAction a #

Default action for `traceAction` hook

putTraceMsg :: Logger -> TraceAction a #

Trace something

loggerTraceFlushUpdate :: Logger -> (IO () -> IO ()) -> Logger #

Set the trace flushing function

The currently set trace flushing function is passed to the updating function

loggerTraceFlush :: Logger -> IO () #

Calls the trace flushing function

logTraceMsg :: Logger -> String -> SDoc -> a -> a #

Log a trace message