formatting-6.3.2: Combinator-based type-safe formatting (like printf() or FORMAT)

Copyright(c) 2013 Chris Done 2013 Shachaf Ben-Kiki
LicenseBSD3
Maintainerchrisdone@gmail.com
Stabilityexperimental
PortabilityGHC
Safe HaskellNone
LanguageHaskell98

Formatting

Contents

Description

Combinator-based type-safe formatting (like printf() or FORMAT) for Text.

Example:

>>> format ("Person's name is " % text % ", age is " % hex) "Dave" 54

See Formatting.Formatters for a complete list of formatting combinators.

Synopsis

Documentation

data Format r a Source #

A formatter. When you construct formatters the first type parameter, r, will remain polymorphic. The second type parameter, a, will change to reflect the types of the data that will be formatted. For example, in

myFormat :: Formatter r (Text -> Int -> r)
myFormat = "Person's name is " % text % ", age is " % hex

the first type parameter remains polymorphic, and the second type parameter is Text -> Int -> r, which indicates that it formats a Text and an Int.

When you run the Format, for example with format, you provide the arguments and they will be formatted into a string.

> format ("Person's name is " % text % ", age is " % hex) "Dave" 54
"Person's name is Dave, age is 36"

Instances

Functor (Format r) Source #

Not particularly useful, but could be.

Methods

fmap :: (a -> b) -> Format r a -> Format r b #

(<$) :: a -> Format r b -> Format r a #

Category * Format Source #

The same as (%). At present using Category has an import overhead, but one day it might be imported as standard.

Methods

id :: cat a a #

(.) :: cat b c -> cat a b -> cat a c #

(~) * a r => IsString (Format r a) Source #

Useful instance for writing format string. With this you can write Foo instead of now "Foo!".

Methods

fromString :: String -> Format r a #

Semigroup (Format r (a -> r)) Source # 

Methods

(<>) :: Format r (a -> r) -> Format r (a -> r) -> Format r (a -> r) #

sconcat :: NonEmpty (Format r (a -> r)) -> Format r (a -> r) #

stimes :: Integral b => b -> Format r (a -> r) -> Format r (a -> r) #

Monoid (Format r (a -> r)) Source #

Useful instance for applying two formatters to the same input argument. For example: format (year <> "/" % month) now will yield "2015/01".

Methods

mempty :: Format r (a -> r) #

mappend :: Format r (a -> r) -> Format r (a -> r) -> Format r (a -> r) #

mconcat :: [Format r (a -> r)] -> Format r (a -> r) #

(%) :: Format r a -> Format r' r -> Format r' a infixr 9 Source #

Concatenate two formatters.

formatter1 % formatter2 is a formatter that accepts arguments for formatter1 and formatter2 and concatenates their results. For example

format1 :: Format r (Text -> r)
format1 = "Person's name is " % text
format2 :: Format r r
format2 = ", "
format3 :: Format r (Int -> r)
format3 = "age is " % hex
myFormat :: Formatter r (Text -> Int -> r)
myFormat = format1 % format2 % format3

Notice how the argument types of format1 and format3 are gathered into the type of myFormat.

(This is actually the composition operator for Format's Category instance, but that is (at present) inconvenient to use with regular Prelude. So this function is provided as a convenience.)

(%.) :: Format r (Builder -> r') -> Format r' a -> Format r a infixr 8 Source #

Function compose two formatters. Will feed the result of one formatter into another.

now :: Builder -> Format r r Source #

Don't format any data, just output a constant Builder.

later :: (a -> Builder) -> Format r (a -> r) Source #

Format a value of type a using a function of type a -> Builder. For example, later (f :: Int -> Builder) produces Format r (Int -> r).

mapf :: (a -> b) -> Format r (b -> t) -> Format r (a -> t) Source #

Functorial map over a formatter's input. Example: format (mapf (drop 1) string) "hello"

Top-level functions

runFormat :: Format r a -> (Builder -> r) -> a Source #

format :: Format Text a -> a Source #

Run the formatter and return a lazy Text value.

sformat :: Format Text a -> a Source #

Run the formatter and return a strict Text value.

bprint :: Format Builder a -> a Source #

Run the formatter and return a Builder value.

fprint :: Format (IO ()) a -> a Source #

Run the formatter and print out the text to stdout.

hprint :: Handle -> Format (IO ()) a -> a Source #

Run the formatter and put the output onto the given Handle.

Formatting library

Other functions

formatToString :: Format [Char] a -> a Source #

Run the formatter and return a list of characters.