prettyprinter-configurable-1.30.0.0: Configurable pretty-printing
Safe HaskellSafe-Inferred
LanguageHaskell2010

Text.PrettyBy

Description

The main module of the library.

Synopsis

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 prettyByDefaultFor "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 VoidPrettyBy 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 Int16PrettyBy 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 Int32PrettyBy 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 Int64PrettyBy 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 Int8PrettyBy 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 Word16PrettyBy 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 Word32PrettyBy 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 Word64PrettyBy 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 Word8PrettyBy 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 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 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 IntegerPrettyBy 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 NaturalPrettyBy 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 () ⇒ 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 BoolPrettyBy 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 CharPrettyBy 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 DoublePrettyBy 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 FloatPrettyBy 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 IntPrettyBy 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 WordPrettyBy 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 (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 (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 #

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

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 [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 (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

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

prettyAttachPrettyConfig config a → Doc ann

prettyList ∷ [AttachPrettyConfig config a] → Doc ann

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

withAttachPrettyConfig ∷ config → ((∀ 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 nonDefaultPrettyByDefaultPrettyBy 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 nonDefaultPrettyListByDefaultPrettyBy 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 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 Docs 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 ~ CharRender [a] Source # 
Instance details

Defined in Text.PrettyBy.Default

Methods

render ∷ Doc ann → [a] Source #

display ∷ ∀ str a. (Pretty a, Render str) ⇒ a → str Source #

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

displayBy ∷ ∀ 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.