text-show-2.1.1: Efficient conversion of values into Text

Copyright(C) 2014-2015 Ryan Scott
LicenseBSD-style (see the file LICENSE)
MaintainerRyan Scott
StabilityProvisional
PortabilityGHC
Safe HaskellNone
LanguageHaskell2010

TextShow

Contents

Description

Efficiently convert from values to Text via Builders.

Since: 2

Synopsis

The TextShow classes

TextShow

class TextShow a where Source

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 Source

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

-> Builder 

Convert a value to a Builder with the given predence.

Since: 2

showb :: a -> Builder Source

A specialized variant of showbPrec using precedence context zero.

Since: 2

showbList :: [a] -> Builder Source

Allows for specialized display of lists. This is used, for example, when showing lists of Chars.

Since: 2

showt :: TextShow a => a -> Text Source

Constructs a strict Text from a single value.

Since: 2

showtl :: TextShow a => a -> Text Source

Constructs a lazy Text from a single value.

Since: 2

showtPrec :: TextShow a => Int -> a -> Text Source

Constructs a strict Text from a single value with the given precedence.

Since: 2

showtlPrec :: TextShow a => Int -> a -> Text Source

Constructs a lazy Text from a single value with the given precedence.

Since: 2

showtList :: TextShow a => [a] -> Text Source

Construct a strict Text from a list of values.

Since: 2

showtlList :: TextShow a => [a] -> Text Source

Construct a lazy Text from a list of values.

Since: 2

showbParen :: Bool -> Builder -> Builder Source

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

Since: 2

showbSpace :: Builder Source

Construct a Builder containing a single space character.

Since: 2

TextShow1

class TextShow1 f where Source

Lifting of the TextShow class to unary type constructors.

Since: 2

Methods

showbPrecWith :: (Int -> a -> Builder) -> Int -> f a -> Builder Source

Lifts a showbPrec function through the type constructor.

Since: 2

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

Lift the standard showbPrec function through the type constructor.

Since: 2

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

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 Source

Lifting of the TextShow class to binary type constructors.

Since: 2

Methods

showbPrecWith2 :: (Int -> a -> Builder) -> (Int -> b -> Builder) -> Int -> f a b -> Builder Source

Lifts showbPrec functions through the type constructor.

Since: 2

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

Lift two showbPrec functions through the type constructor.

Since: 2

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

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.

toText :: Builder -> Text Source

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 Source

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

fromText :: Text -> Builder

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

fromLazyText :: Text -> Builder

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

fromString :: String -> Builder

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

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 Source

Computes the length of a Builder.

Since: 2

unlinesB :: [Builder] -> Builder Source

Merges several Builders, separating them by newlines.

Since: 2

unwordsB :: [Builder] -> Builder Source

Merges several Builders, separating them by spaces.

Since: 2

Printing values

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

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

Since: 2

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

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

Since: 2

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

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

Since: 2

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

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

Since: 2

Conversion between TextShow and string Show

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

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

Since: 2.1

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

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

Since: 2.1