TextShow

Efficiently convert from values to Text via Builders.

Since: 2

The TextShow classes

TextShow

class TextShow a where

Conversion of values to Text. Because there are both strict and lazy Text variants, the TextShow class deliberately avoids using Text in its functions. Instead, showbPrec, showb, and showbList all return Builder, an efficient intermediate form that can be converted to either kind of Text.

Builder is a Monoid, so it is useful to use the mappend (or <>) function to combine Builders when creating TextShow instances. As an example:

import Data.Monoid
import TextShow

data Example = Example Int Int
instance TextShow Example where
    showb (Example i1 i2) = showb i1 <> showbSpace <> showb i2

If you do not want to create TextShow instances manually, you can alternatively use the TextShow.TH module to automatically generate default TextShow instances using Template Haskell, or the TextShow.Generic module to quickly define TextShow instances using genericShowbPrec.

Since: 2

Minimal complete definition

showbPrec | showb

Methods

showbPrec

Arguments

:: Int

The operator precedence of the enclosing context (a number from 0 to 11). Function application has precedence 10.

-> a

The value to be converted to a Builder.

-> Builder

Convert a value to a Builder with the given predence.

Since: 2

showb

Arguments

:: a

The value to be converted to a Builder.

-> Builder

Converts a value to a strict Text. If you hand-define this, it should satisfy:

showb = showbPrec 0

Since: 2

showbList

Arguments

:: [a]

The list of values to be converted to a Builder.

-> Builder

Converts a list of values to a Builder. By default, this is defined as 'showbList = showbListWith showb, but it can be overridden to allow for specialized displaying of lists (e.g., lists of Chars).

Since: 2

showtPrec

Arguments

:: Int

The operator precedence of the enclosing context (a number from 0 to 11). Function application has precedence 10.

-> a

The value to be converted to a strict Text.

-> Text

Converts a value to a strict Text with the given precedence. This can be overridden for efficiency, but it should satisfy:

showtPrec p = toStrict . showtlPrec p

Since: 3

showt

Arguments

:: a

The value to be converted to a strict Text.

-> Text

Converts a value to a strict Text. This can be overridden for efficiency, but it should satisfy:

showt = toStrict . showtl

Since: 3

showtList

Arguments

:: [a]

The list of values to be converted to a strict Text.

-> Text

Converts a list of values to a strict Text. This can be overridden for efficiency, but it should satisfy:

showtList = toStrict . showtlList

Since: 3

showtlPrec

Arguments

:: Int

The operator precedence of the enclosing context (a number from 0 to 11). Function application has precedence 10.

-> a

The value to be converted to a lazy Text.

-> Text

Converts a value to a lazy Text with the given precedence. This can be overridden for efficiency, but it should satisfy:

showtlPrec p = toLazyText . showbPrec p

Since: 3

showtl

Arguments

:: a

The value to be converted to a lazy Text.

-> Text

Converts a value to a lazy Text. This can be overridden for efficiency, but it should satisfy:

showtl = toLazyText . showb

Since: 3

showtlList

Arguments

:: [a]

The list of values to be converted to a lazy Text.

-> Text

Converts a list of values to a lazy Text. This can be overridden for efficiency, but it should satisfy:

showtlList = toLazyText . showbList

Since: 3

Instances

TextShow ConType

TextShow a => TextShow (FromTextShow a)

Show a => TextShow (FromStringShow a)

(TextShow1 f, TextShow a) => TextShow (FromTextShow1 * f a)

(TextShow2 f, TextShow a, TextShow b) => TextShow (FromTextShow2 * * f a b)

showbParen :: Bool -> Builder -> Builder

Surrounds Builder output with parentheses if the Bool parameter is True.

Since: 2

showbSpace :: Builder

Construct a Builder containing a single space character.

Since: 2

TextShow1

class TextShow1 f where

Lifting of the TextShow class to unary type constructors.

Since: 2

Minimal complete definition

liftShowbPrec

Methods

liftShowbPrec :: (Int -> a -> Builder) -> ([a] -> Builder) -> Int -> f a -> Builder

showbPrec function for an application of the type constructor based on showbPrec and showbList functions for the argument type.

Since: 3

liftShowbList :: (Int -> a -> Builder) -> ([a] -> Builder) -> [f a] -> Builder

showbList function for an application of the type constructor based on showbPrec and showbList functions for the argument type. The default implementation using standard list syntax is correct for most types.

Since: 3

