For general description, see README.

General syntax of formatting strings is taken from Python's string.format, see python documentation. Shortly speaking, variable substitutions are denoted by braces ({}).

There are several ways of how variable placeholders can be matched with provided values:

• If you place just empty braces {}, this will refer to variables by position. All empty placeholders are automatically numbered starting from 0; so for example {}, {}, {} is exactly the same as {0}, {1}, {2}.
• You can number placeholders by yourself.
• You can place numbered placeholders in any order you want.
• You can give names to your placeholders, like in Hello, {name}!. Only alphanumeric names are valid for now.
• You can use one variable several times, or not use it at all.
• Numbered placeholders will work for variable containers that address their contents by index, including Single, tuples and lists.
• Named placeholders will work for variable containers that address their contents by name, including [(Text, a)], Map Text a.

Internal structure of string format is described by data type Format. It is possible to parse Format from a string using some another syntax.

There are more than one commonly used formatting string syntaxes. In the module Data.Text.Format.Parse.Shell another widely used syntax is defined. In this shell-like syntax, variable substitution is defined by the dollar sign: "Hello, $name!". It is possible to use braces, like in shell: "Hello, ${name}!". Numbered and automatically numbered placeholders are also supported.

For each placeholder, you can specify formatting rules for variable which will be placed there, after the colon in the braces. Valid examples are {1:8.4}, {:>8}.

Exact syntax of variable format specification depends on type of variable which you are going to use. If you specify format incorrectly, there will be an error.

This syntax can be used for integers, floats and strings:

[[fill]align][sign][#][width][.precision][radix][~convert]

where:

• fill - padding character (space by default)
• align - alignment indicator (<, >, or ^)
• sign - when to show number's sign (+, -, or space)
• # - if specified, then for hexadecimal numbers the leading 0x will be added
• width - minimum length of the field
• precision - number of decimal places after point, for floating-point numbers
• radix - h or x for hexadecimal, d for decimal (default).
• convert - text conversion. Supported are: u - make upper case, l - make lower case, t - make title case (captialize all words). This is supported only for string variables.

Valid examples are:

format "hex: {:#x}" (Single 17) ==> "hex: 0x11"
format "center: <{0:^10}>" (Single "hello") ==> "center: <   hello  >"
format "float: {:+6.4}" (Single 2.718281828) ==> "float: +2.7183"
format "capitalization: {:~t}" (Single "hello world") ==> "capitalization: Hello World"

For Bool values, there is special format syntax:

true:false

where "true" is what you want to see for True and "false" is what you want to see for False. Colon can be replaced with semicolon or comma.

Valid examples are:

format "default: {}" (Single True) ==> "default: true"
format "enable: {:yes:no}" (Single False) ==> "enable: no"

For Maybe a values, there is special format syntax supported:

someformat|nothing

where someformat is the format specification for a, and nothing is a string which you want to see for Nothing. If |nothing part is not specified, then Nothing value will be rendered as empty string.

Valid examples are:

format "Value: {:.3|<undefined>}." (Single 2.718281828) ==> "Value: 2.718."
format "Value: {:.3|<undefined>}." (Single (Nothing :: Maybe Float)) ==> "Value: <undefined>."
format "Value: {:.3}." (Single (Nothing :: Maybe Float)) ==> "Value: ."

For time/date types from Data.Time, there is special syntax defined in Data.Time.Format.

Valid examples are:

format "time: {:%H:%M:%S}" (Single time) ==> "time: 19:06:01"
format "time: {:%H:%M:%S %Z}" (Single time) ==> "time: 19:06:01 YEKT"
format "default: {}" (Single time) ==> "default: Sat,  3 Jun 2017 19:06:00 YEKT"