RIO export Builder as the ByteString builder so we have to hide it and provide this in its stead.

derive via this type if you have a Buildable and want to derive a corresponding Display instance

derive via this type if you have a Display type and want to derive a corresponding Buildable instance

Display the absolute value time span in seconds.

>>> secondsF 3 100
"100.000"

Display the absolute value time span in minutes.

>>> minutesF 3 150
"2.500"

Display the absolute value time span in hours.

>>> hoursF 3 3600
"1.000"

Display the absolute value time span in days.

>>> daysF 3 1518646845
"17576.931"

Display the absolute value time span in years.

>>> epochF t    -- time passed since Jan 1, 1970
"1518646845"
>>> yearsF 3 1518646845
"48.156"

Display a time span as one time relative to another. Input is assumed to be seconds. Typical inputs are NominalDiffTime and DiffTime.

>>> diffF False 100
"a minute"
>>> diffF True 100
"in a minute"

Week number of year, where weeks start on Monday (as mondayStartWeek), 00 - 53.

>>> weekOfYearMonF t
"07"

Day of week number, 0 (= Sunday) - 6 (= Saturday).

>>> dayOfWeekFromZeroF t
"3"

Week number of year, where weeks start on Sunday (as sundayStartWeek), 00 - 53.

>>> weekFromZeroF t
"06"

Day of week, long form (fst from wDays locale), Sunday - Saturday.

>>> dayNameF t
"Wednesday"

Day of week, short form (snd from wDays locale), Sun - Sat.

>>> dayNameShortF t
"Wed"

Day for Week Date format, 1 - 7.

>>> dayOfWeekF t
"3"

Week for Week Date format, 01 - 53.

>>> weekF t
"07"

Century (first two digits of year) for Week Date format, 00 - 99.

>>> weekCenturyF t
"20"

Last two digits of year for Week Date format, 00 - 99.

>>> weekYYF t
"18"

Year for Week Date format e.g. 2013.

>>> weekYearF t
"2018"

Day of year for Ordinal Date format, 001 - 366.

>>> dayF t
"045"

Day of month, leading space as needed, 1 - 31.

Day of month, 1st, 2nd, 25th, etc.

>>> dayOfMonthOrdF t
"14th"

Day of month, leading 0 as needed, 01 - 31.

>>> dayOfMonthF t
"14"

Month of year, leading 0 as needed, 01 - 12.

>>> monthF t
"02"

Month name, short form (snd from months locale), Jan - Dec.

>>> monthNameShortF t
"Feb"

Month name, long form (fst from months locale), January - December.

>>> monthNameF t
"February"

Century (being the first two digits of the year), 00 - 99.

>>> centuryF t
"20"

Last two digits of year, 00 - 99.

>>> yyF t
"18"

Year.

>>> yearF t
"2018"

As dateFmt locale (e.g. %m/%d/%y).

>>> dateSlashLF t
"02/14/18"

Same as %Y-%m-%d.

>>> dateDashF t
"2018-02-14"

Same as %m/%d/%y.

>>> dateSlashF t
"02/14/18"

Number of whole seconds since the Unix epoch. For times before the Unix epoch, this is a negative number. Note that in %s.%q and %s%Q the decimals are positive, not negative. For example, 0.9 seconds before the Unix epoch is formatted as -1.1 with %s%Q.

>>> epochF t
"1518646845"

Decimal point of the second. Up to 12 digits, without trailing zeros. For a whole number of seconds, this produces an empty string.

>>> subsecondF t
".5"

Picosecond, including trailing zeros, 000000000000 - 999999999999.

>>> picosecondF t
"500000000000"

Second, without decimal part, 00 - 60.

>>> secondF t
"45"

Minute, 00 - 59.

>>> minuteF t
"20"

Hour, 12-hour, leading space as needed, 1 - 12.

>>> hour12SF t
" 4"
>>> hour12SF midnight
"12"

Hour, 24-hour, leading space as needed, 0 - 23.

>>> hour24SF t
"16"
>>> hour24SF midnight
" 0"

Hour, 12-hour, leading 0 as needed, 01 - 12.

>>> hour12F t
"04"
>>> hour12F midnight
"12"

Hour, 24-hour, leading 0 as needed, 00 - 23.

>>> hour24F t
"16"
>>> hour24F midnight
"00"

Day half from (amPm locale), AM, PM.

>>> dayHalfUF t
"PM"

Day half from (amPm locale), converted to lowercase, am, pm.

>>> dayHalfF t
"pm"

As time12Fmt locale (e.g. %I:%M:%S %p).

>>> hmsPLF t
"04:20:45 PM"

As timeFmt locale (e.g. %H:%M:%S).

>>> hmsLF t
"16:20:45"

Same as %H:%M:%S.

>>> hmsF t
"16:20:45"

Same as %H:%M.

>>> hmF t
"16:20"

As dateTimeFmt locale (e.g. %a %b %e %H:%M:%S %Z %Y).

>>> dateTimeF t
"Wed Feb 14 16:20:45 CST 2018"

Timezone name.

>>> tzNameF t
"CST"

Timezone offset on the format -HHMM.

>>> t
2018-02-14 16:20:45.5 CST
>>> tzF t
"-0600"

Format time with an arbitrary formatting string. Other formatters in this module are implemented using timeF.

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=="

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.

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 format, but adds a newline.

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

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.

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 floating-point number without scientific notation:

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

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:

>>> 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 number in arbitrary base (up to 36):

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

Format a number as binary:

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

Format a number as octal:

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

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

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.

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=="

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"

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"

Take the last N characters:

>>> suffixF 3 "hello"
"llo"

Take the first N characters:

>>> prefixF 3 "hello"
"hel"

Format an Either:

>>> eitherF (Right 1 :: Either Bool Int)
"<Right: 1>"

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"

A version of jsonMapF 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 blockMapF 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 mapF that lets you supply your own building function for keys and values.

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 jsonListF 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
]

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 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 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 simple comma-separated list formatter.

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

For multiline output, use jsonListF.

Arrange elements on separate lines.

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

Put spaces between elements.

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

Of course, it works on anything Buildable:

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

Attach a name to anything:

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

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.

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.

Like pretty, but appends a newline.

pretty shows a value using its Buildable instance.

Like fmt, but appends a newline.

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!

show and concatenate, then convert.

Concatenate, then convert.

build and concatenate, then convert.

Concatenate, then convert.

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