Data.Type.Pretty

Type Pretty Printing

Printing Custom Types

The main usecase of this library is rendering one's own complex types to pretty String values, e.g. for debugging and tracing purposes.

One way to create PrettyType documents is to define ToPretty instances for your types by combining the promoted constructors of PrettyType.

If UndecidableInstances isn't holding you back, use the type aliases like PutStr, PutNat, PrettyInfix, etc in these instance definitions.

ToPretty is an open type family, that converts a custom type to a PrettyType.

showPretty eventually crafts a String value from a proxy to the custom type.

It might be helpful to overcome egoistic needs for guaranteed compiler termination (i.e. allowing UndecidableInstances) in order to be able to use type aliases like PutStr, PutNat, etc.

Example

Let's start with the output:

+-------+-----+------------+
|  col 1|col 2|       col 3|
+-------+-----+------------+
|   2423|  451|       21234|
| 242322|   42|         n/a|
|      0| 4351|      623562|
|   4351|  n/a|         n/a|
|      0| 4351|      623562|
+-------+-----+------------+

... of rendering this table:

type TestTable =
  'MyTable         '[MyCol "col 1" 7, MyCol "col 2" 5, MyCol "col 3" 12]
          '[ MyRow '[2423           ,451             ,21234]
           , MyRow '[242322         ,42]
           , MyRow '[0              ,4351            ,623562]
           , MyRow '[4351]
           , MyRow '[0              ,4351            ,623562]
           ]

...using this function:

prettyTestTable :: String
prettyTestTable = showPretty (Proxy :: Proxy TestTable)

...from these data types:

-- | A type with a list of columns and rows.
data MyTable = MyTable [Type] [Type]

-- | A row of a table, with a list of numbers, one each for every column.
data MyRow :: [Nat] -> Type

-- | The column of a table. It has a width and a column title.
data MyCol :: Symbol -> Nat -> Type

...converted to PrettyType using this ToPretty instance:

