Formatting.Combinators

Render a Maybe value either as a default (if Nothing) or using the given formatter:

>>> format (maybed "Goodbye" text) Nothing"Goodbye"

>>> format (maybed "Goodbye" text) (Just "Hello")"Hello"

Render the value in a Maybe using the given formatter, or produce an empty string:

>>> format (optioned text) Nothing""

>>> format (optioned text) (Just "Hello")"Hello"

Render the value in an Either:

>>> format (eithered text int) (Left "Error!")"Error!"

>>> format (eithered text int) (Right 69)"69"

Render the value in a Left with the given formatter, rendering a Right as an empty string:

>>> format (lefted text) (Left "bingo")"bingo"

>>> format (lefted text) (Right 16)""

Render the value in a Right with the given formatter, rendering a Left as an empty string:

>>> format (righted text) (Left 16)""

>>> format (righted text) (Right "bingo")"bingo"

Format each value in a list and concatenate them all:

>>> format (concatenated text) ["one", "two", "three"]"onetwothree"

>>> format (took 15 (concatenated bin)) [1..]"1101110010111011110001001101010111100110111101111"

Use the given text-joining function to join together the individually rendered items of a list.

>>> format (joinedWith (mconcat . reverse) int) [123, 456, 789]"789456123"

Format each value in a list and place the given string between each:

>>> fprintLn (intercalated "||" int) [1, 2, 3]1||2||3

Format each value in a list with spaces in between:

>>> format (unworded int) [1, 2, 3]"1 2 3"

Format each value in a list, placing each on its own line:

>>> fprint (unlined char) ['a'..'c']abc

Separate the formatted items of the Foldable (e.g. list) with spaces:

>>> format (spaced int) [1, 2, 3]"1 2 3"

Note that this behaviour is identical to unworded, it's just a different way of thinking about it.

Separate the formatted items of the Foldable (e.g. list) with commas:

>>> format (commaSep stext) ["one", "two", "three", "four", "five"]"one,two,three,four,five"

>>> format (took 5 (commaSep int)) [1..]"1,2,3,4,5"

Separate the formatted items of the Foldable (e.g. list) with commas and spaces:

>>> format (took 3 (commaSpaceSep ords)) [1..]"1st, 2nd, 3rd"

Add square brackets around the Foldable (e.g. a list), and separate each formatted item with a comma and space.

>>> format (list stext) ["one", "two", "three"]"[one, two, three]"

>>> format (list shown) ["one", "two", "three"]"[\"one\", \"two\", \"three\"]"

Like list, but also put double quotes around each rendered item:

>>> fprintLn (qlist stext) ["one", "two", "three"]["one", "two", "three"]

Take only the first n items from the list of items.

>>> format (took 7 (list bin)) [1..]"[1, 10, 11, 100, 101, 110, 111]"

>>> format (list bin) (take 7 [1..])"[1, 10, 11, 100, 101, 110, 111]"

Drop the first n items from the list of items.

>>> format (dropped 3 (list int)) [1..6]"[4, 5, 6]"

Split the formatted item in places the given predicated matches, and use the given list combinator to render the resultant list of strings (this function was sent to us from a parallel universe in which splat is the past participle of split, e.g. "whoops, I splat my pants").

>>> format (splat Data.Char.isSpace commaSpaceSep stext) "This\t  is\n\t\t  poorly formatted   ""This, , , is, , , , , poorly, formatted, , , "

Utility for taking a text-splitting function and turning it into a formatting combinator.

>>> format (splatWith (TL.chunksOf 3) list int) 1234567890"[123, 456, 789, 0]"

Split the formatted item at instances of the given string, and use the given list combinator to render the resultant list of strings.

>>> fprint (splatOn "," unlined text) "one,two,three"onetwothree

>>> fprint (splatOn "," (indentedLines 4) text) "one,two,three"    one    two    three

Split the formatted item into words and use the given list combinator to render the resultant list of strings.

>>> format (worded list text) "one  two three  ""[one, two, three]"

Split the formatted item into lines and use the given list combinator to render the resultant list of strings.

>>> fprintLn (lined qlist text) "one two three\n\nfour five six\nseven eight nine\n\n"["one two three", "", "four five six", "seven eight nine", ""]

Alter the formatted string with the given function.

>>> format (alteredWith Data.Text.Lazy.reverse int) 123456"654321"

