Typeclass associating format types (d, f, etc.) with the types that can be formatted by them.

You can extend the printf methods here for your own types by writing your instances here.

A type synonym for a single-character symbol. Ideally this would just be Char, but we don't have chars at the type level. So, if you see SChar in a type signature, it means that it's expected to be a symbol/string with only one single character.

Type-safe printf with true naked polyarity. Call it like printf @"you have %.02f dollars, %s".

>>> putStrLn $ printf @"You have %.2f dollars, %s" 3.62 "Luigi"
You have 3.62 dollars, Luigi

While the type of printf @"my fmt string" isn't going to be very helpful, the error messages should help guide you along the way:

>>> printf @"You have %.2f dollars, %s"
-- ERROR: Call to printf missing argument fulfilling "%.2f"
-- Either provide an argument or rewrite the format string to not expect
-- one.

>>> printf @"You have %.2f dollars, %s" 3.62
-- ERROR: Call to printf missing argument fulfilling "%s"
-- Either provide an argument or rewrite the format string to not expect
-- one.

>>> printf @"You have %.2f dollars, %s" 3.62 "Luigi"
You have 3.62 dollars, Luigi

>>> printf @"You have %.2f dollars, %s" 3.62 "Luigi" 72
-- ERROR: An extra argument of type Integer was given to a call to printf
-- Either remove the argument, or rewrite the format string to include the
-- appropriate hole.

If you're having problems getting the error messages to give helpful feedback, try using pHelp:

>>> pHelp $ printf @"You have %.2f dollars, %s" 3.62
-- ERROR: Call to printf missing argument fulfilling "%s"
-- Either provide an argument or rewrite the format string to not expect
-- one.

pHelp can give the type system the nudge it needs to provide good errors.

See pprintf for a version of this with nicer types and type errors, but requires wrapping arguments, and rprintf for a version of this with "fake" polyarity, taking a list as input instead. Also see top-level module documentation GHC.TypeLits.Printf for a more comprehensive summary.

Note that this also supports the "interpret as an IO action to print out results" functionality that Text.Printf supports. This also supports returning strict Text and lazy Text as well.

A version of printf taking an explicit proxy, which allows usage without TypeApplications

>>> putStrLn $ printf_ (Proxy :: Proxy "You have %.2f dollars, %s") 3.62 "Luigi"
You have 3.62 dollars, Luigi

A useful token for helping the type system give useful errors for printf:

>>> printf @"You have ".2f" dollars, %s" 3.26 :: PHelp
-- ERROR: Call to printf missing argument fulfilling "%s"
-- Either provide an argument or rewrite the format string to not expect
-- one.

Usually things should work out on their own without needing this ... but sometimes the type system could need a nudge.

See also pHelp

A useful helper function for helping the type system give useful errors for printf:

>>> pHelp $ printf @"You have %.2f dollars, %s" 3.62
-- ERROR: Call to printf missing argument fulfilling "%s"
-- Either provide an argument or rewrite the format string to not expect
-- one.

Usually things would work out on their own without needing this ... but sometimes the type system could need a nudge.

The typeclass supporting polyarity used by printf. It works in mostly the same way as PrintfType from Text.Printf, and similar the same as FormatF.

Ideally, you will never have to run into this typeclass or have to deal with it. It will come up if you ask for the type of printf, or sometimes if you give the wrong number or type of arguments to it.

>>> :t printf @"You have %.2f dollars, %s"
FormatFun '[ Right ..., 'Left " dollars ", 'Right ...] fun => fun

Every item in the first argument of FormatFun is a chunk of the formatting string, split between format holes (Right) and string chunks (Left). You can successively "eliminate" them by providing more arguments that implement each hole:

>>> :t printf @"You have %.2f dollars, %s" 3.62
FormatFun '[ Right ...] fun => fun

Until you you finally fill all the holes:

>>> :t printf @"You have %.2f dollars, %s" 3.62 "Luigi"
FormatFun '[] t => t

at which point you may use it as a String or IO (), in the same way that Text.Printf works. We also support using strict Text lazy Text as well.

So, while it's possible to reason with this using the types, it's usually more difficult than with pprintf and rprintf.

This is why, instead of reasoning with this using its types, it's easier to reason with it using the errors instead:

>>> printf @"You have %.2f dollars, %s"
-- ERROR: Call to printf missing argument fulfilling "%.2f"
-- Either provide an argument or rewrite the format string to not expect
-- one.

>>> printf @"You have %.2f dollars, %s" 3.62
-- ERROR: Call to printf missing argument fulfilling "%s"
-- Either provide an argument or rewrite the format string to not expect
-- one.

>>> printf @"You have %.2f dollars, %s" 3.62 "Luigi"
You have 3.62 dollars, Luigi

>>> printf @"You have %.2f dollars, %s" 3.62 "Luigi" 72
-- ERROR: An extra argument of type Integer was given to a call to printf
-- Either remove the argument, or rewrite the format string to include the
-- appropriate hole.

If you're having problems getting the error messages to give helpful feedback, try using pHelp:

