Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
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 {}
- data AttachPrettyConfig config a = AttachPrettyConfig !config !a
- newtype PrettyAny a = PrettyAny {
- unPrettyAny ∷ a
- withAttachPrettyConfig ∷ config → ((∀ 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
- display ∷ ∀ str a. (Pretty a, Render str) ⇒ a → str
- displayBy ∷ ∀ 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.
Nothing
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
PrettyDefaultBy config Void ⇒ PrettyBy config Void Source # |
|
PrettyDefaultBy config Int16 ⇒ PrettyBy config Int16 Source # | |
PrettyDefaultBy config Int32 ⇒ PrettyBy config Int32 Source # | |
PrettyDefaultBy config Int64 ⇒ PrettyBy config Int64 Source # | |
PrettyDefaultBy config Int8 ⇒ PrettyBy config Int8 Source # | |
PrettyDefaultBy config Word16 ⇒ PrettyBy config Word16 Source # | |
PrettyDefaultBy config Word32 ⇒ PrettyBy config Word32 Source # | |
PrettyDefaultBy config Word64 ⇒ PrettyBy config Word64 Source # | |
PrettyDefaultBy config Word8 ⇒ PrettyBy config Word8 Source # | |
PrettyDefaultBy config Text ⇒ PrettyBy config Text Source # | Automatically converts all newlines to
|
PrettyDefaultBy config Text ⇒ PrettyBy config Text Source # | An instance for lazy |
PrettyDefaultBy config Integer ⇒ PrettyBy config Integer Source # |
|
PrettyDefaultBy config Natural ⇒ PrettyBy config Natural Source # |
|
PrettyDefaultBy config () ⇒ PrettyBy config () Source # |
The argument is not used:
|
Defined in Text.PrettyBy.Internal | |
PrettyDefaultBy config Bool ⇒ PrettyBy config Bool Source # |
|
PrettyDefaultBy config Char ⇒ PrettyBy config Char Source # | By default a
|
PrettyDefaultBy config Double ⇒ PrettyBy config Double Source # |
|
PrettyDefaultBy config Float ⇒ PrettyBy config Float Source # |
|
PrettyDefaultBy config Int ⇒ PrettyBy config Int Source # |
|
PrettyDefaultBy config Word ⇒ PrettyBy config Word Source # | |
PrettyDefaultBy config (Identity a) ⇒ PrettyBy config (Identity a) Source # |
|
PrettyDefaultBy config (NonEmpty a) ⇒ PrettyBy config (NonEmpty a) Source # |
|
Pretty a ⇒ PrettyBy config (IgnorePrettyConfig a) Source # |
|
Defined in Text.PrettyBy.Internal prettyBy ∷ config → IgnorePrettyConfig a → Doc ann Source # prettyListBy ∷ config → [IgnorePrettyConfig a] → Doc ann Source # | |
PrettyDefaultBy config a ⇒ PrettyBy config (PrettyCommon a) Source # | |
Defined in Text.PrettyBy.Internal 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
|
PrettyDefaultBy config [a] ⇒ PrettyBy config [a] Source # |
|
Defined in Text.PrettyBy.Internal | |
PrettyDefaultBy config (a, b) ⇒ PrettyBy config (a, b) Source # |
|
Defined in Text.PrettyBy.Internal | |
PrettyDefaultBy config (Const a b) ⇒ PrettyBy config (Const a b) Source # | Non-polykinded, because
|
PrettyDefaultBy config (a, b, c) ⇒ PrettyBy config (a, b, c) Source # |
|
Defined in Text.PrettyBy.Internal |
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.
Instances
Pretty a ⇒ PrettyBy config (IgnorePrettyConfig a) Source # |
|
Defined in Text.PrettyBy.Internal 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.
AttachPrettyConfig !config !a |
Instances
PrettyBy config a ⇒ Pretty (AttachPrettyConfig config a) Source # |
|
Defined in Text.PrettyBy.Internal pretty ∷ AttachPrettyConfig config a → Doc ann Source # prettyList ∷ [AttachPrettyConfig config a] → Doc ann 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.
PrettyAny | |
|
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 #
defaultPrettyBifunctorBy ∷ (Bifunctor f, Pretty (f (AttachPrettyConfig config a) (AttachPrettyConfig config b))) ⇒ config → f a b → Doc ann Source #
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.
Nothing
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
type HasPrettyDefaults () Source # |
|
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".