ghc-lib-parser-9.12.2.20250421: 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
- 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 Source #

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

Methods

getLogger :: m Logger Source #

#### Instances

Instances details

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

class ContainsLogger t where Source #

Methods

extractLogger :: t -> Logger Source #

#### Instances

Instances details

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

# Logger setup

initLogger :: IO Logger Source #

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

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

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

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

data DumpFormat Source #

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

## Hooks

popLogHook :: Logger -> Logger Source #

Pop a log hook

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

Push a log hook

popJsonLogHook :: Logger -> Logger Source #

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

Push a json log hook

popDumpHook :: Logger -> Logger Source #

Pop a dump hook

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

Push a dump hook

popTraceHook :: Logger -> Logger Source #

Pop a trace hook

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

Push a trace hook

makeThreadSafe :: Logger -> IO Logger Source #

Make the logger thread-safe

## Flags

data LogFlags Source #

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

Default LogFlags

log_dopt :: DumpFlag -> LogFlags -> Bool Source #

Test if a DumpFlag is enabled

log_set_dopt :: DumpFlag -> LogFlags -> LogFlags Source #

Enable a DumpFlag

setLogFlags :: Logger -> LogFlags -> Logger Source #

Set LogFlags

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

Update LogFlags

logFlags :: Logger -> LogFlags Source #

Logger flags

logHasDumpFlag :: Logger -> DumpFlag -> Bool Source #

Test if a DumpFlag is set

logVerbAtLeast :: Logger -> Int -> Bool Source #

Test if verbosity is >= to the given value

# Logging

putLogMsg :: Logger -> LogAction Source #

Log something

defaultLogAction :: LogAction Source #

defaultLogJsonAction :: LogJsonAction Source #

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

Like `defaultLogActionHPutStrDoc` but appends an extra newline.

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

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 () Source #

Log something

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

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

Log a dump message (not a dump file)

# Dumping

defaultDumpAction :: DumpCache -> LogAction -> DumpAction Source #

Default action for `dumpAction` hook

putDumpFile :: Logger -> DumpAction Source #

Dump something

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

Dump if the given DumpFlag is set

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

Dump if the given DumpFlag is set

Unlike `putDumpFileMaybe`, has a NamePprCtx argument

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

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

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

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

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

Dump something

# Tracing

defaultTraceAction :: TraceAction a Source #

Default action for `traceAction` hook

putTraceMsg :: Logger -> TraceAction a Source #

Trace something

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

Set the trace flushing function

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

loggerTraceFlush :: Logger -> IO () Source #

Calls the trace flushing function

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

Log a trace message