A formatter. This type holds all the information we need to create a formatting function, wrapped up in a way that makes it easy to compose.

Build one of these up with primitives like s, string and int, join them together with <>, and when you're done, generate the final printing function with print.

Example

import Formatting exposing (..)


greeting =
    s "Hello " <> string <> s "!"


print greeting "Kris"


--> "Hello Kris!"

Creating Custom Formatters

Imagine you have an existing formatting rule you'd like to turn into a formatter:

tweetSummary : Int -> String -> String
tweetSummary starCount body =
    "(" ++ toString starCount ++ ") " ++ body

First, wrap the type signature in brackets:

tweetSummary : (Int -> String -> String)

Then change the result type to a variable. (That's where the magic begins - the Formatting library gets control of the final result type.):

tweetSummary : (Int -> String -> r)

Now add Format r to the start.

tweetSummary : Format r (Int -> String -> r)

All very mechanical. Now for the function body. Let's recall what it looked like at the start:

tweetSummary starCount body =
    "(" ++ toString starCount ++ ") " ++ body

Change that into an anonymous function:

tweetSummary =
    (\starCount body ->
        "(" ++ toString starCount ++ ") " ++ body
    )

Now add in a callback function as the first argument:

tweetSummary =
    (\callback starCount body ->
        "(" ++ toString starCount ++ ") " ++ body
    )

Pass your function's result to that callback (using <| is the easy way):

tweetSummary =
    (\callback starCount body ->
        callback <| "(" ++ toString starCount ++ ") " ++ body
    )

Finally, wrap that all up in a Format constructor:

tweetSummary =
    Format
        (\callback starCount body ->
            callback <| "(" ++ toString starCount ++ ") " ++ body
        )

And you're done. You have a composable formatting function. It's a mechanical process that's probably a bit weird at first, but easy to get used to.

Compose two formatters together.

Create a new formatter by applying a function to the output of this formatter.

For example:

import String exposing (toUpper)


format = s "Name: " <> map toUpper string

...produces a formatter that uppercases the name:

print format "Kris"


--> "Name: KRIS"

Create a new formatter by applying a function to the input of this formatter. The dual of map.

For example:

format = s "Height: " <> premap .height float

...produces a formatter that accesses a .height record field:

print format { height: 1.72 }


--> "Height: 1.72"

Apply an argument to a Formatter. Useful when you want to supply an argument, but don't yet want to convert your formatter to a plain ol' function (with print).

Turn your formatter into a function that's just waiting for its arguments.

Given this format:

orderFormat =
    s "FREE: " <> int <> s " x " <> string  <> s "!"

...we can either use it immediately:

order : String
order = print orderFormat 2 "Ice Cream"


--> "FREE: 2 x Ice Cream!"

...or turn it into an ordinary function to be used later:

orderFormatter : Int -> String -> String
orderFormatter =
    print orderFormat




...elsewhere...




order : String
order = orderFormatter 2 "Ice Cream"


--> "FREE: 2 x Ice Cream!"

Convenience function. Like print, but returns an Html.text node as its final result, instead of a String.

Hint: If you're using any formatters where whitespace is sigificant, you might well need one or both of these CSS rules:

font-family: monospace;
white-space: pre;

A boilerplate string.

A placeholder for a String argument.

A placeholder for an Int argument.

A placeholder for an Bool argument.

A placeholder for a Float argument.

A placeholder for any value that we can call toString on.

Eagle-eyed readers of the source will notice that we use this same function to define int and float, since toString gives us the right result for both of those types.

The sole difference is, int and float have more restrictive type signatures.

wrap one string with another. It's convenient for building strings like `"Invalid key '<keyname>'." For example:

print (wrap "'" string) "tester"


--> "'tester'"

String.pad lifted into the world of Formatters.

For example:

print (pad 10 '-' string) "KRIS"


--> "---KRIS---"

String.padLeft lifted into the world of Formatters.

For example:

print (padLeft 10 '_' float) 1.72


--> "______1.72"

String.padRight lifted into the world of Formatters.

For example:

print (padRight 10 '.' int) 789


--> "789......."

DEPRECATED: Use roundTo instead.

A float rounded to n decimal places.

Format a URI fragment.

For example:

print uriFragment "this string"


--> "this%20string"