>>> pHelp $ printf @"You have %.2f dollars, %s" 3.62
-- ERROR: Call to printf missing argument fulfilling "%s"
-- Either provide an argument or rewrite the format string to not expect
-- one.

pHelp can give the type system the nudge it needs to provide good errors.

Type-safe printf with true guarded polyarity. Call it like pprintf @"you have %.02f dollars, %s".

A call to printf on a valid string will always give a well-defined type for a function in return:

>>> :t pprintf @"You have %.2f dollars, %s"
PP "f" -> PP "s" -> String

You can always query the type, and get a well-defined type back, which you can utilize using typed holes or other type-guided development techniques.

To give pprintf its arguments, however, they must be wrapped in PP:

>>> putStrLn $ pprintf @"You have %.2f dollars, %s" (PP 3.62) (PP "Luigi")
You have 3.62 dollars, Luigi

See printf for a polyariadic method that doesn't require PP on its inputs, but with a less helpful type signature, and rprintf for a fake-polyariadic method that doesn't require PP, but requires arguments in a single list instead. Also see top-level module documentation GHC.TypeLits.Printf for a more comprehensive summary.

A version of pprintf taking an explicit proxy, which allows usage without TypeApplications

>>> :t pprintf_ (Proxy :: Proxy "You have %.2f dollars, %s")
PP "f" -> PP "s" -> String

Required wrapper around inputs to pprintf (guarded polyarity). See documentation for pprintf for examples of usage.

You can "wrap" any value in PP as long as it can be formatted as the format type indicated.

For example, to make a PP "f", you can use PP 3.5 or PP 94.2, but not PP (3 :: Int) or PP "hello". To make a value of type PP c, you must wrap a value that can be formatted via c.

Type-safe printf with faked polyarity. Pass in a "list" of arguments (using :% and RNil), instead of as multiple arguments. Call it like rprintf @"you have %.02f dollars, %s".

>>> :t rprintf @"You have %.2f dollars, %s"
FormatArgs '["f", "s"] -> String

This means that it is expecting something that can be printed with f and something that can be printed with s. We can provide a Double and a String:

>>> putStrLn $ rprintf @"You have %.2f dollars, %s" (3.62 ':%' "Luigi" :% 'RNil')
You have 3.62 dollars, Luigi

See pprintf for a version with true polyarity and good clear types, but requires wrapping its arguments, and printf for a version with true polyarity but less clear types. Also see top-level module documentation GHC.TypeLits.Printf for a more comprehensive summary.

A version of rprintf taking an explicit proxy, which allows usage without TypeApplications

>>> :t rprintf_ (Proxy :: Proxy "You have %.2f dollars, %s")
FormatArgs '["f", "s"] -> String

A record is parameterized by a universe u, an interpretation f and a list of rows rs. The labels or indices of the record are given by inhabitants of the kind u; the type of values at any label r :: u is given by its interpretation f r :: *.

A heterogeneous list (from Data.Vinyl.Core) used for calling with rprintf. Instead of supplying the inputs as different arguments, we can gather all the inputs into a single list to give to rprintf.

>>> :t rprintf @"You have %.2f dollars, %s"
FormatArgs '["f", "s"] -> String

To construct a FormatArgs '["f", "s"], you need to give a value formattable by f and a value formattable by s, given like a linked list, with :% for cons and RNil for nil.

>>> putStrLn $ rprintf @"You have %.2f dollars, %s" (3.62 :% "Luigi" :% RNil)
You have 3.62 dollars, Luigi

(This should evoke the idea of of 3.62 : Luigi : [], even though the latter is not possible in Haskell)

Parse and run a single format hole on a single vale. Can be useful for formatting individual items or for testing your own custom instances of FormatType.

Usually meant to be used with OverloadedLabels:

>>> pfmt #f 3.62
"3.62"

However, current versions of GHC disallow labels that aren't valid identifier names, disallowing things like pfmt #.2f 3.62. While there is an <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0170-unrestricted-overloadedlabels.rst approved proposal> that allows this, if you are using an earlier GHC version, you can get around this using mkPFmt:

>>> pfmt (mkPFmt @".2f") 3.6234124
"3.62"

Ideally we'd want to be able to write

>>> pfmt #.2f 3.6234124
"3.62"

(which should be possible in GHC 8.10+)

Note that the format string does not include the leading %.

Utility type powering pfmt. See dcumentation for pfmt for more information on usage.

Using OverloadedLabels, you never need to construct this directly can just write #f and a PFmt "f" will be generated. You can also create this using mkPFmt or mkPFmt_, in the situations where OverloadedLabels doesn't work or is not wanted.

Useful for using pfmt without OverloadedLabels, or also when passing format specifiers that aren't currently allowed with OverloadedLabels until GHC 8.10+ (like #.2f).

>>> pfmt (mkPFmt @".2f") 3.6234124
"3.62"

A version of mkPFmt that takes an explicit proxy input.

>>> pfmt (mkPFmt_ (Proxy :: Proxy ".2f") 3.6234124
"3.62"