type instance ToPretty ('MyTable cols rows) =
           PrettyManyIn (PutStr "+") (RowSepLine cols)
      <$$> PrettyManyIn (PutStr "|") (TableHeading cols)
      <$$> PrettyManyIn (PutStr "+") (RowSepLine cols)
      <$$> PrettyHigh   (TableRows cols rows)
      <$$> PrettyManyIn (PutStr "+") (RowSepLine cols)

type family
  TableHeading (cols :: [Type]) :: [PrettyType] where
  TableHeading '[]                      = '[]
  TableHeading (MyCol title width ': r) = PutStrW width title  ': TableHeading  r

type family
   RowSepLine (cols :: [Type]) :: [PrettyType] where
   RowSepLine '[] = '[]
   RowSepLine (MyCol title width ': r) =
     PrettyOften width (PutStr "-") ': RowSepLine  r

type family
  TableRows (cols :: [Type]) (rows :: [Type]) :: [PrettyType] where
  TableRows cols '[] = '[]
  TableRows cols (MyRow cells ': rest ) =
    PrettyManyIn (PutStr "|") (TableCells cols cells) ': TableRows cols rest

type family
  TableCells (cols :: [Type]) (cells :: [Nat]) :: [PrettyType] where
  TableCells '[] cells = '[]
  TableCells (MyCol title width ': cols) (value ': cells) =
    PutNatW width value ':  TableCells cols cells
  TableCells (MyCol title width ': cols) '[] =
    PutStrW width "n/a" ':  TableCells cols '[]

Pretty Printing Types

showPretty

Arguments

:: forall (t :: k). PrettyTypeShow (ToPretty t)

=> proxy t

A proxy to the type to print. A ToPretty instance for t must exists.

-> String

Pretty print either types of kind PrettyType or any other type with a ToPretty instance.

type family ToPretty (a :: k) :: PrettyType

Create a PrettyType from a type.

This is a type-level equivalent of the Show class.

Write an instance of this for converting your type (preferrable of your kind also) to a promoted PrettyType.

Instances

type ToPretty PrettyType t

type ToPretty PrettyType t = t

Pretty Printing

Pretty Printing Strings (Symbol)

type PutStr str = PrettySymbol PrettyUnpadded PrettyPrecise str

A PrettyType for a string.

type PutStrW width str = PrettySymbol (PrettyPadded width) (PrettyPrecision width) str

A PrettyType for a string with the exact given width.

type PutStrLn str = PutStr str <++> PutStr "\n"

A PrettyType for a string with a newline character at the end.

Pretty Printing Numbers (Nat)

type PutNat x = PrettyNat PrettyUnpadded PrettyPrecise PrettyDec x

A PrettyType for a number.

type PutNatW width x = PrettyNat (PrettyPadded width) PrettyPrecise PrettyDec x

A PrettyType for a number with a width.

type PutHex x = PrettyNat PrettyUnpadded PrettyPrecise PrettyHex x

Create PrettyType from a Nat formatted as hex number using lower-case letters for the hex digits.

type PutHex8 x = PrettyNat PrettyUnpadded (PrettyPrecision 2) PrettyHex x

Create PrettyType from a Nat formatted as 8 bit hex number using lower-case letters for the hex digits.

type PutHex16 x = PrettyNat PrettyUnpadded (PrettyPrecision 4) PrettyHex x

Create PrettyType from a Nat formatted as 16 bit hex number using lower-case letters for the hex digits.

type PutHex32 x = PrettyNat PrettyUnpadded (PrettyPrecision 8) PrettyHex x

Create PrettyType from a Nat formatted as 32 bit hex number using lower-case letters for the hex digits.

type PutHex64 x = PrettyNat PrettyUnpadded (PrettyPrecision 16) PrettyHex x

Create PrettyType from a Nat formatted as 64 bit hex number using lower-case letters for the hex digits.

type PutHeX x = PrettyNat PrettyUnpadded PrettyPrecise PrettyHexU x

Create PrettyType from a Nat formatted as hex number using lower-case letters for the hex digits.

type PutHeX8 x = PrettyNat PrettyUnpadded (PrettyPrecision 2) PrettyHexU x

Create PrettyType from a Nat formatted as 8 bit hex number using uppercase letters for the hex digits.

type PutHeX16 x = PrettyNat PrettyUnpadded (PrettyPrecision 4) PrettyHexU x

Create PrettyType from a Nat formatted as 16 bit hex number using uppercase letters for the hex digits.

type PutHeX32 x = PrettyNat PrettyUnpadded (PrettyPrecision 8) PrettyHexU x

Create PrettyType from a Nat formatted as 32 bit hex number using uppercase letters for the hex digits.

type PutHeX64 x = PrettyNat PrettyUnpadded (PrettyPrecision 16) PrettyHexU x

Create PrettyType from a Nat formatted as 64 bit hex number using uppercase letters for the hex digits.

type PutBits x = PrettyNat PrettyUnpadded PrettyPrecise PrettyBit x

Create PrettyType from a Nat formatted as bit representation,

>>> showPretty (Proxy :: Proxy (PutBits 5))
"101"

type PutBits8 x = PrettyNat PrettyUnpadded (PrettyPrecision 8) PrettyBit x

Create PrettyType from a Nat formatted as 8-bit bit representation,

>>> showPretty (Proxy :: Proxy (PutBits8 5))
"00000101"

type PutBits16 x = PrettyNat PrettyUnpadded (PrettyPrecision 16) PrettyBit x

Create PrettyType from a Nat formatted as 16-bit bit representation,

>>> showPretty (Proxy :: Proxy (PutBits16 5))
"00000000000000101"

type PutBits32 x = PrettyNat PrettyUnpadded (PrettyPrecision 32) PrettyBit x

Create PrettyType from a Nat formatted as 32-bit bit representation,

>>> showPretty (Proxy :: Proxy (PutBits32 5))
"00000000000000000000000000000000101"

type PutBits64 x = PrettyNat PrettyUnpadded (PrettyPrecision 64) PrettyBit x

Create PrettyType from a Nat formatted as 64-bit bit representation,

>>> showPretty (Proxy :: Proxy (PutBits64 5))
"00000000000000000000000000000000000000000000000000000000000000000000101"

Composing Pretty Printers

type (<:>) label body = PrettySuffix (PutStr ":") (PutStr label) <+> body infixl 5

A label followed by a colon and space : followed by another element.

>>> showPretty (Proxy :: Proxy ("foo" <:> PutStr "bar"))
@
foo: bar
@

type (<:$$>) label body = PrettySuffix (PutStr ":") (PutStr label) <$$> body infixl 5

Like <:> but begin the body on a new line.

>>> showPretty (Proxy :: Proxy (PutStr "foo" <:$$> PutStr "bar"))
@
foo:
bar
@

type (<:$$-->) label body = PrettySuffix (PutStr ":") (PutStr label) <$$--> body infixl 3

Like '<:$$__>' but indent the body with two spaces.

>>> showPretty (Proxy :: Proxy (PutStr "foo" <:$$--> PutStr "bar"))
@
foo:
  bar
@

type (<++>) l r = PrettyInfix PrettyEmpty l r infixl 6

Concatenate two PrettyType.

type (<+>) l r = PrettyInfix PrettySpace l r infixl 5

Concatenate two PrettyType using a PrettySpace.

type (<||>) l r = PrettyAlternative l r infixl 5

Choose the first non-empty from two PrettyTypes.

type (<$$>) l r = PrettyInfix PrettyNewline l r infixl 4

Concatenate two PrettyType using a PrettyNewline.

type (<$$-->) l r = PrettyInfix PrettyNewline l (PrettyIndent 2 r) infixl 3

Concatenate two PrettyType using a PrettyNewline and indent the second.

type PrettyParens doc = PrettySurrounded (PutStr "(") (PutStr ")") doc

Surround a pretty with parens

type PrettySurrounded open close doc = (open <++> doc) <++> close

Surround a pretty with some pretties

Pretty Printing Lists

type PrettyWide docs = PrettyMany PrettySpace docs

Combine a (type level) list of PrettyTypes next to each other using PrettySpace

type PrettyHigh docs = PrettyMany PrettyNewline docs

Combine a (type level) list of PrettyTypes below each other using PrettyNewline

type PrettyManyIn sep docs = PrettySurrounded sep sep (PrettyMany sep docs)

A combination of PrettySpace and PrettyMany, e.g.:

>>> showPretty (Proxy :: Proxy (PrettyManyIn (PutStr "|") '[PutStr "a", PutStr "b"]))
"|a|b|"

type family PrettyMany (sep :: PrettyType) (docs :: [PrettyType]) :: PrettyType where ...

Combine a (type level) list of PrettyTypes seperated by a seperation element.

Equations

PrettyMany sep '[] = PrettyEmpty

PrettyMany sep '[singleOne] = singleOne

PrettyMany sep (next ': rest) = (next <++> sep) <++> PrettyMany sep rest

type family PrettyOften (n :: Nat) (doc :: PrettyType) :: PrettyType where ...

Repeat a PrettyType n-times and append the copies.

Equations

PrettyOften 0 doc = PrettyEmpty

PrettyOften n doc = doc <++> PrettyOften (n - 1) doc

Basic Building Blocks

data PrettyType where

Combinators for type documents.

The basis for pretty printing is this eDSL. It is rendered via the PrettyTypeShow instances for its promoted constructors.

Only the promoted constructors are used, only they have instances for that class.

Constructors

PrettyEmpty :: PrettyType

PrettySpace :: PrettyType

PrettyNewline :: PrettyType

Begin a newline. Always use this otherwise indentation will not work!

PrettySymbol :: PrettyPadded -> PrettyPrecision -> Symbol -> PrettyType

PrettyNat :: PrettyPadded -> PrettyPrecision -> PrettyNatFormat -> Nat -> PrettyType

PrettyPrefix :: PrettyType -> PrettyType -> PrettyType

Prefix the second with the first argument, but only if it (the second) has content.

PrettyInfix :: PrettyType -> PrettyType -> PrettyType -> PrettyType

Combine the last to arguments with the first in between them, but only if both have content.

PrettySuffix :: PrettyType -> PrettyType -> PrettyType

Add a the first argument as suffix to the second argument, but only if the second has content.

PrettyIndent :: Nat -> PrettyType -> PrettyType

Indentation. Prefix any line using the given number of PrettySpace.

PrettyAlternative :: PrettyType -> PrettyType -> PrettyType

Alternative rendering, if the first document ist empty the second will be rendered.

Instances

type ToPretty PrettyType t

type ToPretty PrettyType t = t

data PrettyPadded where

Padding for PrettyTypes PrettySymbol and PrettyNat.

Constructors

PrettyUnpadded :: PrettyPadded

No minimum or fixed width

PrettyPadded :: Nat -> PrettyPadded

Pad a PrettySymbol or PrettyNat with spaces or zeros. NOTE PrettyNats will never be shorter than the minimum number of digits, regardless of this padding.

Instances

PrintfArgModifier PrettyPadded PrettyUnpadded

Translation of PrettyUnpadded to an empty modifier string

Methods

toPrintfArgModifier :: p a -> String

KnownNat p => PrintfArgModifier PrettyPadded (PrettyPadded p)

Translation of PrettyPadded to a string with the numeric padding value.

Methods

toPrintfArgModifier :: p a -> String

data PrettyPrecision where

The precision for PrettySymbol and PrettyNat.

Constructors

PrettyPrecise :: PrettyPrecision

No minimum precision.

PrettyPrecision :: Nat -> PrettyPrecision

Precision, for Symbols the maximum width, for Nats the minimum digits. NOTEPrettyNats will never be shorter than the minimum number of digits, wheres PrettySymbols will be truncated if they are longer than the precision.

Instances

PrintfArgModifier PrettyPrecision PrettyPrecise

Translation of PrettyPrecise to an empty modifier string

Methods

toPrintfArgModifier :: p a -> String

KnownNat p => PrintfArgModifier PrettyPrecision (PrettyPrecision p)

Translation of PrettyPadded to a string with the numeric precision value, prependen by a dot ".".

Methods

toPrintfArgModifier :: p a -> String

data PrettyNatFormat

PrettyNat formatting options.

Constructors

PrettyHex

Hexa decimal rendering:

>>> showPretty (Proxy::Proxy (PrettyNat PrettyUnpadded PrettyPrecise PrettyHex 51966))
"cafe"

PrettyHexU

Hexa decimal rendering (upper case):

>>> showPretty (Proxy::Proxy (PrettyNat PrettyUnpadded PrettyPrecise PrettyHexU 51966))
"CAFE"

PrettyDec

Decimal rendering:

>>> showPretty (Proxy::Proxy (PrettyNat PrettyUnpadded PrettyPrecise PrettyHexU 51966))
"51966"

PrettyBit

Binary rendering:

>>> showPretty (Proxy::Proxy (PrettyNat PrettyUnpadded PrettyPrecise PrettyHexU 51966))
"1100101011111110"

Instances

PrintfArgModifier PrettyNatFormat PrettyHex

Translation of PrettyHex to printf format character: x

Methods

toPrintfArgModifier :: p a -> String

PrintfArgModifier PrettyNatFormat PrettyHexU

Translation of PrettyHexU to printf format character: X

Methods

toPrintfArgModifier :: p a -> String

PrintfArgModifier PrettyNatFormat PrettyDec

Translation of PrettyDec to printf format character: d

Methods

toPrintfArgModifier :: p a -> String

PrintfArgModifier PrettyNatFormat PrettyBit

Translation of PrettyBit to printf format character: b

Methods

toPrintfArgModifier :: p a -> String

Pretty Rendering

class PrettyTypeShow p where

An internal type class for rendering the types of kind PrettyType.

Minimal complete definition

ptShow

Methods

ptShow :: proxy p -> PTM ()

Given any proxy to a promoted constructor of PrettyType, generate a String.

ptHasContent :: proxy p -> PTM Bool

Return True if contents would be writting to the output of rendered via ptShow

Instances

PrettyTypeShow PrettyEmpty

Print nothing.

Methods

ptShow :: proxy PrettyEmpty -> PTM ()

ptHasContent :: proxy PrettyEmpty -> PTM Bool

PrettyTypeShow PrettySpace

Print a single space character.

Methods

ptShow :: proxy PrettySpace -> PTM ()

ptHasContent :: proxy PrettySpace -> PTM Bool

PrettyTypeShow PrettyNewline

Print a single newline character.

Methods

ptShow :: proxy PrettyNewline -> PTM ()

ptHasContent :: proxy PrettyNewline -> PTM Bool

(PrettyTypeShow sep, PrettyTypeShow x) => PrettyTypeShow (PrettyPrefix sep x)

Prefix a PrettyType to x, but only if ptHasContent of x holds.

Methods

ptShow :: proxy (PrettyPrefix sep x) -> PTM ()

ptHasContent :: proxy (PrettyPrefix sep x) -> PTM Bool

(PrettyTypeShow sep, PrettyTypeShow x) => PrettyTypeShow (PrettySuffix sep x)

Add a PrettyType suffix to x, but only if ptHasContent holds.

Methods

ptShow :: proxy (PrettySuffix sep x) -> PTM ()

ptHasContent :: proxy (PrettySuffix sep x) -> PTM Bool

(PrettyTypeShow r, KnownNat n) => PrettyTypeShow (PrettyIndent n r)

Render an indented, nested type.

Methods

ptShow :: proxy (PrettyIndent n r) -> PTM ()

ptHasContent :: proxy (PrettyIndent n r) -> PTM Bool

(PrettyTypeShow l, PrettyTypeShow r) => PrettyTypeShow (PrettyAlternative l r)

Render the first document, and if it is empty, the second

Methods

ptShow :: proxy (PrettyAlternative l r) -> PTM ()

ptHasContent :: proxy (PrettyAlternative l r) -> PTM Bool

(KnownSymbol t, PrintfArgModifier PrettyPadded pad, PrintfArgModifier PrettyPrecision prec) => PrettyTypeShow (PrettySymbol pad prec t)

Print a Symbol using the printf and the given format parameters.

Methods

ptShow :: proxy (PrettySymbol pad prec t) -> PTM ()

ptHasContent :: proxy (PrettySymbol pad prec t) -> PTM Bool

(PrettyTypeShow sep, PrettyTypeShow l, PrettyTypeShow r) => PrettyTypeShow (PrettyInfix sep l r)

Concatenate two PrettyTypes. If one of them is empty print the other without any seperation character.

Methods

ptShow :: proxy (PrettyInfix sep l r) -> PTM ()

ptHasContent :: proxy (PrettyInfix sep l r) -> PTM Bool

(KnownNat x, PrintfArgModifier PrettyNatFormat fmt, PrintfArgModifier PrettyPadded pad, PrintfArgModifier PrettyPrecision prec) => PrettyTypeShow (PrettyNat pad prec fmt x)

Print a Nat using the printf and the given format parameters.

Methods

ptShow :: proxy (PrettyNat pad prec fmt x) -> PTM ()

ptHasContent :: proxy (PrettyNat pad prec fmt x) -> PTM Bool

type PTM a = RWS Indentation String PTRenderState a

Internal monad used by ptShow, the state is a Bool indicating

writeIndented :: String -> PTM ()

Internal; write a possibly indented string, and update the PTRenderState accordingly.

type Indentation = Int

Internal type of the indentation used by ptShow in PTM

data PTRenderState

Internal state used by ptShow in PTM

Constructors

AtBeginningOfLine

AlreadyIndented

class PrintfArgModifier a where

Internal printf format generation. Used internally by PrettyTypeShow instances to generate the format string piece by piece with the values for the instances of e.g. PrettyPrecise, PrettyNatFormat, or PrettyEmpty.

Minimal complete definition

toPrintfArgModifier

Methods

toPrintfArgModifier :: p a -> String

Generate a piece of a printf format string from a proxy for a type.

Instances

PrintfArgModifier PrettyNatFormat PrettyHex

Translation of PrettyHex to printf format character: x

Methods

toPrintfArgModifier :: p a -> String

PrintfArgModifier PrettyNatFormat PrettyHexU

Translation of PrettyHexU to printf format character: X

Methods

toPrintfArgModifier :: p a -> String

PrintfArgModifier PrettyNatFormat PrettyDec

Translation of PrettyDec to printf format character: d

Methods

toPrintfArgModifier :: p a -> String

PrintfArgModifier PrettyNatFormat PrettyBit

Translation of PrettyBit to printf format character: b

Methods

toPrintfArgModifier :: p a -> String

PrintfArgModifier PrettyPrecision PrettyPrecise

Translation of PrettyPrecise to an empty modifier string

Methods

toPrintfArgModifier :: p a -> String

PrintfArgModifier PrettyPadded PrettyUnpadded

Translation of PrettyUnpadded to an empty modifier string

Methods

toPrintfArgModifier :: p a -> String

KnownNat p => PrintfArgModifier PrettyPrecision (PrettyPrecision p)

Translation of PrettyPadded to a string with the numeric precision value, prependen by a dot ".".

Methods

toPrintfArgModifier :: p a -> String

KnownNat p => PrintfArgModifier PrettyPadded (PrettyPadded p)

Translation of PrettyPadded to a string with the numeric padding value.

Methods

toPrintfArgModifier :: p a -> String