Skip to content
Printf-style format-strings for user-defined string conversion
OCaml Makefile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


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.


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.

You can’t perform that action at this time.