Moduleformatting-7.2.0Haskell2010

Formatting

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

Example:

Example1 expression

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

See Formatting.Formatters for a list of formatters. See Formatting.Combinators for a list of formatting combinators, for combining and altering formatters.

1 type
18 values

Packageformatting-7.2.0
Exports19
LanguageHaskell2010
LicenceBSD-3-Clause
SourceFormatting.hs

newtypenewtype Format r a

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 :: Format 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"

Instances5Category, Functor, IsString, Semigroup, Monoid

Category FormatDefined in formatting-7.2.0 · Formatting.Internal
The same as (%). At present using Category has an import overhead, but one day it might be imported as standard.

Functor (Format r)Defined in formatting-7.2.0 · Formatting.Internal

This can be used almost like contramap, e.g:

formatter :: Format r (b -> r)
formatter = _

adapter :: a -> b
adapter = _

adapted :: Format r (a -> r)
adapted = fmap (. adapter) formatter

a ~ r => IsString (Format r a)Defined in formatting-7.2.0 · Formatting.Internal
Useful instance for writing format string. With this you can write "Foo" instead of now "Foo!".
Semigroup (Format r (a -> r))Defined in formatting-7.2.0 · Formatting.Internal
Monoid (Format r (a -> r))Defined in formatting-7.2.0 · Formatting.Internal
Useful instance for applying two formatters to the same input argument. For example: format (year <> "/" % month) now will yield "2015/01".

value(%) :: Format r a -> Format r' r -> Format r' a

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 :: Format 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 Formats Category instance, but that is (at present) inconvenient to use with regular Prelude. So this function is provided as a convenience.)

value(%+) :: Format r a -> Format r' r -> Format r' a

Concatenate two formatters with a space in between.

Example2 expressions

>>> :set -XOverloadedStrings>>> format (int %+ "+" %+ int %+ "=" %+ int) 2 3 5"2 + 3 = 5"

value(%.) :: Format r (Builder -> r') -> Format r' a -> Format r a

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

value(<%+>) :: Format r (a -> r) -> Format r (a -> r) -> Format r (a -> r)

Like (<>) except put a space between the two formatters. For example: format (year %+ month %+ dayOfMonth) now will yield "2022 06 06"

valuenow :: Builder -> Format r r

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

valuelater :: (a -> Builder) -> Format r (a -> r)

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

valuemapf :: (a -> b) -> Format r (b -> t) -> Format r (a -> t)

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

Top-level functions

11 declarations

valuerunFormat :: Format r a -> (Builder -> r) -> a

valueformat :: Format Text a -> a

Run the formatter and return a lazy Text value.

valuesformat :: Format Text a -> a

Run the formatter and return a strict Text value.

valuebprint :: Format Builder a -> a

Run the formatter and return a Builder value.

valuebformat :: Format Builder a -> a

Run the formatter and return a Builder value.

This is a newer synonym for bprint, following the naming convention set by format and sformat.

valuefprint :: MonadIO m => Format (m ()) a -> a

Run the formatter and print out the text to stdout.

valuefprintLn :: MonadIO m => Format (m ()) a -> a

Run the formatter and print out the text to stdout, followed by a newline.

valuehprint :: MonadIO m => Handle -> Format (m ()) a -> a

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

valuehprintLn :: MonadIO m => Handle -> Format (m ()) a -> a

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

valueformatToString :: Format String a -> a

Run the formatter and return a list of characters.

valueformatted :: FromBuilder t => (t -> o) -> Format o a -> a

Makes it easy to add formatting to any api that is expecting a builder, a strict or lazy text, or a string. It is essentially (flip runFormat), but with a more generous type due to the typeclass.

For example: >>> formatted TL.putStr ("x is: " % int % "n") 7 x is: 7 >>> formatted T.putStr ("x is: " % int % "n") 7 x is: 7 >>> formatted (id TL.Text) ("x is: " % int % "n") 7 "x is: 7n" >>> formatted (idT.Text) ("x is: " % int % "n") 7 "x is: 7n"

Formatting library

0 declarations

module Formatting.Formatters

module Formatting.Combinators