Copyright | (C) 2014-2015 Ryan Scott |
---|---|
License | BSD-style (see the file LICENSE) |
Maintainer | Ryan Scott |
Stability | Experimental |
Portability | GHC |
Safe Haskell | None |
Language | Haskell98 |
Functions to mechanically derive Show
instances or splice
show
-related expressions into Haskell source code. You need to enable
the TemplateHaskell
language extension in order to use this module.
Since: 0.3
- deriveShow :: Name -> Q [Dec]
- deriveShowPragmas :: PragmaOptions -> Name -> Q [Dec]
- mkShow :: Name -> Q Exp
- mkShowLazy :: Name -> Q Exp
- mkShowPrec :: Name -> Q Exp
- mkShowPrecLazy :: Name -> Q Exp
- mkShowList :: Name -> Q Exp
- mkShowListLazy :: Name -> Q Exp
- mkShowb :: Name -> Q Exp
- mkShowbPrec :: Name -> Q Exp
- mkShowbList :: Name -> Q Exp
- mkPrint :: Name -> Q Exp
- mkPrintLazy :: Name -> Q Exp
- mkHPrint :: Name -> Q Exp
- mkHPrintLazy :: Name -> Q Exp
- data PragmaOptions = PragmaOptions {
- inlineShowbPrec :: Bool
- inlineShowb :: Bool
- inlineShowbList :: Bool
- specializeTypes :: [Q Type]
- defaultPragmaOptions :: PragmaOptions
- defaultInlineShowbPrec :: PragmaOptions
- defaultInlineShowb :: PragmaOptions
- defaultInlineShowbList :: PragmaOptions
deriveShow
deriveShow
automatically generates a Show
instance declaration for a data
type or newtype
. As an example:
{-# LANGUAGE TemplateHaskell #-} import Text.Show.Text.TH (deriveShow) data D a = Nullary | Unary Int | Product String Char a | Record { testOne :: Double , testTwo :: Bool , testThree :: D a } $(deriveShow
defaultOptions
''D)
D
now has a Show
instance analogous to what would be generated by a
deriving Show
clause.
Note that at the moment, there are a number of limitations to this approach:
deriveShow
does not support data families, so it is impossible to usederiveShow
withdata instance
s ornewtype instance
s.deriveShow
lacks the ability to properly detect data types with higher-kinded type parameters (e.g.,data HK f a = HK (f a)
). If you wish to deriveShow
instances for these data types, you will need to usemkShowbPrec
(see the documentation of themk
functions for more information).- Some data constructors have arguments whose
Show
instance depends on a typeclass besidesShow
. For example, considernewtype MyRatio a = MyRatio (Ratio a)
.
is aRatio
aShow
instance only ifa
is an instance of bothIntegral
andShow
. Unfortunately,deriveShow
cannot infer thata
must be an instance ofIntegral
, so it cannot create aShow
instance forMyRatio
. However, you can usemkShowbPrec
to get around this (see the documentation of themk
functions for more information).
Generates a Show
instance declaration for the given data
type or newtype
.
Since: 0.3
:: PragmaOptions | Specifies what pragmas to generate with this instance |
-> Name | Name of the data type to make an instance of |
-> Q [Dec] |
Generates a Show
instance declaration for the given data
type or newtype
.
You shouldn't need to use this function unless you know what you are doing.
Unlike deriveShow
, this function allows configuration of whether to inline
showbPrec
, showb
, or showbList
. It also allows for specializing instances
certain types. For example:
data ADT a = ADT a
$(deriveShowPragmas defaultInlineShowbPrec
{
specializeTypes = [t| Int |]
}
''ADT)
This declararation would produce code like this:
instance Show a => Show (ADT a) where {-# INLINE showbPrec #-} {-# SPECIALIZE instance Show (ADT Int) #-} showbPrec = ...
Since: 0.5
mk
functions
There may be scenarios in which you want to show an arbitrary data
type or newtype
without having to make the type an instance of Show
. For these cases,
Text.Show.Text.TH provide several functions (all prefixed with mk
) that splice
the appropriate lambda expression into your source code.
As an example, suppose you have data ADT = ADTCon
, which is not an instance of Show
.
With mkShow
, you can still convert it to Text
:
{-# LANGUAGE OverloadedStrings, TemplateHaskell #-} whichADT :: Bool whichADT = $(mkShow ''ADT) ADTCon == "ADT"
mk
functions are also useful for creating Show
instances for data types with
sophisticated type parameters. For example, deriveShow
cannot infer the correct type
context for newtype HigherKinded f a = HigherKinded (f a)
, since f
is a
higher-kinded type parameter. However, it is still possible to derive a Show
instance for HigherKinded
without too much trouble using mkShowbPrec
:
{-# LANGUAGE TemplateHaskell #-} instance Show (f a) => Show (HigherKinded f a) where showbPrec = $(mkShowbPrec ''HigherKinded)
mkShow :: Name -> Q Exp Source
Generates a lambda expression which converts the given data
type or newtype
to a strict Text
.
Since: 0.3.1
mkShowLazy :: Name -> Q Exp Source
Generates a lambda expression which converts the given data
type or newtype
to a lazy Text
.
Since: 0.3.1
mkShowPrec :: Name -> Q Exp Source
Generates a lambda expression which converts the given data
type or newtype
to a strict Text
with the given precedence.
Since: 0.3.1
mkShowPrecLazy :: Name -> Q Exp Source
Generates a lambda expression which converts the given data
type or newtype
to a lazy Text
with the given precedence.
Since: 0.3.1
mkShowList :: Name -> Q Exp Source
Generates a lambda expression which converts the given list of data
types or
newtype
s to a strict Text
in which the values are surrounded by square
brackets and each value is separated by a comma.
Since: 0.5
mkShowListLazy :: Name -> Q Exp Source
Generates a lambda expression which converts the given list of data
types or
newtype
s to a lazy Text
in which the values are surrounded by square
brackets and each value is separated by a comma.
Since: 0.5
mkShowb :: Name -> Q Exp Source
Generates a lambda expression which converts the given data
type or newtype
to a Builder
.
Since: 0.3.1
mkShowbPrec :: Name -> Q Exp Source
Generates a lambda expression which converts the given data
type or newtype
to a Builder
with the given precedence.
Since: 0.3.1
mkShowbList :: Name -> Q Exp Source
Generates a lambda expression which converts the given list of data
types or
newtype
s to a Builder
in which the values are surrounded by square brackets
and each value is separated by a comma.
Since: 0.5
mkPrint :: Name -> Q Exp Source
Generates a lambda expression which writes the given data
type or newtype
argument's strict Text
output to the standard output, followed by a newline.
Since: 0.3.1
mkPrintLazy :: Name -> Q Exp Source
Generates a lambda expression which writes the given data
type or newtype
argument's lazy Text
output to the standard output, followed by a newline.
Since: 0.3.1
mkHPrint :: Name -> Q Exp Source
Generates a lambda expression which writes the given data
type or newtype
argument's strict Text
output to the given file handle, followed by a newline.
Since: 0.3.1
mkHPrintLazy :: Name -> Q Exp Source
Generates a lambda expression which writes the given data
type or newtype
argument's lazy Text
output to the given file handle, followed by a newline.
Since: 0.3.1
Advanced pragma options
data PragmaOptions Source
Options that specify what INLINE
or SPECIALIZE
pragmas to generate with
a Show
instance.
Since: 0.5
PragmaOptions | |
|
defaultPragmaOptions :: PragmaOptions Source
Do not generate any pragmas with a Show
instance.
Since: 0.5