fmt converts things to String, Text or Builder.

Most of the time you won't need it, as strings produced with (%<) and (>%) can already be used as String, Text, etc. However, combinators like listF can only produce Builder (for better type inference), and you need to use fmt on them.

Also, fmt can do printing:

>>> fmt "Hello world!\n"
Hello world!

Like fmt, but appends a newline.

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.

The class of types that can be rendered to a Builder.

Indent already formatted text.

>>> fmt $ "This is a list:\n" <> indent 4 (blockListF [1,2,3])
This is a list:
    - 1
    - 2
    - 3

Attach a name to anything:

>>> fmt $ nameF "clients" $ blockListF ["Alice", "Bob", "Zalgo"]
clients:
  - Alice
  - Bob
  - Zalgo

A simple comma-separated list formatter.

>>> listF ["hello", "world"]
"[hello, world]"

A version of listF that lets you supply your own building function for list elements.

For instance, to format a list of lists you'd have to do this (since there's no Buildable instance for lists):

>>> listF' listF [[1,2,3],[4,5,6]]
"[[1, 2, 3], [4, 5, 6]]"

A multiline formatter for lists.

>>> fmt $ blockListF [1,2,3]
- 1
- 2
- 3

It automatically handles multiline list elements:

>>> fmt $ blockListF ["hellonworld", "foonbarnquix"]
- hello
  world

- foo
  bar
  quix

A version of blockListF that lets you supply your own building function for list elements.

A JSON-style formatter for lists.

>>> fmt $ jsonListF [1,2,3]
[
  1
, 2
, 3
]

Like blockListF, it handles multiline elements well:

>>> fmt $ jsonListF ["hello\nworld", "foo\nbar\nquix"]
[
  hello
  world
, foo
  bar
  quix
]

(Note that, unlike blockListF, it doesn't add blank lines in such cases.)

A version of jsonListF that lets you supply your own building function for list elements.

A simple JSON-like map formatter; works for Map, HashMap, etc, as well as ordinary lists of pairs. Doesn't handle multiline elements (for that you need blockMapF or jsonMapF).

>>> mapF [("a", 1), ("b", 4)]
"{a: 1, b: 4}"

A version of mapF that lets you supply your own building function for keys and values.

A YAML-like map formatter:

>>> fmt $ blockMapF [("Odds", blockListF [1,3]), ("Evens", blockListF [2,4])]
Odds:
  - 1
  - 3
Evens:
  - 2
  - 4

A version of blockMapF that lets you supply your own building function for keys and values.

A JSON-like map formatter (unlike mapF, always multiline):

>>> fmt $ jsonMapF [("Odds", jsonListF [1,3]), ("Evens", jsonListF [2,4])]
{
  Odds:
    [
      1
    , 3
    ]
, Evens:
    [
      2
    , 4
    ]
}

A version of jsonMapF that lets you supply your own building function for keys and values.

Format a tuple (of up to 8 elements):

>>> tupleF (1,2,"hi")
"(1, 2, hi)"

If any of the elements takes several lines, an alternate format is used:

>>> fmt $ tupleF ("test","foonbar","more test")
( test
,
  foo
  bar
,
  more test )

Format a list like a tuple. (This function is used to define tupleF.)

Like build for Maybe, but displays Nothing as Nothing instead of an empty string.

build:

>>> build (Nothing :: Maybe Int)
""
>>> build (Just 1 :: Maybe Int)
"1"

maybeF:

>>> maybeF (Nothing :: Maybe Int)
"<Nothing>"
>>> maybeF (Just 1 :: Maybe Int)
"1"

Format an Either:

>>> eitherF (Right 1)
"<Right>: 1"

Take the first N characters:

>>> prefixF 3 "hello"
"hel"

Take the last N characters:

>>> suffixF 3 "hello"
"llo"

padLeftF n c pads the string with character c from the left side until it becomes n characters wide (and does nothing if the string is already that long, or longer):

>>> padLeftF 5 '0' 12
"00012"
>>> padLeftF 5 '0' 123456
"123456"

padRightF n c pads the string with character c from the right side until it becomes n characters wide (and does nothing if the string is already that long, or longer):

>>> padRightF 5 ' ' "foo"
"foo  "
>>> padRightF 5 ' ' "foobar"
"foobar"

padCenterF n c pads the string with character c from both sides until it becomes n characters wide (and does nothing if the string is already that long, or longer):

>>> padCenterF 5 '=' "foo"
"=foo="
>>> padCenterF 5 '=' "foobar"
"foobar"

When padding can't be distributed equally, the left side is preferred:

>>> padCenter 8 '=' "foo"
"===foo=="

Format a number or bytestring as hex:

>>> hexF 3635
"e33"

Convert a bytestring to base64:

>>> base64F ("\0\50\63\80" :: BS.ByteString)
"ADI/UA=="

Convert a bytestring to base64url (a variant of base64 which omits / and thus can be used in URLs):

>>> base64UrlF ("\0\50\63\80" :: BS.ByteString)
"ADI_UA=="

Add an ordinal suffix to a number:

>>> ordinalF 15
"15th"
>>> ordinalF 22
"22nd"

Break digits in a number:

>>> commaizeF 15830000
"15,830,000"

Format a number as octal:

>>> listF' octF [7,8,9,10]
"[7, 10, 11, 12]"

Format a number as binary:

>>> listF' binF [7,8,9,10]
"[111, 1000, 1001, 1010]"

Format a number in arbitrary base (up to 36):

>>> baseF 3 10000
"111201101"
>>> baseF 7 10000
"41104"
>>> baseF 36 10000
"7ps"

Format a floating-point number:

>>> floatF 3.1415
"3.1415"

Numbers bigger than 1e21 or smaller than 1e-6 will be displayed using scientific notation:

>>> listF' floatF [1e-6,9e-7]
"[0.000001, 9e-7]"
>>> listF' floatF [9e20,1e21]
"[900000000000000000000, 1e21]"

Format a floating-point number using scientific notation, with given amount of precision:

>>> listF' (exptF 5) [pi,0.1,10]
"[3.14159e0, 1.00000e-1, 1.00000e1]"

Format a floating-point number with given amount of precision.

For small numbers, it uses scientific notation for everything smaller than 1e-6:

listF' (precF 3) [1e-5,1e-6,1e-7]

"[0.0000100, 0.00000100, 1.00e-7]"

For large numbers, it uses scientific notation for everything larger than 1eN, where N is the precision:

listF' (precF 4) [1e3,5e3,1e4]

"[1000, 5000, 1.000e4]"

Format a floating-point number without scientific notation:

>>> listF' (fixedF 5) [pi,0.1,10]
"[3.14159, 0.10000, 10.00000]"

Display something only if the condition is True (empty string otherwise).

>>> "Hello!" <> whenF showDetails (", details: "%foobar%"")

Note that it can only take a Builder (because otherwise it would be unusable with (%<)-formatted strings which can resolve to any FromBuilder). Thus, use fmt if you need just one value:

>>> "Maybe here's a number: "%cond (fmt n)%""

Display something only if the condition is False (empty string otherwise).