package ppx_custom_printf

title: ppx_custom_printf parent: ../README.md

Extensions to printf-style format-strings for user-defined string conversion.

ppx_custom_printf is a ppx rewriter that allows the use of user-defined string conversion functions in format strings (that is, strings passed to printf, sprintf, etc.).

No new syntax is introduced. Instead a previously ill-typed use of the ! operator is re-purposed.

Basic Usage

The basic usage is as follows:

printf !"The time is %{Time} and the timezone is %{Time.Zone}."
  time zone

The ppx rewriter will turn the !-string into a format of type (Time.t -> Time.Zone.t -> unit, unit, string) format. This is done by embedding the Time.to_string and Time.Zone.to_string functions into the format, using the low-level format mechanism of the stdlib.

In general, specifiers like %{<Module-path>} produce a call to Module-path.to_string. The module path can even be empty, in which case the generated code calls to_string.

Note that you have to prepend the format string with a !, so that the ppx rewriter knows to operate on it.

Sexps

The syntax %{sexp:<type>} is also supported. For example:

printf !"The time is %{sexp:Time.t}." time

The time argument will be turned into a string using:

fun x -> Sexplib.Sexp.to_string_hum ([%sexp_of: Time.t] x)

This supports arbitrary type expressions.

You can use Sexplib.Sexp.to_string_mach instead of Sexplib.Sexp.to_string_hum by using %{sexp#mach:<type>}

Using functions other than M.to_string

The format specifier %{<Module-path>.<lowercase_identifier>} corresponds to that function. So, for example:

printf !"The date is %{Core.Date.to_string_iso8601_basic}" date

will turn date to a string using the following code:

fun x -> Core.Date.to_string_iso8601_basic x

Further, the format specifier %{<Module-path>#<lowercase_identifier>} corresponds to the function <Module_path>.to_string_<lowercase_identifier>. So, for example:

printf !"The date is %{Core.Date#american}" date

will turn date to a string using:

fun x -> Core.Date.to_string_american x

Subformats disallowed

In a regular format string, you can use format specifiers of the form %{<spec>%} and %(<spec>%) where <spec> is another format specifier.

Using these specifiers is disallowed in format strings that are processed with custom-printf.