Text.Show.Text.TH

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

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 use deriveShow with data instances or newtype instances.
• 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 derive Show instances for these data types, you will need to use mkShowbPrec (see the documentation of the mk functions for more information).
• Some data constructors have arguments whose Show instance depends on a typeclass besides Show. For example, consider newtype MyRatio a = MyRatio (Ratio a). Ratio a is a Show instance only if a is an instance of both Integral and Show. Unfortunately, deriveShow cannot infer that a must be an instance of Integral, so it cannot create a Show instance for MyRatio. However, you can use mkShowbPrec to get around this (see the documentation of the mk functions for more information).

deriveShow

Arguments

:: Name

Name of the data type to make an instance of Show

-> Q [Dec]

Generates a Show instance declaration for the given data type or newtype.

Since: 0.3

deriveShowPragmas

Arguments

:: PragmaOptions

Specifies what pragmas to generate with this instance

-> Name

Name of the data type to make an instance of Show

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

Generates a lambda expression which converts the given data type or newtype to a strict Text.

Since: 0.3.1

mkShowLazy :: Name -> Q Exp

Generates a lambda expression which converts the given data type or newtype to a lazy Text.

Since: 0.3.1

mkShowPrec :: Name -> Q Exp

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

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

Generates a lambda expression which converts the given list of data types or newtypes 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

Generates a lambda expression which converts the given list of data types or newtypes 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

Generates a lambda expression which converts the given data type or newtype to a Builder.

Since: 0.3.1

mkShowbPrec :: Name -> Q Exp

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

Generates a lambda expression which converts the given list of data types or newtypes 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

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

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

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

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

Options that specify what INLINE or SPECIALIZE pragmas to generate with a Show instance.

Since: 0.5

Constructors

PragmaOptions

Fields

inlineShowbPrec :: Bool

Whether to inline showbPrec

inlineShowb :: Bool

Whether to inline showb

inlineShowbList :: Bool

Whether to inline showbList

specializeTypes :: [Q Type]

Types for which to create specialized instance declarations

defaultPragmaOptions :: PragmaOptions

Do not generate any pragmas with a Show instance.

Since: 0.5

defaultInlineShowbPrec :: PragmaOptions

Inline the showbPrec function in a Show instance.

Since: 0.5

defaultInlineShowb :: PragmaOptions

Inline the showb function in a Show instance.

Since: 0.5

defaultInlineShowbList :: PragmaOptions

Inline the showbList function in a Show instance.

Since: 0.5