Instances

TextShow1 FromTextShow

TextShow1 FromStringShow

TextShow1 f => TextShow1 (FromTextShow1 * f)

(TextShow2 f, TextShow a) => TextShow1 (FromTextShow2 * * f a)

showbPrec1 :: (TextShow1 f, TextShow a) => Int -> f a -> Builder

Lift the standard showbPrec and showbList functions through the type constructor.

Since: 2

showbUnaryWith :: (Int -> a -> Builder) -> Builder -> Int -> a -> Builder

showbUnaryWith sp n p x produces the Builder representation of a unary data constructor with name n and argument x, in precedence context p, using the function sp to show occurrences of the type argument.

Since: 2

TextShow2

class TextShow2 f where

Lifting of the TextShow class to binary type constructors.

Since: 2

Minimal complete definition

liftShowbPrec2

Methods

liftShowbPrec2 :: (Int -> a -> Builder) -> ([a] -> Builder) -> (Int -> b -> Builder) -> ([b] -> Builder) -> Int -> f a b -> Builder

showbPrec function for an application of the type constructor based on showbPrec and showbList functions for the argument types.

Since: 3

liftShowbList2 :: (Int -> a -> Builder) -> ([a] -> Builder) -> (Int -> b -> Builder) -> ([b] -> Builder) -> [f a b] -> Builder

showbList function for an application of the type constructor based on showbPrec and showbList functions for the argument types. The default implementation using standard list syntax is correct for most types.

Since: 3

Instances

TextShow2 f => TextShow2 (FromTextShow2 * * f)

showbPrec2 :: (TextShow2 f, TextShow a, TextShow b) => Int -> f a b -> Builder

Lift two showbPrec functions through the type constructor.

Since: 2

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

showbBinaryWith sp n p x y produces the Builder representation of a binary data constructor with name n and arguments x and y, in precedence context p, using the functions sp1 and sp2 to show occurrences of the type arguments.

Since: 2

Builders

The Builder type

data Builder :: *

A Builder is an efficient way to build lazy Text values. There are several functions for constructing builders, but only one to inspect them: to extract any data, you have to turn them into lazy Text values using toLazyText.

Internally, a builder constructs a lazy Text by filling arrays piece by piece. As each buffer is filled, it is 'popped' off, to become a new chunk of the resulting lazy Text. All this is hidden from the user of the Builder.

Instances

Eq Builder

Ord Builder

Show Builder

IsString Builder

Monoid Builder

Semigroup Builder

toText :: Builder -> Text

Convert a Builder to a strict Text.

Since: 2

toLazyText :: Builder -> Text

O(n). Extract a lazy Text from a Builder with a default buffer size. The construction work takes place if and when the relevant part of the lazy Text is demanded.

toLazyTextWith :: Int -> Builder -> Text

O(n). Extract a lazy Text from a Builder, using the given size for the initial buffer. The construction work takes place if and when the relevant part of the lazy Text is demanded.

If the initial buffer is too small to hold all data, subsequent buffers will be the default buffer size.

toString :: Builder -> String

Convert a Builder to a String (without surrounding it with double quotes, as show would).

Since: 2

Constructing Builders

singleton :: Char -> Builder

O(1). A Builder taking a single character, satisfying

• toLazyText (singleton c) = singleton c

fromText :: Text -> Builder

O(1). A Builder taking a Text, satisfying

• toLazyText (fromText t) = fromChunks [t]

fromLazyText :: Text -> Builder

O(1). A Builder taking a lazy Text, satisfying

• toLazyText (fromLazyText t) = t

fromString :: String -> Builder

O(1). A Builder taking a String, satisfying

• toLazyText (fromString s) = fromChunks [S.pack s]

Flushing the buffer state

flush :: Builder

O(1). Pop the strict Text we have constructed so far, if any, yielding a new chunk in the result lazy Text.

Builder utility functions

lengthB :: Builder -> Int64

Computes the length of a Builder.

Since: 2

unlinesB :: [Builder] -> Builder

Merges several Builders, separating them by newlines.

Since: 2

unwordsB :: [Builder] -> Builder

Merges several Builders, separating them by spaces.

Since: 2

Printing values

printT :: TextShow a => a -> IO ()

Writes a value's strict Text representation to the standard output, followed by a newline.

Since: 2

printTL :: TextShow a => a -> IO ()

Writes a value's lazy Text representation to the standard output, followed by a newline.

Since: 2

