HORIZON HASKELLDocslts/ghc-10.0.x8fef28d2026-11-02Search packagesCtrl K
Theme: |

GHC 10.0.0.20260917 · lts/ghc-10.0.x · 8fef28d · 2026-11-02

Moduleghc-10.0.0.20260917GHC2024

GHC.Utils.Outputable

This module defines classes and functions for pretty-printing. It also exports a number of helpful debugging and other utilities such as trace and panic.

The interface to this module is very similar to the standard Hughes-PJ pretty printing module, except that it exports a number of additional functions that are rarely used, and works over the SDoc type.

Contents
  1. Type classes
  2. Pretty printing combinators
  3. Converting SDoc into strings and outputting it
  4. Controlling the style in which output is printed
Synopsis

Type classes

classclass Outputable a where
Source#

Class designating that some type has an SDoc representation

Methods

Instances924Outputable, …
classclass Outputable a => OutputableBndr a where
Source#

When we print a binder, we often want to print its type too. The OutputableBndr class encapsulates this idea.

Methods

Instances19OutputableBndr, …
classclass OutputableP env a where
Source#

Outputable class with an additional environment value

See Note [The OutputableP class]

Methods

Instances46OutputableP, …
datadata BindingSite
Source#

BindingSite is used to tell the thing that prints binder what language construct is binding the identifier. This can be used to decide how much info to print. Also see Note [Binding-site specific printing] in GHC.Core.Ppr

Constructors

Instances1Eq
  • Eq BindingSiteDefined in ghc-10.0.0.20260917 · GHC.Utils.Outputable
classclass IsOutput doc where
Source#

A superclass for IsLine and IsDoc that provides an identity, empty, as well as access to the shared SDocContext.

See Note [The outputable class hierarchy] for more details.

Methods

Instances3IsOutput
  • IsOutput HDocDefined in ghc-10.0.0.20260917 · GHC.Utils.Outputable
  • IsOutput HLineDefined in ghc-10.0.0.20260917 · GHC.Utils.Outputable
  • IsOutput SDocDefined in ghc-10.0.0.20260917 · GHC.Utils.Outputable
classclass IsOutput doc => IsLine doc where
Source#

A class of types that represent a single logical line of text, with support for horizontal composition.

See Note [HLine versus HDoc] and Note [The outputable class hierarchy] for more details.

Methods

  • char :: Char -> doc
  • text :: String -> doc
  • ftext :: FastString -> doc
  • ztext :: FastZString -> doc
  • (<>) :: doc -> doc -> doc

    Join two docs together horizontally without a gap.

  • (<+>) :: doc -> doc -> doc

    Join two docs together horizontally with a gap between them.

  • sep :: [doc] -> doc

    Separate: is either like hsep or like vcat, depending on what fits.

  • fsep :: [doc] -> doc

    A paragraph-fill combinator. It's much like sep, only it keeps fitting things on one line until it can't fit any more.

  • hcat :: [doc] -> doc

    Concatenate docs horizontally without gaps.

  • hsep :: [doc] -> doc

    Concatenate docs horizontally with a space between each one.

  • dualLine :: SDoc -> HLine -> doc

    Prints as either the given SDoc or the given HLine, depending on which type the result is instantiated to. This should generally be avoided; see Note [dualLine and dualDoc] for details.

Instances2IsLine
  • IsLine HLineDefined in ghc-10.0.0.20260917 · GHC.Utils.Outputable
  • IsLine SDocDefined in ghc-10.0.0.20260917 · GHC.Utils.Outputable
classclass (IsOutput doc, IsLine (Line doc)) => IsDoc doc where
Source#

A class of types that represent a multiline document, with support for vertical composition.

See Note [HLine versus HDoc] and Note [The outputable class hierarchy] for more details.

Associated types

  • type family Line doc

