Data.Text.Display

Use display to produce user-facing text

Documentation

display :: Display a => a -> Text

Convert a value to a readable Text.

Examples

>>> display 3
"3"

>>> display True
"True"

Since: 0.0.1.0

class Display a where

A typeclass for user-facing output.

Since: 0.0.1.0

Minimal complete definition

displayBuilder | displayPrec

Methods

displayBuilder :: a -> Builder

Implement this method to describe how to convert your value to Builder.

displayList :: [a] -> Builder

The method displayList is provided to allow for a specialised way to render lists of a certain value. This is used to render the list of Char as a string of characters enclosed in double quotes, rather than between square brackets and separated by commas.

Example

import qualified Data.Text.Lazy.Builder as TB

instance Display Char where
  displayBuilder c = TB.fromText $ T.singleton c
  displayList cs = TB.fromText $ T.pack cs

instance Display a => Display [a] where
  -- In this instance, 'displayBuilder' is defined in terms of 'displayList', which for most types
  -- is defined as the default written in the class declaration.
  -- But when a ~ Char, there is an explicit implementation that is selected instead, which
  -- provides the rendering of the character string between double quotes.
  displayBuilder = displayList

How implementations are selected

displayBuilder ([1,2,3] :: [Int])
→ displayBuilder @[Int] = displayBuilderList @Int
→ Default `displayList`

displayBuilder ("abc" :: [Char])
→ displayBuilder @[Char] = displayBuilderList @Char
→ Custom `displayList`

displayPrec

Arguments

:: Int

The precedence level passed in by the surrounding context

-> a

-> Builder

The method displayPrec allows you to write instances that require nesting. The precedence parameter can be thought of as a suggestion coming from the surrounding context for how tightly to bind. If the precedence parameter is higher than the precedence of the operator (or constructor, function, etc.) being displayed, then that suggests that the output will need to be surrounded in parentheses in order to bind tightly enough (see displayParen).

For example, if an operator constructor is being displayed, then the precedence requirement for its arguments will be the precedence of the operator. Meaning, if the argument binds looser than the surrounding operator, then it will require parentheses.

Note that function/constructor application has an effective precedence of 10.

Examples

instance Display a => Display (Maybe a) where
  -- In this instance, we define 'displayPrec' rather than 'displayBuilder' as we need to decide
  -- whether or not to surround ourselves in parentheses based on the surrounding context.
  -- If the precedence parameter is higher than 10 (the precedence of constructor application)
  -- then we indeed need to surround ourselves in parentheses to avoid malformed outputs
  -- such as @Just Just 5@.
  -- We then set the precedence parameter of the inner 'displayPrec' to 11, as even
  -- constructor application is not strong enough to avoid parentheses.
  displayPrec _ Nothing = "Nothing"
  displayPrec prec (Just a) = displayParen (prec > 10) $ "Just " <> displayPrec 11 a

data Pair a b = a :*: b
infix 5 :*: -- arbitrary choice of precedence
instance (Display a, Display b) => Display (Pair a b) where
  displayPrec prec (a :*: b) = displayParen (prec > 5) $ displayPrec 6 a <> " :*: " <> displayPrec 6 b

Instances

Display Void

Since: 0.0.3.0

Defined in Data.Text.Display

Methods

displayBuilder :: Void -> Builder

displayList :: [Void] -> Builder

displayPrec :: Int -> Void -> Builder

Display SomeException

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: SomeException -> Builder

displayList :: [SomeException] -> Builder

displayPrec :: Int -> SomeException -> Builder

Display IOException

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: IOException -> Builder

displayList :: [IOException] -> Builder

displayPrec :: Int -> IOException -> Builder

Display Int16

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: Int16 -> Builder

displayList :: [Int16] -> Builder

displayPrec :: Int -> Int16 -> Builder

Display Int32

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: Int32 -> Builder

displayList :: [Int32] -> Builder

displayPrec :: Int -> Int32 -> Builder

Display Int64

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: Int64 -> Builder

displayList :: [Int64] -> Builder

displayPrec :: Int -> Int64 -> Builder

Display Int8

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: Int8 -> Builder

displayList :: [Int8] -> Builder