hPrintT :: TextShow a => Handle -> a -> IO ()

Writes a value's strict Text representation to a file handle, followed by a newline.

Since: 2

hPrintTL :: TextShow a => Handle -> a -> IO ()

Writes a value's lazy Text representation to a file handle, followed by a newline.

Since: 2

Conversion between TextShow and string Show

newtype FromStringShow a

The TextShow instance for FromStringShow is based on its String Show instance. That is,

showbPrec p (FromStringShow x) = showsToShowb showsPrec p x

Since: 2

Constructors

FromStringShow

Fields

fromStringShow :: a

Instances

Functor FromStringShow

Foldable FromStringShow

Traversable FromStringShow

Generic1 FromStringShow

Show1 FromStringShow

TextShow1 FromStringShow

Eq a => Eq (FromStringShow a)

Data a => Data (FromStringShow a)

Ord a => Ord (FromStringShow a)

Read a => Read (FromStringShow a)

Show a => Show (FromStringShow a)

Generic (FromStringShow a)

Lift a0 => Lift (FromStringShow a)

Show a => TextShow (FromStringShow a)

type Rep1 FromStringShow

type Rep (FromStringShow a)

newtype FromTextShow a

The String Show instance for FromTextShow is based on its TextShow instance. That is,

showsPrec p (FromTextShow x) = showbToShows showbPrec p x

Since: 2

Constructors

FromTextShow

Fields

fromTextShow :: a

Instances

Functor FromTextShow

Foldable FromTextShow

Traversable FromTextShow

Generic1 FromTextShow

Show1 FromTextShow

TextShow1 FromTextShow

Eq a => Eq (FromTextShow a)

Data a => Data (FromTextShow a)

Ord a => Ord (FromTextShow a)

Read a => Read (FromTextShow a)

TextShow a => Show (FromTextShow a)

Generic (FromTextShow a)

Lift a0 => Lift (FromTextShow a)

TextShow a => TextShow (FromTextShow a)

type Rep1 FromTextShow

type Rep (FromTextShow a)

newtype FromStringShow1 f a

The TextShow1 instance for FromStringShow1 is based on its String Show1 instance. That is,

liftShowbPrec sp sl p (FromStringShow1 x) =
    showsPrecToShowbPrec (liftShowsPrec (showbPrecToShowsPrec sp)
                                            (showbToShows         sl))
                           p x

Since: 3

Constructors

FromStringShow1

Fields

fromStringShow1 :: f a

Instances

Functor f => Functor (FromStringShow1 * f)

Foldable f => Foldable (FromStringShow1 * f)

Traversable f => Traversable (FromStringShow1 * f)

Generic1 (FromStringShow1 * f)

Show1 f => Show1 (FromStringShow1 * f)

Eq (f a) => Eq (FromStringShow1 k f a)

(Data (f a), Typeable (* -> *) f, Typeable * a) => Data (FromStringShow1 * f a)

Ord (f a) => Ord (FromStringShow1 k f a)

Read (f a) => Read (FromStringShow1 k f a)

(Show1 f, Show a) => Show (FromStringShow1 * f a)

Generic (FromStringShow1 k f a)

Lift (f a) => Lift (FromStringShow1 k f a)

type Rep1 (FromStringShow1 k f)

type Rep (FromStringShow1 k f a)

newtype FromTextShow1 f a

The String Show1 instance for FromTextShow1 is based on its TextShow1 instance. That is,

liftShowsPrec sp sl p (FromTextShow1 x) =
    showbPrecToShowsPrec (liftShowbPrec (showsPrecToShowbPrec sp)
                                            (showsToShowb         sl))
                           p x

Since: 3

Constructors

FromTextShow1

Fields

fromTextShow1 :: f a

Instances

Functor f => Functor (FromTextShow1 * f)

Foldable f => Foldable (FromTextShow1 * f)

Traversable f => Traversable (FromTextShow1 * f)

Generic1 (FromTextShow1 * f)

TextShow1 f => Show1 (FromTextShow1 * f)

TextShow1 f => TextShow1 (FromTextShow1 * f)

Eq (f a) => Eq (FromTextShow1 k f a)

(Data (f a), Typeable (* -> *) f, Typeable * a) => Data (FromTextShow1 * f a)

Ord (f a) => Ord (FromTextShow1 k f a)

Read (f a) => Read (FromTextShow1 k f a)

Generic (FromTextShow1 k f a)

