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 [-1.2,-12.2]
"[-1.2, -12.2]"
>>> 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.

A newtype for deriving a generic Buildable instance for any type using DerivingVia.

>>> :set -XDerivingVia
>>> :{
data Bar = Bar { x :: Bool, y :: [Int] }
  deriving stock Generic
  deriving Buildable via GenericBuildable Bar
:}

>>> pretty (Bar True [1,2,3])
Bar:
  x: True
  y: [1, 2, 3]