displayPrec :: Int -> Int8 -> Builder

Display Word16

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: Word16 -> Builder

displayList :: [Word16] -> Builder

displayPrec :: Int -> Word16 -> Builder

Display Word32

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: Word32 -> Builder

displayList :: [Word32] -> Builder

displayPrec :: Int -> Word32 -> Builder

Display Word64

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: Word64 -> Builder

displayList :: [Word64] -> Builder

displayPrec :: Int -> Word64 -> Builder

Display Word8

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: Word8 -> Builder

displayList :: [Word8] -> Builder

displayPrec :: Int -> Word8 -> Builder

CannotDisplayByteStrings => Display ByteString

🚫 You should not try to display strict ByteStrings!

💡 Always provide an explicit encoding. Use decodeUtf8' or decodeUtf8With to convert from UTF-8

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: ByteString -> Builder

displayList :: [ByteString] -> Builder

displayPrec :: Int -> ByteString -> Builder

CannotDisplayByteStrings => Display ByteString

🚫 You should not try to display lazy ByteStrings!

💡 Always provide an explicit encoding. Use decodeUtf8' or decodeUtf8With to convert from UTF-8

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: ByteString -> Builder

displayList :: [ByteString] -> Builder

displayPrec :: Int -> ByteString -> Builder

Display Text

Strict Text

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: Text -> Builder

displayList :: [Text] -> Builder

displayPrec :: Int -> Text -> Builder

Display Text

Lazy Text

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: Text -> Builder

displayList :: [Text] -> Builder

displayPrec :: Int -> Text -> Builder

Display Integer

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: Integer -> Builder

displayList :: [Integer] -> Builder

displayPrec :: Int -> Integer -> Builder

Display ()

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: () -> Builder

displayList :: [()] -> Builder

displayPrec :: Int -> () -> Builder

Display Bool

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: Bool -> Builder

displayList :: [Bool] -> Builder

displayPrec :: Int -> Bool -> Builder

Display Char

displayList is overloaded, so that when the Display [a] instance calls displayList, we end up with a nice string instead of a list of chars between brackets.

>>> display [1, 2, 3]
"[1,2,3]"

>>> display ['h', 'e', 'l', 'l', 'o']
"hello"

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: Char -> Builder

displayList :: [Char] -> Builder

displayPrec :: Int -> Char -> Builder

Display Double

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: Double -> Builder

displayList :: [Double] -> Builder

displayPrec :: Int -> Double -> Builder

Display Float

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: Float -> Builder

displayList :: [Float] -> Builder

displayPrec :: Int -> Float -> Builder

Display Int

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: Int -> Builder

displayList :: [Int] -> Builder

displayPrec :: Int -> Int -> Builder

Display Word

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: Word -> Builder

displayList :: [Word] -> Builder

displayPrec :: Int -> Word -> Builder

Show e => Display (ShowInstance e)

This wrapper allows you to rely on a pre-existing Show instance in order to derive Display from it.

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: ShowInstance e -> Builder

displayList :: [ShowInstance e] -> Builder

displayPrec :: Int -> ShowInstance e -> Builder

Display a => Display (NonEmpty a)

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: NonEmpty a -> Builder

displayList :: [NonEmpty a] -> Builder

displayPrec :: Int -> NonEmpty a -> Builder

Display a => Display (Maybe a)

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: Maybe a -> Builder

displayList :: [Maybe a] -> Builder

displayPrec :: Int -> Maybe a -> Builder

Display a => Display [a]

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: [a] -> Builder

displayList :: [[a]] -> Builder

displayPrec :: Int -> [a] -> Builder

KnownSymbol str => Display (OpaqueInstance str a)

This wrapper allows you to create an opaque instance for your type, useful for redacting sensitive content like tokens or passwords.

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: OpaqueInstance str a -> Builder

displayList :: [OpaqueInstance str a] -> Builder

displayPrec :: Int -> OpaqueInstance str a -> Builder

CannotDisplayBareFunctions => Display (a -> b)

🚫 You should not try to display functions!

💡 Write a 'newtype' wrapper that represents your domain more accurately. If you are not consciously trying to use display on a function, make sure that you are not missing an argument somewhere.

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: (a -> b) -> Builder

