package ppx_custom_printf

  1. Overview
  2. Docs
Printf-style format-strings for user-defined string conversion


Dune Dependency






Part of the Jane Street's PPX rewriters collection.

Published: 04 Jun 2019



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.

Dependencies (5)

  1. ppxlib >= "0.7.0" & < "0.9.0"
  2. dune >= "1.5.1"
  3. ppx_sexp_conv >= "v0.12" & < "v0.13"
  4. base >= "v0.12" & < "v0.13"
  5. ocaml >= "4.04.2"

Dev Dependencies


Used by (6)

  1. bin_prot = "v0.12.0"
  2. hl_yaml
  3. ppx_expect = "v0.12.0"
  4. ppx_jane = "v0.12.0"
  5. routes >= "2.0.0"
  6. torch < "v0.16.0"




Innovation. Community. Security.