Concatenate, then convert.

build and concatenate, then convert.

Concatenate, then convert.

show and concatenate, then convert.

An old-style formatting function taken from text-format (see Data.Text.Format ). Unlike format from Data.Text.Format , it can produce String and strict Text as well (and print to console too). Also it's polyvariadic:

>>> format "{} + {} = {}" 2 2 4
2 + 2 = 4

You can use arbitrary formatters:

>>> format "0x{} + 0x{} = 0x{}" (hexF 130) (hexF 270) (hexF (130+270))
0x82 + 0x10e = 0x190

Like format , but adds a newline.

A format string. This is intentionally incompatible with other string types, to make it difficult to construct a format string by concatenating string fragments (a very common way to accidentally make code vulnerable to malicious data).

This type is an instance of IsString , so the easiest way to construct a query is to enable the OverloadedStrings language extension and then simply write the query in double quotes.

{-# LANGUAGE OverloadedStrings #-}

import Fmt

f :: Format
f = "hello {}"

The underlying type is Text , so literal Haskell strings that contain Unicode characters will be correctly handled.

fmt converts things to String , Text , ByteString 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.

pretty shows a value using its Buildable instance.

Like pretty , 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 a block of text.

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

The output will always end with a newline, even when the input doesn't.

Add a prefix to the first line, and indent all lines but the first one.

The output will always end with a newline, even when the input doesn't.

Attach a name to anything:

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

Put spaces between elements.

>>> fmt $ unwordsF ["hello", "world"]
hello world

Of course, it works on anything Buildable :

>>> fmt $ unwordsF [1, 2]
1 2

Arrange elements on separate lines.

>>> fmt $ unlinesF ["hello", "world"]
hello
world

A simple comma-separated list formatter.

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

For multiline output, use jsonListF .

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

For instance, to format a list of numbers as hex:

>>> listF' hexF [1234, 5678]
"[4d2, 162e]"

A multiline formatter for lists.

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

Multi-line elements are indented correctly:

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

A version of blockListF that lets you supply your own building function for list elements (instead of build ) and choose the bullet character (instead of "-" ).

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
]

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.

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

For multiline output, use jsonMapF .

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","foo\nbar","more test")
( test
,
  foo
  bar
,
  more test )

You can also use tupleF on lists to get tuple-like formatting.

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 :: Either Bool Int)
"<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"

padBothF 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):

>>> padBothF 5 '=' "foo"
"=foo="
>>> padBothF 5 '=' "foobar"
"foobar"

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

>>> padBothF 8 '=' "foo"
"===foo=="

Format a number or bytestring as hex:

>>> hexF 3635
"e33"
>>> hexF ("\0\50\63\80" :: BS.ByteString)
"00323f50"

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 smaller than 1e-6 or bigger-or-equal to 1e21 will be displayed using scientific notation:

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

Format a floating-point number using scientific notation, with the given amount of decimal places.

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

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

Note that it can only take a Builder (because otherwise it would be unusable with ( +| )-formatted strings which can resolve to any FromBuilder ). You can use build to convert any value to a Builder .

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

Format an arbitrary value without requiring a Buildable instance:

>>> data Foo = Foo { x :: Bool, y :: [Int] } deriving Generic

>>> fmt (genericF (Foo True [1,2,3]))
Foo:
  x: True
  y: [1, 2, 3]

It works for non-record constructors too:

>>> data Bar = Bar Bool [Int] deriving Generic

>>> fmtLn (genericF (Bar True [1,2,3]))
<Bar: True, [1, 2, 3]>

Any fields inside the type must either be Buildable or one of the following types:

• a function
• a tuple (up to 8-tuples)
• list, NonEmpty , Seq
• Map , IntMap , Set , IntSet
• Maybe , Either

The exact format of genericF might change in future versions, so don't rely on it. It's merely a convenience function.