Filter the formatted string to contain only characters which pass the given predicate:

>>> format (charsKeptIf Data.Char.isUpper text) "Data.Char.isUpper""DCU"

Filter the formatted string to not contain characters which pass the given predicate:

>>> format (charsRemovedIf Data.Char.isUpper text) "Data.Char.isUpper""ata.har.ispper"

Take a formatter and replace the given needle with the given replacement in its output.

>>> format (replaced "Bruce" "<redacted>" stext) "Bruce replied that Bruce's name was, in fact, '<redacted>'.""<redacted> replied that <redacted>'s name was, in fact, '<redacted>'."

Convert any letters in the output of the given formatter to upper-case.

>>> format (uppercased text) "I'm not shouting, you're shouting.""I'M NOT SHOUTING, YOU'RE SHOUTING."

Convert any letters in the output of the given formatter to lower-case.

>>> format (lowercased text) "Cd SrC/; Rm -Rf *""cd src/; rm -rf *"

Convert the formatted string to title case, or something like it:

>>> format (titlecased string) "the life of brian""The Life Of Brian"

Truncate the formatted string at the end so that it is no more than the given number of characters in length, placing an ellipsis at the end such that it does not exceed this length.

>>> format (ltruncated 5 text) "hello""hello"

>>> format (ltruncated 5 text) "hellos""he..."

Truncate the formatted string in the center, leaving the given number of characters at the start and end, and placing an ellipsis in between. The length will be no longer than `start + end + 3` characters long.

>>> format (ctruncated 15 4 text) "The quick brown fox jumps over the lazy dog.""The quick brown...dog."

>>> format (ctruncated 15 4 text) "The quick brown fox""The quick brown fox"

Truncate the formatted string at the start so that it is no more than the given number of characters in length, placing an ellipsis at the start such that it does not exceed this length.

>>> format (rtruncated 5 text) "hello""hello"

>>> format (rtruncated 5 text) "hellos""...os"

Pad the formatted string on the left with the given character to give it the given minimum width:

>>> format (lpadded 7 ' ' int) 1"      1"

>>> format (lpadded 7 ' ' int) 123456789"123456789"

Pad the formatted string on the right with the given character to give it the given minimum width:

>>> format (rpadded 7 ' ' int) 1"1      "

Pad the formatted string on the left and right with the given character to center it, giving it the given minimum width:

>>> format (cpadded 7 ' ' int) 1"   1   "

Format the item with a fixed width, padding with the given character on the left to extend, adding an ellipsis on the right to shorten:

>>> format (lfixed 10 ' ' int) 123"123       "

>>> format (lfixed 10 ' ' int) 1234567890"1234567890"

>>> format (lfixed 10 ' ' int) 123456789012345"1234567..."

Format the item with a fixed width, padding with the given character on the right to extend, adding an ellipsis on the right to shorten:

>>> format (rfixed 10 ' ' int) 123"       123"

>>> format (rfixed 10 ' ' int) 1234567890"1234567890"

>>> format (rfixed 10 ' ' int) 123456789012345"...9012345"

Format the item with a fixed width, padding with the given character on either side to extend, adding an ellipsis in the center to shorten.

The total length will be `l + r + 3` characters.

>>> format (cfixed 4 3 ' ' int) 123"    123   "

>>> format (cfixed 4 3 ' ' int) 1234567890"1234567890"

>>> format (cfixed 4 3 ' ' int) 123456789012345"1234...345"

Add the given prefix to the formatted item:

>>> format ("The answer is: " % prefixed "wait for it... " int) 42"The answer is: wait for it... 42"

>>> fprint (unlined (indented 4 (prefixed "- " int))) [1, 2, 3]    - 1    - 2    - 3

Add the given suffix to the formatted item.

Surround the output string with the given string:

>>> format (surrounded "***" string) "glue""***glue***"

Enclose the output string with the given strings:

>>> format (enclosed "<!--" "-->" text) "an html comment""<!--an html comment-->"

Add single quotes around the formatted item:

>>> let obj = Just Nothing in format ("The object is: " % squoted shown % ".") obj"The object is: 'Just Nothing'."

Add double quotes around the formatted item:

>>> fprintLn ("He said it was based on " % dquoted stext % ".") "science"He said it was based on "science".

Add parentheses around the formatted item:

>>> format ("We found " % parenthesised int % " discrepancies.") 17"We found (17) discrepancies."

