A formatter, implemented as an indexed continuation

When you construct formatters the first type parameter, r, will remain polymorphic. The second type parameter, a, will change to reflect the types of the data that will be formatted. For example, in

person :: Fmt2 ByteString Int
person = "Person's name is " % t % ", age is " % d

the first type parameter remains polymorphic, and the second type parameter is ByteString -> Int -> r, which indicates that it formats a ByteString and an Int.

When you run the formatter, for example with format, you provide the arguments and they will be formatted into a string.

>>> format ("This person's name is " % s % ", their age is " % d) "Anne" 22
"This person's name is Anne, their age is 22"

Run a monadic formatting expression.

Like the method of PrintfType, spr executes the formatting commands contained in the expression and returns the result as a monadic variable.

For example, note that the li tag repeats, while the ul tag does not:

>>> :{
 let contact = p "You can reach me at" % ul . spr . li $ do
       c1 <- a ! href @String "https://example.com" $ "Website"
       c2 <- a ! href @String "mailto:cmk@example.com" $ "Email"
       pure $ c1 <> c2
 in runLogStr contact
:}
"<p>You can reach me at</p><ul><li><a href=\"https://foo.com\">Web</a></li><li><a href=\"mailto:cmk@foo.com\">Email</a></li></ul>"

Run a formatter and print out the text to stdout.

Run a Fmt.

Run a LogFmt.

Format a constant value of type m.

Format a constant value of type m.

Concatenate two formatters.

Apply a Fmt1 to a Fmt.

Indexed bind.

Concatenate a collection of formatters.

Map over the the formatting Monoid.

Replace one occurance of a search term.

replace1 "bar" "foo" "foobarbaz"

"foofoobaz"

A unary higher-order formatter.

 Fmt1 m s a ~ (m -> s) -> a -> s

A binary higher-order formatter.

 Fmt2 m s a b ~ (m -> s) -> a -> b -> s

Format a value of type a using a function of type a -> m.

 runFmt . fmt1 :: (a -> m) -> a -> m

Concatenate two formatters, applying both to the same input.

Format each value in a list and concatenate them all:

>>> runFmt (cat1 (s % " ")) ["one", "two", "three"]
"one two three "

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

>>> runLogFmt (cat1With (mconcat . reverse) d) [123, 456, 789]
"789456123"

cat1With unlines :: Foldable f => Fmt1 LogStr String a -> Fmt1 LogStr s (f a)
cat1With unlines :: Foldable f => Fmt1 LogStr Text a -> Fmt1 LogStr s (f a)
cat1With unlines :: Foldable f => Fmt1 LogStr ByteString a -> Fmt1 LogStr s (f a)
cat1With $ intercalate " " :: Foldable f => Fmt1 LogStr String a -> Fmt1 LogStr s (f a)
cat1With $ intercalate " " :: Foldable f => Fmt1 LogStr Text a -> Fmt1 LogStr s (f a)
cat1With $ intercalate " " :: Foldable f => Fmt1 LogStr ByteString a -> Fmt1 LogStr s (f a)

Turn a text-splitting function into a formatting combinator.

 split1With hsep :: (Traversable f, ToLogStr msg) => (ByteString -> f msg) -> Fmt LogStr s a -> Fmt LogStr s a
 split1With vsep :: (Traversable f, ToLogStr msg) => (ByteString -> f msg) -> Fmt LogStr s a -> Fmt LogStr s a
 split1With list1 :: (Traversable f, ToLogStr msg) => (ByteString -> f msg) -> Fmt LogStr s a -> Fmt LogStr s a

>>> commas = reverse . fmap BL.reverse . BL.chunksOf 3 . BL.reverse
>>> dollars = prefix "$" . split1With commas (intercalate ",") . reversed
>>> runLogFmt (dollars d) 1234567890
"$1,234,567,890"
>>> printf (split1With (BL.splitOn ",") vsep t) "one,two,three"
one
two
three
>>> printf (split1With (BL.splitOn ",") (indentEach 4) t) "one,two,three"
    one
    two
    three

Format HTML

For example:

 contact :: Html LogStr
 contact = p "You can reach me at" % ul . spr . li $ do
       c1 <- a ! href String "https://example.com" $ Website
       c2 <- a ! href String "mailto:cmk@example.com" $ Email
       pure $ c1 <> c2
 

generates the following output:

"<p>You can reach me at</p><ul><li><a href=\"https://foo.com\">Web</a></li><li><a href=\"mailto:cmk@foo.com\">Email</a></li></ul>"

Type for an attribute.

Apply an attribute to an HTML tag.

