Documentation

Whether to left-adjust or zero-pad a field. These are mutually exclusive, with LeftAdjust taking precedence.

Since: base-4.7.0.0

How to handle the sign of a numeric field. These are mutually exclusive, with SignPlus taking precedence.

Since: base-4.7.0.0

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.

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.

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.

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)

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.

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.

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 %.

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"

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