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, PrettySeperated, 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 (<++>) l r = PrettySeperated PrettyEmpty l r infixl 6

Concatenate two PrettyType.

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

Concatenate two PrettyType using a PrettySpace.

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

Concatenate two PrettyType using a PrettyNewline.

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

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

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

PrettySeperated :: PrettyType -> PrettyType -> PrettyType -> PrettyType

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 -> String

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

Instances

PrettyTypeShow PrettyEmpty

Print nothing.

Methods

ptShow :: proxy PrettyEmpty -> String

PrettyTypeShow PrettySpace

Print a single space character.

Methods

ptShow :: proxy PrettySpace -> String

PrettyTypeShow PrettyNewline

Print a single newline character.

Methods

ptShow :: proxy PrettyNewline -> String

(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) -> String

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

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

Methods

ptShow :: proxy (PrettySeperated sep l r) -> String

(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) -> String

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