>>> fprintLn (took 5 (list (parenthesised int))) [1..][(1), (2), (3), (4), (5)]

Add square brackets around the formatted item:

>>> format (squared int) 7"[7]"

Add curly brackets around the formatted item:

>>> format ("\\begin" % braced text) "section""\\begin{section}"

Add angle brackets around the formatted item:

>>> format (angled int) 7"<7>"

>>> format (list (angled text)) ["html", "head", "title", "body", "div", "span"]"[<html>, <head>, <title>, <body>, <div>, <span>]"

Add backticks around the formatted item:

>>> format ("Be sure to run " % backticked builder % " as root.") ":(){:|:&};:""Be sure to run `:(){:|:&};:` as root."

Insert the given number of spaces at the start of the rendered text:

>>> format (indented 4 int) 7"    7"

Note that this only indents the first line of a multi-line string. To indent all lines see reindented.

Format a list of items, placing one per line, indented by the given number of spaces.

>>> fprint ("The lucky numbers are:\n" % indentedLines 4 int) [7, 13, 1, 42]The lucky numbers are:    7    13    1    42

Indent each line of the formatted string by the given number of spaces:

>>> fprint (reindented 2 text) "one\ntwo\nthree"  one  two  three

Take a fractional number and round it before formatting it as the given Format:

>>> format (roundedTo int) 6.66"7">>> format (list (roundedTo int)) [10.66, 6.66, 1.0, 3.4]"[11, 7, 1, 3]"

Note: the type variable f will almost always be 'Format r', so the type of this function can be thought of as:

roundedTo :: (Integral i, RealFrac d) => Format r (i -> r) -> Format r (d -> r)

Take a fractional number and truncate it before formatting it as the given Format:

>>> format (truncatedTo int) 6.66"6">>> format (list (truncatedTo int)) [10.66, 6.66, 1.0, 3.4]"[10, 6, 1, 3]"

Note: the type variable f will almost always be 'Format r', so the type of this function can be thought of as:

truncatedTo :: (Integral i, RealFrac d) => Format r (i -> r) -> Format r (d -> r)

Take a fractional number and ceiling it before formatting it as the given Format:

>>> format (ceilingedTo int) 6.66"7">>> format (list (ceilingedTo int)) [10.66, 6.66, 1.0, 3.4]"[11, 7, 1, 4]"

Note: the type variable f will almost always be 'Format r', so the type of this function can be thought of as:

ceilingedTo :: (Integral i, RealFrac d) => Format r (i -> r) -> Format r (d -> r)

Take a fractional number and floor it before formatting it as the given Format:

>>> format (flooredTo int) 6.66"6">>> format (list (flooredTo int)) [10.66, 6.66, 1.0, 3.4]"[10, 6, 1, 3]"

Note: the type variable f will almost always be 'Format r', so the type of this function can be thought of as:

flooredTo :: (Integral i, RealFrac d) => Format r (i -> r) -> Format r (d -> r)

Use the given lens to view an item, formatting it with the given formatter.

You can think of this as having the type:

viewed :: Lens' s a -> Format r (a -> r) -> Format r (s -> r)

>>> format (viewed _1 int) (1, "hello")"1"

This is useful when combined with the Monoid instance for Format, because it allows us to give a data structure as an argument only once, and deconstruct it with the formatters:

data Person = Person
  { _personName :: Text
  , _personAge :: Int
  }
makeLenses ''Person

me :: Person
me = Person Alex 38

format ("The person's name is " % squoted (viewed personName text) % ", and their age is " <> viewed personAge int) me
"The person's name is Alex, and their age is 38"

Access an element of the structure and format it with the given formatter.

>>> format (accessed fst int) (1, "hello")"1"

Repeating the example from viewed:

format ("The person's name is " % squoted (accessed _personName text) % ", and their age is " <> accessed _personAge int) me "The person's name is Alex, and their age is 38"

Render an integer using binary notation with a leading 0b, padding with zeroes to the given width:

>>> format (binPrefix 16) 4097"0b0001000000000001"

Render an integer using octal notation with a leading 0o, padding with zeroes to the given width:

>>> format (octPrefix 16) 4097"0o0000000000010001"

Render an integer using octal notation with a leading 0x, padding with zeroes to the given width:

>>> format (hexPrefix 16) 4097"0x0000000000001001"