Safe Haskell	None
Language	Haskell2010

Text.PrettyBy

Description

The main module of the library.

Synopsis

class PrettyBy config a where
- prettyBy :: config -> a -> Doc ann
- prettyListBy :: config -> [a] -> Doc ann
newtype IgnorePrettyConfig a = IgnorePrettyConfig {
- unIgnorePrettyConfig :: a
}
data AttachPrettyConfig config a = AttachPrettyConfig !config !a
newtype PrettyAny a = PrettyAny {
- unPrettyAny :: a
}
withAttachPrettyConfig :: config -> (( forall a. a -> AttachPrettyConfig config a) -> r) -> r
defaultPrettyFunctorBy :: ( Functor f, Pretty (f ( AttachPrettyConfig config a))) => config -> f a -> Doc ann
defaultPrettyBifunctorBy :: ( Bifunctor f, Pretty (f ( AttachPrettyConfig config a) ( AttachPrettyConfig config b))) => config -> f a b -> Doc ann
class NonDefaultPrettyBy config a where
- nonDefaultPrettyBy :: config -> a -> Doc ann
- nonDefaultPrettyListBy :: config -> [a] -> Doc ann
type family HasPrettyDefaults config :: Bool
type PrettyDefaultBy config = DispatchPrettyDefaultBy ( NonStuckHasPrettyDefaults config) config
class Render str where
- render :: Doc ann -> str
display :: forall str a. ( Pretty a, Render str) => a -> str
displayBy :: forall str a config. ( PrettyBy config a, Render str) => config -> a -> str

Documentation

class PrettyBy config a where Source #

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.

Minimal complete definition

Nothing

Methods

prettyBy :: config -> a -> Doc ann Source #

Pretty-print a value of type a the way a config specifies it. The default implementation of prettyBy is in terms of pretty , defaultPrettyFunctorBy or defaultPrettyBifunctorBy depending on the kind of the data type that you're providing an instance for. For example, the default implementation of prettyBy for a monomorphic type is going to be "ignore the config and call pretty over the value":

>>> newtype N = N Int deriving newtype (Pretty)
>>> instance PrettyBy () N
>>> prettyBy () (N 42)
42

The default implementation of prettyBy for a Functor is going to be in terms of defaultPrettyFunctorBy :

>>> newtype N a = N a deriving stock (Functor) deriving newtype (Pretty)
>>> instance PrettyBy () a => PrettyBy () (N a)
>>> prettyBy () (N (42 :: Int))
42

It's fine for the data type to have a phantom parameter as long as the data type is still a Functor (i.e. the parameter has to be of kind Type ). Then defaultPrettyFunctorBy is used again:

>>> newtype N a = N Int deriving stock (Functor) deriving newtype (Pretty)
>>> instance PrettyBy () (N b)
>>> prettyBy () (N 42)
42

If the data type has a single parameter of any other kind, then it's not a functor and so like in the monomorphic case pretty is used:

>>> newtype N (b :: Bool) = N Int deriving newtype (Pretty)
>>> instance PrettyBy () (N b)
>>> prettyBy () (N 42)
42

Same applies to a data type with two parameters: if both the parameters are of kind Type , then the data type is assumed to be a Bifunctor and hence defaultPrettyBifunctorBy is used. If the right parameter is of kind Type and the left parameter is of any other kind, then we fallback to assuming the data type is a Functor and defining prettyBy as defaultPrettyFunctorBy . If both the parameters are not of kind Type , we fallback to implementing prettyBy in terms of pretty like in the monomorphic case.

Note that in all those cases a Pretty instance for the data type has to already exist, so that we can derive a PrettyBy one in terms of it. If it doesn't exist or if your data type is not supported (for example, if it has three or more parameters of kind Type ), then you'll need to provide the implementation manually.

default prettyBy :: DefaultFor "prettyBy" config a => config -> a -> Doc ann Source #

prettyListBy :: config -> [a] -> Doc ann Source #

prettyListBy is used to define the default PrettyBy instance for [a] and NonEmpty a . In normal circumstances only the prettyBy function is used. The default implementation of prettyListBy is in terms of defaultPrettyFunctorBy .

