unikernel/duniverse/ppx_custom_printf/README.md

@@ -0,0 +1,93 @@
+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:
+
+```ocaml
+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:
+
+```ocaml
+printf !"The time is %{sexp:Time.t}." time
+```
+
+The `time` argument will be turned into a string using:
+
+```ocaml
+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:
+
+```ocaml
+printf !"The date is %{Core.Date.to_string_iso8601_basic}" date
+```
+
+will turn `date` to a string using the following code:
+
+```ocaml
+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:
+
+```ocaml
+printf !"The date is %{Core.Date#american}" date
+```
+
+will turn `date` to a string using:
+
+```ocaml
+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.