displayList :: [a -> b] -> Builder

displayPrec :: Int -> (a -> b) -> Builder

(Display a, Display b) => Display (a, b)

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: (a, b) -> Builder

displayList :: [(a, b)] -> Builder

displayPrec :: Int -> (a, b) -> Builder

(Display a, Display b, Display c) => Display (a, b, c)

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: (a, b, c) -> Builder

displayList :: [(a, b, c)] -> Builder

displayPrec :: Int -> (a, b, c) -> Builder

(Display a, Display b, Display c, Display d) => Display (a, b, c, d)

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: (a, b, c, d) -> Builder

displayList :: [(a, b, c, d)] -> Builder

displayPrec :: Int -> (a, b, c, d) -> Builder

Deriving your instance automatically

newtype ShowInstance (a :: Type)

This wrapper allows you to rely on a pre-existing Show instance in order to derive Display from it.

Example

data AutomaticallyDerived = AD
 -- We derive 'Show'
 deriving stock Show
 -- We take advantage of the 'Show' instance to derive 'Display' from it
 deriving Display
   via (ShowInstance AutomaticallyDerived)

Since: 0.0.1.0

Constructors

ShowInstance a

Instances

Show a => Show (ShowInstance a)

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

showsPrec :: Int -> ShowInstance a -> ShowS

show :: ShowInstance a -> String

showList :: [ShowInstance a] -> ShowS

Show e => Display (ShowInstance e)

This wrapper allows you to rely on a pre-existing Show instance in order to derive Display from it.

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: ShowInstance e -> Builder

displayList :: [ShowInstance e] -> Builder

displayPrec :: Int -> ShowInstance e -> Builder

newtype OpaqueInstance (str :: Symbol) (a :: Type)

This wrapper allows you to create an opaque instance for your type, useful for redacting sensitive content like tokens or passwords.

Example

data UserToken = UserToken UUID
 deriving Display
   via (OpaqueInstance "[REDACTED]" UserToken)

display $ UserToken "7a01d2ce-31ff-11ec-8c10-5405db82c3cd"
"[REDACTED]"

Since: 0.0.1.0

Constructors

Opaque a

Instances

KnownSymbol str => Display (OpaqueInstance str a)

This wrapper allows you to create an opaque instance for your type, useful for redacting sensitive content like tokens or passwords.

Since: 0.0.1.0

Defined in Data.Text.Display

Methods

displayBuilder :: OpaqueInstance str a -> Builder

displayList :: [OpaqueInstance str a] -> Builder

displayPrec :: Int -> OpaqueInstance str a -> Builder

Writing your instance by hand

displayParen :: Bool -> Builder -> Builder

A utility function that surrounds the given Builder with parentheses when the Bool parameter is True. Useful for writing instances that may require nesting. See the displayPrec documentation for more information.

Since: 0.0.1.0

Design choices

A “Lawless Typeclass”

The Display typeclass does not contain any law. This is a controversial choice for some people, but the truth is that there are not any laws to ask of the consumer that are not already enforced by the type system and the internals of the Text type.

"🚫 You should not try to display functions!"

Sometimes, when using the library, you may encounter this message:

• 🚫 You should not try to display functions!
  💡 Write a 'newtype' wrapper that represents your domain more accurately.
     If you are not consciously trying to use `display` on a function,
     make sure that you are not missing an argument somewhere.

The display library does not allow the definition and usage of Display on bare function types ((a -> b)). Experience and time have shown that due to partial application being baked in the language, many users encounter a partial application-related error message when a simple missing argument to a function is the root cause.

There may be legitimate uses of a Display instance on a function type. But these usages are extremely dependent on their domain of application. That is why it is best to wrap them in a newtype that can better express and enforce the domain.

"🚫 You should not try to display ByteStrings!"

An arbitrary ByteStrings cannot be safely converted to text without prior knowledge of its encoding.

As such, in order to avoid dangerously blind conversions, it is recommended to use a specialised function such as decodeUtf8' or decodeUtf8With if you wish to turn a UTF8-encoded ByteString to Text.