default prettyListBy :: config -> [a] -> Doc ann Source #

Instances

Instances details

PrettyDefaultBy config Char => PrettyBy config Char Source #	By default a `String` (i.e. `[Char]` ) is converted to a `Text` first and then pretty-printed. So make sure that if you have any non-default pretty-printing for `Char` or `Text` , they're in sync. `>>>` `prettyBy () 'a'`a `>>>` `prettyBy () "abc"`abc
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Char -> Doc ann Source # prettyListBy :: config -> [ Char ] -> Doc ann Source #
PrettyDefaultBy config Text => PrettyBy config Text Source #	An instance for lazy `Text` . Identitical to the strict one.
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Text -> Doc ann Source # prettyListBy :: config -> [ Text ] -> Doc ann Source #
PrettyDefaultBy config Text => PrettyBy config Text Source #	Automatically converts all newlines to `line` . `>>>` `prettyBy () ("hello\nworld" :: Strict.Text)`hello world
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Text -> Doc ann Source # prettyListBy :: config -> [ Text ] -> Doc ann Source #
PrettyDefaultBy config Double => PrettyBy config Double Source #	`>>>` `prettyBy () (pi :: Double)`3.141592653589793
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Double -> Doc ann Source # prettyListBy :: config -> [ Double ] -> Doc ann Source #
PrettyDefaultBy config Float => PrettyBy config Float Source #	`>>>` `prettyBy () (pi :: Float)`3.1415927
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Float -> Doc ann Source # prettyListBy :: config -> [ Float ] -> Doc ann Source #
PrettyDefaultBy config Word64 => PrettyBy config Word64 Source #
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Word64 -> Doc ann Source # prettyListBy :: config -> [ Word64 ] -> Doc ann Source #
PrettyDefaultBy config Word32 => PrettyBy config Word32 Source #
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Word32 -> Doc ann Source # prettyListBy :: config -> [ Word32 ] -> Doc ann Source #
PrettyDefaultBy config Word16 => PrettyBy config Word16 Source #
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Word16 -> Doc ann Source # prettyListBy :: config -> [ Word16 ] -> Doc ann Source #
PrettyDefaultBy config Word8 => PrettyBy config Word8 Source #
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Word8 -> Doc ann Source # prettyListBy :: config -> [ Word8 ] -> Doc ann Source #
PrettyDefaultBy config Word => PrettyBy config Word Source #
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Word -> Doc ann Source # prettyListBy :: config -> [ Word ] -> Doc ann Source #
PrettyDefaultBy config Int64 => PrettyBy config Int64 Source #
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Int64 -> Doc ann Source # prettyListBy :: config -> [ Int64 ] -> Doc ann Source #
PrettyDefaultBy config Int32 => PrettyBy config Int32 Source #
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Int32 -> Doc ann Source # prettyListBy :: config -> [ Int32 ] -> Doc ann Source #
PrettyDefaultBy config Int16 => PrettyBy config Int16 Source #
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Int16 -> Doc ann Source # prettyListBy :: config -> [ Int16 ] -> Doc ann Source #
PrettyDefaultBy config Int8 => PrettyBy config Int8 Source #
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Int8 -> Doc ann Source # prettyListBy :: config -> [ Int8 ] -> Doc ann Source #
PrettyDefaultBy config Int => PrettyBy config Int Source #	`>>>` `prettyBy () (123 :: Int)`123
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Int -> Doc ann Source # prettyListBy :: config -> [ Int ] -> Doc ann Source #
PrettyDefaultBy config Integer => PrettyBy config Integer Source #	`>>>` `prettyBy () (2^(123 :: Int) :: Integer)`10633823966279326983230456482242756608
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Integer -> Doc ann Source # prettyListBy :: config -> [ Integer ] -> Doc ann Source #
PrettyDefaultBy config Natural => PrettyBy config Natural Source #	`>>>` `prettyBy () (123 :: Natural)`123
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Natural -> Doc ann Source # prettyListBy :: config -> [ Natural ] -> Doc ann Source #
PrettyDefaultBy config Bool => PrettyBy config Bool Source #	`>>>` `prettyBy () True`True
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Bool -> Doc ann Source # prettyListBy :: config -> [ Bool ] -> Doc ann Source #
PrettyDefaultBy config () => PrettyBy config () Source #	`>>>` `prettyBy () ()`() The argument is not used: `>>>` `prettyBy () (error "Strict?" :: ())`()
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> () -> Doc ann Source # prettyListBy :: config -> [()] -> Doc ann Source #
PrettyDefaultBy config Void => PrettyBy config Void Source #	`>>>` `prettyBy () ([] :: [Void])`[]
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Void -> Doc ann Source # prettyListBy :: config -> [ Void ] -> Doc ann Source #
PrettyDefaultBy config a => PrettyBy config ( PrettyCommon a) Source #
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> PrettyCommon a -> Doc ann Source # prettyListBy :: config -> [ PrettyCommon a] -> Doc ann Source #
Pretty a => PrettyBy config ( IgnorePrettyConfig a) Source #	`>>>` `data Cfg = Cfg``>>>` `data D = D``>>>` `instance Pretty D where pretty D = "D"``>>>` `prettyBy Cfg $ IgnorePrettyConfig D`D
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> IgnorePrettyConfig a -> Doc ann Source # prettyListBy :: config -> [ IgnorePrettyConfig a] -> Doc ann Source #
PrettyDefaultBy config ( Maybe a) => PrettyBy config ( Maybe a) Source #	By default a `[Maybe a]` is converted to `[a]` first and only then pretty-printed. `>>>` `braces $ prettyBy () (Just True)`{True} `>>>` `braces $ prettyBy () (Nothing :: Maybe Bool)`{} `>>>` `prettyBy () [Just False, Nothing, Just True]`[False, True] `>>>` `prettyBy () [Nothing, Just 'a', Just 'b', Nothing, Just 'c']`abc
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Maybe a -> Doc ann Source # prettyListBy :: config -> [ Maybe a] -> Doc ann Source #
PrettyDefaultBy config ( NonEmpty a) => PrettyBy config ( NonEmpty a) Source #	`prettyBy` for `NonEmpty a` is defined in terms of `prettyListBy` by default. `>>>` `prettyBy () (True :\| [False])`[True, False] `>>>` `prettyBy () ('a' :\| "bc")`abc `>>>` `prettyBy () (Just False :\| [Nothing, Just True])`[False, True]
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> NonEmpty a -> Doc ann Source # prettyListBy :: config -> [ NonEmpty a] -> Doc ann Source #
PrettyDefaultBy config [a] => PrettyBy config [a] Source #	`prettyBy` for `[a]` is defined in terms of `prettyListBy` by default. `>>>` `prettyBy () [True, False]`[True, False] `>>>` `prettyBy () "abc"`abc `>>>` `prettyBy () [Just False, Nothing, Just True]`[False, True]
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> [a] -> Doc ann Source # prettyListBy :: config -> [[a]] -> Doc ann Source #
PrettyDefaultBy config ( Identity a) => PrettyBy config ( Identity a) Source #	`>>>` `prettyBy () (Identity True)`True
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Identity a -> Doc ann Source # prettyListBy :: config -> [ Identity a] -> Doc ann Source #
PrettyDefaultBy config (a, b) => PrettyBy config (a, b) Source #	`>>>` `prettyBy () (False, "abc")`(False, abc)
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> (a, b) -> Doc ann Source # prettyListBy :: config -> [(a, b)] -> Doc ann Source #
PrettyDefaultBy config ( Const a b) => PrettyBy config ( Const a b) Source #	Non-polykinded, because `Pretty (Const a b)` is not polykinded either. `>>>` `prettyBy () (Const 1 :: Const Integer Bool)`1
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> Const a b -> Doc ann Source # prettyListBy :: config -> [ Const a b] -> Doc ann Source #
PrettyDefaultBy config (a, b, c) => PrettyBy config (a, b, c) Source #	`>>>` `prettyBy () ('a', "bcd", True)`(a, bcd, True)
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> (a, b, c) -> Doc ann Source # prettyListBy :: config -> [(a, b, c)] -> Doc ann Source #

