Formatting

This library is to write type safe formatter.

A formatter is function that formats a thing into an output. Eg if I have a record, and I want to convert it to a string, for printing.

The output can be other than string, eg I want to print to "html", say each show someone's first name as bold, and last name as grayed out.

import Formatting as F exposing ((<>))


type alias User =
    { first : String
    , last : String
    }


userFormat : F.Format User String
userFormat =
    (.first >> F.string) <> F.s " " <> (.last >> F.string)


user : User -> String
user =
    F.print userFormat

This library is heavily influenced by krisajenkins/formatting.

If you want to combine two formatted strings, use ++ or equivalent.

user : Format User String


date : Format Date String


user_date : User -> Date -> String
user_date u d =
    print user u ++ print date d

Format Constructors

These help us create type safe formatters. The formatters are of type Format a String, if you want a formatter of other kind, say Format a b, you will can use map function to convert. So the path is a -> String -> b.

You can ignore these methods and directly write Format a b if you so want.

s : r -> Format a r

Creates a formatter that returns the same string for any value.

string : Format String String

Creates a formatter for String.

int : Format Int String

Creates a formatter for Int.

bool : Format Bool String

Creates a formatter for Bool.

float : Format Float String

Creates a formatter for Float.

number : Format number String

Creates a formatter for Int or Float.

Format Composition

(<>) : Format a r -> Format a r -> Format a r

<> lets you compose formatters together, best demonstrated via an example:

first : Format User String
first =
    .first >> string


last : Format User String
last =
    .last >> string


name : Format User String
name =
    first <> s " " <> last


print name { first = "Amit", last = "Upadhyay" }


--> "Amit Upadhyay"

map : (r1 -> r2) -> Format a r1 -> Format a r2

map changes the type of output from one format to another. It can also be used for general post processing of the output.

name : Format User String
name =
    (.name >> string)
        |> map String.toUpper

Printer

print : Format a String -> a -> String

Print applies a formatter on a value, to produce the output.

Helpers

These are some helpers that change the output after the conversion of a -> String, they are simple applications of map.

wrap : r -> Format a r -> Format a r

Wrap puts a token around the output.

name : Format User String
name =
    (.name >> string)
        |> wrap "'"


print name { name = "Amit" }


--> 'Amit' (puts "'", before and after).

pad : Int -> Char -> Format a String -> Format a String

Pad a string on both sides until it has a given length.

padLeft : Int -> Char -> Format a String -> Format a String

Pad a string on the left until it has a given length.

padRight : Int -> Char -> Format a String -> Format a String

Pad a string on the right until it has a given length.

roundTo : Int -> Format Float String

Rounds a float to given number of decimal points.

Definition

type alias Format a r =

a -> List r

Format is a the core type on which this library works on. It is nothing fancy, for a Format a String, it converts a to list of String.

The reason why we format it into a list of string, is so we can compose more than one formatter together. Each formatter can return a list of final output type, r, into a list, and our composition function <> concatenates the lists together.

If Elm has support for monoids, we may not have needed the list.

amitu/elm-formatting/1.0.0