Methods

  • line :: Line doc -> doc
  • ($$) :: doc -> doc -> doc

    Join two docs together vertically. If there is no vertical overlap it "dovetails" the two onto one line.

  • lines_ :: [Line doc] -> doc
  • vcat :: [doc] -> doc

    Concatenate docs vertically with dovetailing.

  • dualDoc :: SDoc -> HDoc -> doc

    Prints as either the given SDoc or the given HDoc, depending on which type the result is instantiated to. This should generally be avoided; see Note [dualLine and dualDoc] for details.

Instances2IsDoc
  • IsDoc HDocDefined in ghc-10.0.0.20260917 · GHC.Utils.Outputable
  • IsDoc SDocDefined in ghc-10.0.0.20260917 · GHC.Utils.Outputable
newtypenewtype HLine
Source#

Represents a single line of output that can be efficiently printed directly to a Handle (actually a BufHandle). See Note [SDoc versus HDoc] and Note [HLine versus HDoc] for more details.

Instances3IsLine, IsOutput, JsRender
  • IsLine HLineDefined in ghc-10.0.0.20260917 · GHC.Utils.Outputable
  • IsOutput HLineDefined in ghc-10.0.0.20260917 · GHC.Utils.Outputable
  • JsRender HLineDefined in ghc-10.0.0.20260917 · GHC.JS.Ppr
newtypenewtype HDoc
Source#

Represents a (possibly empty) sequence of lines that can be efficiently printed directly to a Handle (actually a BufHandle). See Note [SDoc versus HDoc] and Note [HLine versus HDoc] for more details.

Instances3IsDoc, IsOutput, Line
  • IsDoc HDocDefined in ghc-10.0.0.20260917 · GHC.Utils.Outputable
  • IsOutput HDocDefined in ghc-10.0.0.20260917 · GHC.Utils.Outputable
  • type Line HDoc = HLineDefined in ghc-10.0.0.20260917 · GHC.Utils.Outputable

Pretty printing combinators

newtypenewtype SDoc
Source#

Represents a pretty-printable document.

To display an SDoc, use printSDoc, printSDocLn, bufLeftRenderSDoc, or renderWithContext. Avoid calling runSDoc directly as it breaks the abstraction layer.

Instances8IsString, Outputable, IsLine, IsDoc, IsOutput, JsRender, …
  • IsString SDocDefined in ghc-10.0.0.20260917 · GHC.Utils.Outputable
  • Outputable SDocDefined in ghc-10.0.0.20260917 · GHC.Utils.Outputable
  • IsLine SDocDefined in ghc-10.0.0.20260917 · GHC.Utils.Outputable
  • IsDoc SDocDefined in ghc-10.0.0.20260917 · GHC.Utils.Outputable
  • IsOutput SDocDefined in ghc-10.0.0.20260917 · GHC.Utils.Outputable
  • JsRender SDocDefined in ghc-10.0.0.20260917 · GHC.JS.Ppr
  • OutputableP env SDocDefined in ghc-10.0.0.20260917 · GHC.Utils.Outputable
  • type Line SDoc = SDocDefined in ghc-10.0.0.20260917 · GHC.Utils.Outputable
newtypenewtype PDoc a
Source#

Wrapper for types having a Outputable instance when an OutputableP instance is required.

Constructors

Instances1OutputableP
valuepprWithCommas
  1. :: (a -> SDoc)

    The pretty printing function to use

  2. -> [a]

    The things to be pretty printed

  3. -> SDoc

    SDoc where the things have been pretty printed, comma-separated and finally packed into a paragraph.

#
valuepprWithSemis
  1. :: (a -> SDoc)

    The pretty printing function to use

  2. -> [a]

    The things to be pretty printed

  3. -> SDoc

    SDoc where the things have been pretty printed, semicolon-separated and finally packed into a paragraph.

#
valuepprWithBars
  1. :: (a -> SDoc)

    The pretty printing function to use

  2. -> [a]

    The things to be pretty printed

  3. -> SDoc

    SDoc where the things have been pretty printed, bar-separated and finally packed into a paragraph.