newtype IgnorePrettyConfig a Source #

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

Constructors

IgnorePrettyConfig
Fields unIgnorePrettyConfig :: a

Instances

Instances details

Pretty a => PrettyBy config ( IgnorePrettyConfig a) Source #	`>>>` `data Cfg = Cfg``>>>` `data D = D``>>>` `instance Pretty D where pretty D = "D"``>>>` `prettyBy Cfg $ IgnorePrettyConfig D`D
Instance details Defined in Text.PrettyBy.Internal Methods prettyBy :: config -> IgnorePrettyConfig a -> Doc ann Source # prettyListBy :: config -> [ IgnorePrettyConfig a] -> Doc ann Source #

data AttachPrettyConfig config a Source #

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

Constructors

AttachPrettyConfig !config !a

Instances

Instances details

PrettyBy config a => Pretty ( AttachPrettyConfig config a) Source #	`>>>` `data Cfg = Cfg``>>>` `data D = D``>>>` `instance PrettyBy Cfg D where prettyBy Cfg D = "D"``>>>` `pretty $ AttachPrettyConfig Cfg D`D
Instance details Defined in Text.PrettyBy.Internal Methods pretty :: AttachPrettyConfig config a -> Doc ann Source # prettyList :: [ AttachPrettyConfig config a] -> Doc ann Source #

