package ppx_custom_printf

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

Install

Dune Dependency

Authors

Maintainers

Sources

v0.17.0.tar.gz
sha256=cd3cf73c31f6b0e18677ce92ce0e6f866b0596d5ea1fc540212c422930a730a0

Description

Part of the Jane Street's PPX rewriters collection.

Published: 23 May 2024

README

ppx_custom_printf

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.

Dependencies (5)

  1. ppxlib >= "0.28.0"
  2. dune >= "3.11.0"
  3. ppx_sexp_conv >= "v0.17" & < "v0.18"
  4. base >= "v0.17" & < "v0.18"
  5. ocaml >= "5.1.0"

Dev Dependencies

None

Used by (8)

  1. bin_prot >= "v0.17.0"
  2. hl_yaml
  3. pgx >= "1.0"
  4. ppx_jane >= "v0.17.0"
  5. routes >= "2.0.0"
  6. SZXX >= "4.1.0"
  7. tdigest >= "2.2.0"
  8. torch < "v0.16.0"

Conflicts

None

OCaml

Innovation. Community. Security.