The interface is similar to https://hackage.haskell.org/package/blaze-builder.

You should not define your own instances of this class.

Shorthand for setting an attribute depending on a conditional.

Example:

p !? (isBig, A.class "big") $ "Hello"

Gives the same result as:

(if isBig then p ! A.class "big" else p) "Hello"

Format each value in a list with spaces in between:

>>> runLogFmt (hsep d) [1, 2, 3]
"1 2 3"

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

>>> printf (vsep c) ['a'..'c']
a
b
c

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

 indentEach n = vsep . indent n

>>> printf (split1With BL.lines (indentList 2) t) "one\ntwo\nthree"
  one
  two
  three
>>> printf ("The lucky numbers are:\n" % indentList 2 d) [7, 13, 1, 42]
The lucky numbers are:
  7
  13
  1
  42

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

>>> runFmt (indent 4 d) 7
"    7"

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

Add the given prefix to the formatted item:

>>> runLogFmt ("The answer is: " % prefix "wait for it... " d) 42
"The answer is: wait for it... 42"

>>> printf (vsep (indent 4 (prefix "- " d))) [1, 2, 3]
    - 1
    - 2
    - 3

Add the given suffix to the formatted item.

Enclose the output string with the given strings:

>>> runFmt (parens $ enclose v s ", ") 1 "two"
"(1, two)"
>>> runFmt (enclose (fmt "<!--") (fmt "-->") s) "an html comment"
"<!--an html comment-->"

Add double quotes around the formatted item:

Use this to escape a string:

>>> runFmt ("He said it was based on " % quotes t' % ".") "science"
He said it was based on "science".

Add single quotes around the formatted item:

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

Add parentheses around the formatted item:

>>> runFmt ("We found " % parens d % " discrepancies.") 17
"We found (17) discrepancies."

>>> printf (get 5 (list1 (parens d))) [1..]
[(1), (2), (3), (4), (5)]

Add braces around the formatted item:

>>> runFmt ("\\begin" % braces t) "section"
"\\begin{section}"

Add square brackets around the formatted item:

>>> runFmt (brackets d) 7
"[7]"

Add backticks around the formatted item:

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

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

>>> runLogFmt (left1 text) (Left "bingo")
"bingo"

>>> runLogFmt (left1 text) (Right 16)
""

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

>>> runLogFmt (right1 text) (Left 16)
""

>>> runLogFmt (right1 text) (Right "bingo")
"bingo"

Render the value in an Either:

>>> runLogFmt (either1 text int) (Left "Error!"
"Error!"

>>> runLogFmt (either1 text int) (Right 69)
"69"

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

>>> runLogFmt (maybe1 "Goodbye" text) Nothing
"Goodbye"

>>> runLogFmt (maybe1 "Goodbye" text) (Just "Hello")
"Hello"

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

>>> runLogFmt (list1 s) ["one", "two", "three"]
"[one, two, three]"
>>> printf (quotes $ list1 d) [1,2,3]
["1", "2", "3"]
>>> printf (quotes $ list1 s) ["one", "two", "three"]
["one", "two", "three"]

A JSON-style formatter for lists.

>>> printf jsonList [1,2,3]
[
  1
, 2
, 3
]

Like yamlListF, it handles multiline elements well:

>>> fmt $ jsonListF ["hello\nworld", "foo\nbar\nquix"]
[
  hello
  world
, foo
  bar
  quix
]

A multiline formatter for lists.

>>> printf (yamlList d) [1,2,3]
- 1
- 2
- 3

Multi-line elements are indented correctly:

>>> printf (yamlList s) ["hello\nworld", "foo\nbar\nquix"]
- hello
  world
- foo
  bar
  quix

A JSON-like map formatter; works for Map, HashMap, etc, and lists of pairs.

>>> fmt $ jsonMapF [("Odds", jsonListF [1,3]), ("Evens", jsonListF [2,4])]
{
  Odds:
    [
      1
    , 3
    ]
, Evens:
    [
      2
    , 4
    ]
}

Log message builder. Use (<>) to append two LogStr in O(1).

Converting LogStr to ByteString.

Types that can be converted to a LogStr. Instances for types from the text library use a UTF-8 encoding. Instances for numerical types use a decimal encoding.

IsString is used in combination with the -XOverloadedStrings language extension to convert the literals to different string types.

For example, if you use the text package, you can say

{-# LANGUAGE OverloadedStrings  #-}

myText = "hello world" :: Text

Internally, the extension will convert this to the equivalent of

myText = fromString @Text ("hello world" :: String)

Note: You can use fromString in normal code as well, but the usual performance/memory efficiency problems with String apply.