newtype PrettyAny a Source #

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.

Constructors

PrettyAny
Fields unPrettyAny :: a

withAttachPrettyConfig :: config -> (( forall a. a -> AttachPrettyConfig config a) -> r) -> r Source #

Pass AttachPrettyConfig config to the continuation.

defaultPrettyFunctorBy :: ( Functor f, Pretty (f ( AttachPrettyConfig config a))) => config -> f a -> Doc ann Source #

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 .

defaultPrettyBifunctorBy :: ( Bifunctor f, Pretty (f ( AttachPrettyConfig config a) ( AttachPrettyConfig config b))) => config -> f a b -> Doc ann Source #

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 .

class NonDefaultPrettyBy config a where Source #

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

Minimal complete definition

Nothing

Methods

nonDefaultPrettyBy :: config -> a -> Doc ann Source #

Pretty-print a value of a type supporting default pretty-printing in a possibly non-default way. The "possibly" is due to nonDefaultPrettyBy having a default implementation as defaultPrettyBy . See docs for HasPrettyDefaults for details.

default nonDefaultPrettyBy :: DefaultPrettyBy config a => config -> a -> Doc ann Source #

nonDefaultPrettyListBy :: config -> [a] -> Doc ann Source #

nonDefaultPrettyListBy to prettyListBy is what nonDefaultPrettyBy to prettyBy . Analogously, the default implementation is defaultPrettyListBy .

default nonDefaultPrettyListBy :: DefaultPrettyBy config a => config -> [a] -> Doc ann Source #

type family HasPrettyDefaults config :: Bool Source #

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.

Instances

Instances details

type HasPrettyDefaults () Source #	`prettyBy ()` works like `pretty` for types supporting default pretty-printing.
Instance details Defined in Text.PrettyBy.Internal type HasPrettyDefaults () = ' True

type PrettyDefaultBy config = DispatchPrettyDefaultBy ( NonStuckHasPrettyDefaults config) config Source #

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".

class Render str where Source #

A class for rendering Doc s as string types.

Methods

render :: Doc ann -> str Source #

Render a Doc as a string type.

Instances

Instances details

Render Text Source #
Instance details Defined in Text.PrettyBy.Default Methods render :: Doc ann -> Text Source #
Render Text Source #
Instance details Defined in Text.PrettyBy.Default Methods render :: Doc ann -> Text Source #
a ~ Char => Render [a] Source #
Instance details Defined in Text.PrettyBy.Default Methods render :: Doc ann -> [a] Source #

display :: forall str a. ( Pretty a, Render str) => a -> str Source #

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

displayBy :: forall str a config. ( PrettyBy config a, Render str) => config -> a -> str Source #

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