#
valuedoublePrec :: Int -> Double -> SDoc
Source#

doublePrec p n shows a floating point number n with p digits of precision after the decimal point.

valuecat :: [SDoc] -> SDoc
Source#

A paragraph-fill combinator. It's much like sep, only it keeps fitting things on one line until it can't fit any more.

valuehang
  1. :: SDoc

    The header

  2. -> Int

    Amount to indent the hung body

  3. -> SDoc

    The hung body, indented and placed below the header

  4. -> SDoc
#
valuepunctuate
  1. :: IsLine doc
  2. => doc

    The punctuation

  3. -> [doc]

    The list that will have punctuation added between every adjacent pair of elements

  4. -> [doc]

    Punctuated list

#
valuepunctuateFinal
  1. :: IsLine doc
  2. => doc

    The interstitial punctuation

  3. -> doc

    The final punctuation

  4. -> [doc]

    The list that will have punctuation added between every adjacent pair of elements

  5. -> [doc]

    Punctuated list

Source#

Punctuate a list, e.g. with commas and dots.

sep $ punctuateFinal comma dot [text "ab", text "cd", text "ef"]
ab, cd, ef.
valuespeakNth :: Int -> SDoc
Source#

Converts an integer to a verbal index:

speakNth 1 = text "first"
speakNth 5 = text "fifth"
speakNth 21 = text "21st"
valuespeakN :: Int -> SDoc
Source#

Converts an integer to a verbal multiplicity:

speakN 0 = text "none"
speakN 5 = text "five"
speakN 10 = text "10"
valuespeakNOf :: Int -> SDoc -> SDoc
Source#

Converts an integer and object description to a statement about the multiplicity of those objects:

speakNOf 0 (text "melon") = text "no melons"
speakNOf 1 (text "melon") = text "one melon"
speakNOf 3 (text "melon") = text "three melons"
valueplural :: [a] -> SDoc
Source#

Determines the pluralisation suffix appropriate for the length of a list:

plural [] = char 's'
plural ["Hello"] = empty
plural ["Hello", "World"] = char 's'
valuesingular :: [a] -> SDoc
Source#

Determines the singular verb suffix appropriate for the length of a list:

singular [] = empty
singular["Hello"] = char 's'
singular ["Hello", "World"] = empty
valueisOrAre :: [a] -> SDoc
Source#

Determines the form of to be appropriate for the length of a list:

isOrAre [] = text "are"
isOrAre ["Hello"] = text "is"
isOrAre ["Hello", "World"] = text "are"
valuedoOrDoes :: [a] -> SDoc
Source#

Determines the form of to do appropriate for the length of a list:

doOrDoes [] = text "do"
doOrDoes ["Hello"] = text "does"
doOrDoes ["Hello", "World"] = text "do"
valueitsOrTheir :: [a] -> SDoc
Source#

Determines the form of possessive appropriate for the length of a list:

itsOrTheir [x]   = text "its"
itsOrTheir [x,y] = text "their"
itsOrTheir []    = text "their"  -- probably avoid this
valuethisOrThese :: [a] -> SDoc
Source#

Determines the form of subject appropriate for the length of a list:

thisOrThese [x]   = text "This"
thisOrThese [x,y] = text "These"
thisOrThese []    = text "These"  -- probably avoid this
valueitOrThey :: [a] -> SDoc
Source#

it or they, depeneding on the length of the list.

itOrThey [x]   = text "it"
itOrThey [x,y] = text "they"
itOrThey []    = text "they"  -- probably avoid this

Converting SDoc into strings and outputting it

Controlling the style in which output is printed

datadata SDocContext
#

Constructors

valuedefaultErrStyle :: PprStyle
Source#

Default style for error messages, when we don't know NamePprCtx It's a bit of a hack because it doesn't take into account what's in scope Only used for desugarer warnings, and typechecker errors in interface sigs