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.

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.

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.

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.

Return the longest sequence of Type in the kind (right-to-left) of the head of an application. (but no longer than Type -> Type -> Type, because we can't support longer ones in DispatchDefaultFor).

This allows us to have different default implementations for prettyBy and defaultPrettyBy depending on whether a is a monomorphic type or a Functor or a Bifunctor. Read the docs of prettyBy for details.

Introducing a class just for the nice name of the method and in case the defaulting machinery somehow blows up in the user's face.

Same as AttachPrettyConfig, but for providing a Pretty instance for anything that has a DefaultPrettyBy instance. Needed for the default implementation of defaultPrettyListBy.

A class for pretty-printing values is some default manner. Basic example:

>>> data D = D
>>> instance PrettyBy () D where prettyBy () D = "D"
>>> defaultPrettyBy () (Just D)
D

DefaultPrettyBy and PrettyBy are mutually recursive in a sense: PrettyBy delegates to DefaultPrettyBy (provided the config supports defaults) when given a value of a type supporting default pretty-printing and DefaultPrettyBy delegates back to PrettyBy for elements of a polymorphic container.

It is possible to extend the set of types supporting default pretty-printing. If you have a newtype wrapping a type that already supports default pretty-printing, then "registering" that newtype amounts to making a standalone newtype-deriving declaration:

>>> newtype AlsoInt = AlsoInt Int
>>> deriving newtype instance PrettyDefaultBy config Int => PrettyBy config AlsoInt
>>> prettyBy () (AlsoInt 42)
42

Note that you have to use standalone deriving as

newtype AlsoInt = AlsoInt Int deriving newtype (PrettyBy config)

doesn't please GHC.

It's also good practice to preserve coherence of Pretty and PrettyBy, so I'd also add deriving newtype (Pretty) to the definition of AlsoInt, even though it's not necessary.

When you want to extend the set of types supporting default pretty-printing with a data type that is a data rather than a newtype, you can directly implement DefaultPrettyBy and and via-derive PrettyBy:

>>> data D = D
>>> instance DefaultPrettyBy config D where defaultPrettyBy _ D = "D"
>>> deriving via PrettyCommon D instance PrettyDefaultBy config D => PrettyBy config D
>>> prettyBy () D
D

But since it's best to preserve coherence of Pretty and PrettyBy for types supporting default pretty-printing, it's recommended (not mandatory) to define a Pretty instance and anyclass-derive DefaultPrettyBy in terms of it:

>>> data D = D
>>> instance Pretty D where pretty D = "D"
>>> instance DefaultPrettyBy config D
>>> deriving via PrettyCommon D instance PrettyDefaultBy config D => PrettyBy config D
>>> prettyBy () [D, D, D]
[D, D, D]

Note that DefaultPrettyBy is specifically designed to handle all configs in its instances, i.e. you only specify a data type in a DefaultPrettyBy instance and leave config universally quantified. This is because default pretty-printing behavior should be the same for all configs supporting default pretty-printing (it's the default after all). If you want to override the defaults, read the docs of HasPrettyDefaults.

Since config in a DefaultPrettyBy instance is meant to be universally quantified, defaultPrettyBy (the main method of DefaultPrettyBy) has to ignore the config in the monomorphic case as it can't use it in any way anyway, i.e. in the monomorphic case defaultPrettyBy has the exact same info as simple pretty, which is another reason to anyclass-derive DefaultPrettyBy in terms of Pretty.

Like in the case of prettyBy, the default implementation of defaultPrettyBy for a Functor is defaultPrettyFunctorBy (and for a Bifunctor -- defaultPrettyBifunctorBy):

>>> data Twice a = Twice a a deriving stock (Functor)
>>> instance Pretty a => Pretty (Twice a) where pretty (Twice x y) = pretty x <+> "&" <+> pretty y
>>> instance PrettyBy config a => DefaultPrettyBy config (Twice a)
>>> deriving via PrettyCommon (Twice a) instance PrettyDefaultBy config (Twice a) => PrettyBy config (Twice a)
>>> prettyBy () (Twice True False)
True & False

Since preserving coherence of Pretty and PrettyBy is only a good practice and not mandatory, it's fine not to provide an instance for Pretty. Then a DefaultPrettyBy can be implemented directly:

>>> data Twice a = Twice a a
>>> instance PrettyBy config a => DefaultPrettyBy config (Twice a) where defaultPrettyBy config (Twice x y) = prettyBy config x <+> "&" <+> prettyBy config y
>>> deriving via PrettyCommon (Twice a) instance PrettyDefaultBy config (Twice a) => PrettyBy config (Twice a)
>>> prettyBy () (Twice True False)
True & False

But make sure that if both a Pretty and a DefaultPrettyBy instances exist, then they're in sync.

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

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 newtype wrapper defined for its PrettyBy instance that allows to via-derive a PrettyBy instance for a type supporting default pretty-printing.

Throw err when b is stuck.

The error thrown when HasPrettyDefaults config is stuck.

A version of HasPrettyDefaults that is never stuck: it either immediately evaluates to a Bool or fails with a TypeError.

DispatchPrettyDefaultBy is a class for dispatching on HasPrettyDefaults config: if it's 'True, then dispatchPrettyDefaultBy is instantiated as defaultPrettyBy, otherwise as nonDefaultPrettyBy (and similarly for dispatchPrettyDefaultListBy). I.e. depending on whether a config allows to pretty-print values using default pretty-printing, either the default or non-default pretty-printing strategy is used.

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.