Documentation

A class for pretty-printing values in a configurable manner.

A basic example:

>>> data Case = UpperCase | LowerCase
>>> data D = D
>>> instance PrettyBy Case D where prettyBy UpperCase D = "D"; prettyBy LowerCase D = "d"
>>> prettyBy UpperCase D
D
>>> prettyBy LowerCase D
d

The library provides instances for common types like Integer or Bool, so you can't define your own PrettyBy SomeConfig Integer instance. And for the same reason you should not define instances like PrettyBy SomeAnotherConfig a for universally quantified a, because such an instance would overlap with the existing ones. Take for example

>>> data ViaShow = ViaShow
>>> instance Show a => PrettyBy ViaShow a where prettyBy ViaShow = pretty . show

with such an instance prettyBy ViaShow (1 :: Int) throws an error about overlapping instances:

• Overlapping instances for PrettyBy ViaShow Int
    arising from a use of ‘prettyBy’
  Matching instances:
    instance PrettyDefaultBy config Int => PrettyBy config Int
    instance [safe] Show a => PrettyBy ViaShow a

There's a newtype provided specifically for the purpose of defining a PrettyBy instance for any a: PrettyAny. Read its docs for details on when you might want to use it.

The PrettyBy instance for common types is defined in a way that allows to override default pretty-printing behaviour, read the docs of HasPrettyDefaults for details.

A newtype wrapper around a whose point is to provide a PrettyBy config instance for anything that has a Pretty instance.

A config together with some value. The point is to provide a Pretty instance for anything that has a PrettyBy config instance.

A newtype wrapper around a provided for the purporse of defining PrettyBy instances handling any a. For example you can wrap values with the PrettyAny constructor directly like in this last line of

>>> data ViaShow = ViaShow
>>> instance Show a => PrettyBy ViaShow (PrettyAny a) where prettyBy ViaShow = pretty . show . unPrettyAny
>>> prettyBy ViaShow $ PrettyAny True
True

or you can use the type to via-derive instances:

>>> data D = D deriving stock (Show)
>>> deriving via PrettyAny D instance PrettyBy ViaShow D
>>> prettyBy ViaShow D
D

One important use case is handling sum-type configs. For example having two configs you can define their sum and derive PrettyBy for the unified config in terms of its components:

>>> data UpperCase = UpperCase
>>> data LowerCase = LowerCase
>>> data Case = CaseUpperCase UpperCase | CaseLowerCase LowerCase
>>> instance (PrettyBy UpperCase a, PrettyBy LowerCase a) => PrettyBy Case (PrettyAny a) where prettyBy (CaseUpperCase upper) = prettyBy upper . unPrettyAny; prettyBy (CaseLowerCase lower) = prettyBy lower . unPrettyAny

Then having a data type implementing both PrettyBy UpperCase and PrettyBy LowerCase you can derive PrettyBy Case for that data type:

>>> data D = D
>>> instance PrettyBy UpperCase D where prettyBy UpperCase D = "D"
>>> instance PrettyBy LowerCase D where prettyBy LowerCase D = "d"
>>> deriving via PrettyAny D instance PrettyBy Case D
>>> prettyBy UpperCase D
D
>>> prettyBy LowerCase D
d

Look into test/Universal.hs for an extended example.

Pass AttachPrettyConfig config to the continuation.

Default configurable pretty-printing for a Functor in terms of Pretty. Attaches the config to each value in the functor and calls pretty over the result, i.e. the spine of the functor is pretty-printed the way the Pretty class specifies it, while the elements are printed by prettyBy.

Default configurable pretty-printing for a Bifunctor in terms of Pretty Attaches the config to each value in the bifunctor and calls pretty over the result, i.e. the spine of the bifunctor is pretty-printed the way the Pretty class specifies it, while the elements are printed by prettyBy.

A class for overriding default pretty-printing behavior for types having it. Read the docs of HasPrettyDefaults for how to use the class.

Determines whether a pretty-printing config allows default pretty-printing for types that support it. I.e. it's possible to create a new config and get access to pretty-printing for all types supporting default pretty-printing just by providing the right type instance. Example:

>>> data DefCfg = DefCfg
>>> type instance HasPrettyDefaults DefCfg = 'True
>>> prettyBy DefCfg (['a', 'b', 'c'], (1 :: Int), Just True)
(abc, 1, True)

The set of types supporting default pretty-printing is determined by the prettyprinter library: whatever there has a Pretty instance also supports default pretty-printing in this library and the behavior of pretty x and prettyBy config_with_defaults x must be identical when x is one of such types.

It is possible to override default pretty-printing. For this you need to specify that HasPrettyDefaults is 'False for your config and then define a NonDefaultPrettyBy config instance for each of the types supporting default pretty-printing that you want to pretty-print values of. Note that once HasPrettyDefaults is specified to be 'False, all defaults are lost for your config, so you can't override default pretty-printing for one type and keep the defaults for all the others. I.e. if you have

>>> data NonDefCfg = NonDefCfg
>>> type instance HasPrettyDefaults NonDefCfg = 'False

then you have no defaults available and an attempt to pretty-print a value of a type supporting default pretty-printing

prettyBy NonDefCfg True

results in a type error:

• No instance for (NonDefaultPrettyBy NonDef Bool)
     arising from a use of ‘prettyBy’

As the error suggests you need to provide a NonDefaultPrettyBy instance explicitly:

>>> instance NonDefaultPrettyBy NonDefCfg Bool where nonDefaultPrettyBy _ b = if b then "t" else "f"
>>> prettyBy NonDefCfg True
t

It is also possible not to provide any implementation for nonDefaultPrettyBy, in which case it defaults to being the default pretty-printing for the given type. This can be useful to recover default pretty-printing for types pretty-printing of which you don't want to override:

>>> instance NonDefaultPrettyBy NonDefCfg Int
>>> prettyBy NonDefCfg (42 :: Int)
42

Look into test/NonDefault.hs for an extended example.

We could give the user more fine-grained control over what defaults to override instead of requiring to explicitly provide all the instances whenever there's a need to override any default behavior, but that would complicate the library even more, so we opted for not doing that at the moment.

Note that you can always override default behavior by wrapping a type in newtype and providing a PrettyBy config_name instance for that newtype.

Also note that if you want to extend the set of types supporting default pretty-printing it's not enough to provide a Pretty instance for your type (such logic is hardly expressible in present day Haskell). Read the docs of DefaultPrettyBy for how to extend the set of types supporting default pretty-printing.

PrettyDefaultBy config a is the same thing as PrettyBy config a, when a supports default pretty-printing. Thus PrettyDefaultBy config a and PrettyBy config a are interchangeable constraints for such types, but the latter throws an annoying "this makes type inference for inner bindings fragile" warning, unlike the former. PrettyDefaultBy config a reads as "a supports default pretty-printing and can be pretty-printed via config in either default or non-default manner depending on whether config supports default pretty-printing".

A class for rendering Docs as string types.

Pretty-print and render a value as a string type.

Pretty-print and render a value as a string type in a configurable way.