ppx_sexp_message - Easy construction of s-expressions
The aim of ppx_sexp_message is to ease the creation of s-expressions in OCaml. This is mainly motivated by writing error and debugging messages, where one needs to construct a s-expression based on various element of the context such as function arguments. For instance:
open Core let rename ~src ~dst = try Unix.rename ~src:tmpfile ~dst with Unix.Unix_Error (error, _, _) -> raise_s [%message "Error while renaming file" ~source:(tmpfile : string) ~dest: (dst : string) (error : Unix.Error.t) ]
would produce the following s-expression:
("Error while renaming file" (source tmp/XYZ) (dest blah) (error ENOENT))
Ppx_sexp_message expands the
[%message ...] extension point into an expression that evaluates to an s-expression, i.e. an expression of type
Sexplib.Sexp.t. The grammar of the payload is a small DSL that specifies what the generated s-expression looks like.
Ppx_sexp_message recognizes the form
[%message expr1 expr2 ...], and maps it pointwise to an s-expression that looks like
((<optional_tag_1> <value_1>) ... (<optional_tag_n> <value_n>)). A single expression also works (but it can't syntactically be an application).
expr is mapped to an an optional tag and value as follows.
The tag is determined by the following rules:
no tag if the labelled expression has the label
the tag is the label when the label is not
when the expression is not labelled
the tag is
exprif the expression has the form
(expr : typ)
otherwise there is no tag
Here are examples of each of these rules:
[%message "error" ~_:(msg : string)]becomes
(error "value of msg")
[%message "error" ~tag:(msg : string)]becomes
(error (tag "value of msg"))
[%message "error" (msg : string)]becomes
(error (msg "value of msg"))
[%message "error" "value of msg"]becomes
(error "value of msg")
Having the tag derived from the expression is by far the most common case, since it is convenient to not have to come up with a descriptive name. This is especially valuable for debugging messages.
The rest of this section describe how each expression is converted to a value in the s-expression.
Conversion of expressions
Literals of base types (constant strings, integers, floats, ...) are converted to their natural sexp representation.
When an expression is annotated with a type, the type is used to convert the value exactly like
Otherwise, expressions are assumed to be valid ocaml expressions of type string and the resulting string ends up as an atom in the s-expression.
(Map.keys m : string list)becomes
("Map.keys m" (.bashrc .emacs))
(sprintf "expected %s of type" ast_type)becomes
"expected a pattern of type"
Optionally displayed expression
When an expression is annotated with a type, if the type has the syntax
a option [@sexp.option] for some
when the value is
None, the tag and expression are omitted
when the value is
Some x, then the tag and
If the type annotation has the attribute
[@sexp.omit_nil], then when the expression is converted into an sexp, if that sexp is
(), then both the tag and the expression are omitted.
One can also use
[%message.omit_nil exprs], which is a variation of
[%message exprs] which behaves as if all
option types were annotated with
[@sexp.option] and all other expressions were annotated with
Special case of the empty string
An exception to the previous rules is the treatment of the empty string. An empty string will be treated as if it did not appear in the source code. It it useful to work around syntactic limitations:
the inability to put a label on the first expression
the inability to tell the difference between an application and a single expression which is an application
`[%message "" ~problem:(error : Error.t)]
`[%message "" (sprintf "invalid %s" name)]
The extension points
[%lazy_message.omit_nil] are additionally provided, which just wrap the generated code in
[lazy] to delay computing and allocating of possibly large sexps. This is intended to be used with, for example,
[Error.of_lazy_sexp], where the error messages may be large, but are typically not used:
let execute_query_exn ~database ~query = Database.execute_query ~database ~query |> Option.value_exn ~error: (Error.of_lazy_sexp [%lazy_message "Query failed" (database : Database.t) (query : Query.t)])
For convenience and continuity of the syntax
Difference with ppx_sexp_value
Ppx_sexp_message is similar to ppx_sexp_value in the sense that it makes the creation of s-expression nicer. The main difference is that ppx_sexp_value is a more general rewriter that build a s-expression based closely on what the user wrote. On the other hand ppx_sexp_message tries to focus on having a DSL that is as light as possible for building error messages.