Lift (f a) => Lift (FromTextShow1 k f a)

(TextShow1 f, TextShow a) => TextShow (FromTextShow1 * f a)

type Rep1 (FromTextShow1 k f)

type Rep (FromTextShow1 k f a)

newtype FromStringShow2 f a b

The TextShow2 instance for FromStringShow2 is based on its String Show2 instance. That is,

liftShowbPrec2 sp1 sl1 sp2 sl2 p (FromStringShow2 x) =
    showsPrecToShowbPrec (liftShowsPrec2 (showbPrecToShowsPrec sp1)
                                             (showbToShows         sl1)
                                             (showbPrecToShowsPrec sp2)
                                             (showbToShows         sl2))
                           p x

Since: 3

Constructors

FromStringShow2

Fields

fromStringShow2 :: f a b

Instances

Bifunctor f0 => Bifunctor (FromStringShow2 * * f)

Bitraversable f0 => Bitraversable (FromStringShow2 * * f)

Bifoldable f0 => Bifoldable (FromStringShow2 * * f)

Functor (f a) => Functor (FromStringShow2 k * f a)

Foldable (f a) => Foldable (FromStringShow2 k * f a)

Traversable (f a) => Traversable (FromStringShow2 k * f a)

Generic1 (FromStringShow2 k * f a)

Eq (f a b) => Eq (FromStringShow2 k k f a b)

(Data (f a b), Typeable (* -> * -> *) f, Typeable * a, Typeable * b) => Data (FromStringShow2 * * f a b)

Ord (f a b) => Ord (FromStringShow2 k k f a b)

Read (f a b) => Read (FromStringShow2 k k f a b)

Generic (FromStringShow2 k k f a b)

Lift (f a b) => Lift (FromStringShow2 k k f a b)

type Rep1 (FromStringShow2 k k1 f a)

type Rep (FromStringShow2 k k1 f a b)

newtype FromTextShow2 f a b

The String Show2 instance for FromTextShow2 is based on its TextShow2 instance. That is,

liftShowsPrec2 sp1 sl1 sp2 sl2 p (FromTextShow2 x) =
    showbPrecToShowsPrec (liftShowbPrec2 (showsPrecToShowbPrec sp1)
                                             (showsToShowb         sl1)
                                             (showsPrecToShowbPrec sp2)
                                             (showsToShowb         sl2))
                           p x

Since: 3

Constructors

FromTextShow2

Fields

fromTextShow2 :: f a b

Instances

Bifunctor f0 => Bifunctor (FromTextShow2 * * f)

Bitraversable f0 => Bitraversable (FromTextShow2 * * f)

Bifoldable f0 => Bifoldable (FromTextShow2 * * f)

TextShow2 f => TextShow2 (FromTextShow2 * * f)

Functor (f a) => Functor (FromTextShow2 k * f a)

Foldable (f a) => Foldable (FromTextShow2 k * f a)

Traversable (f a) => Traversable (FromTextShow2 k * f a)

Generic1 (FromTextShow2 k * f a)

(TextShow2 f, TextShow a) => TextShow1 (FromTextShow2 * * f a)

Eq (f a b) => Eq (FromTextShow2 k k f a b)

(Data (f a b), Typeable (* -> * -> *) f, Typeable * a, Typeable * b) => Data (FromTextShow2 * * f a b)

Ord (f a b) => Ord (FromTextShow2 k k f a b)

Read (f a b) => Read (FromTextShow2 k k f a b)

Generic (FromTextShow2 k k f a b)

Lift (f a b) => Lift (FromTextShow2 k k f a b)

(TextShow2 f, TextShow a, TextShow b) => TextShow (FromTextShow2 * * f a b)

type Rep1 (FromTextShow2 k k1 f a)

type Rep (FromTextShow2 k k1 f a b)

showsPrecToShowbPrec :: (Int -> a -> ShowS) -> Int -> a -> Builder

Convert a precedence-aware ShowS-based show function to a Builder-based one.

Since: 3

showsToShowb :: (a -> ShowS) -> a -> Builder

Convert a ShowS-based show function to a Builder-based one.

Since: 3

showbPrecToShowsPrec :: (Int -> a -> Builder) -> Int -> a -> ShowS

Convert a precedence-aware Builder-based show function to a ShowS-based one.

Since: 3

showbToShows :: (a -> Builder) -> a -> ShowS

Convert a Builder-based show function to a ShowS-based one.

Since: 3