Extensions of printing
Camlp5 provides extensions kits to pretty print programs in revised syntax and normal syntax. Some other extensions kits also allow to rebuild the parsers, or the EXTEND statements in their initial syntax. The pretty print system is itself extensible, by adding new rules. We present here how it works in the Camlp5 sources.
The pretty print system of Camlp5 uses the library modules Pretty, an original system to format output) and Extfun, another original system of extensible functions.
This chapter is designed for programmers that want to understand how the pretty printing of OCaml programs work in Camlp5, want to adapt, modify or debug it, or want to add their own pretty printing extensions.
Introduction
The files doing the pretty printings are located in Camlp5 sources in the directory "etc". Peruse them if you are interested in creating new ones. The main ones are:
- "etc/pr_r.ml": pretty print in revised syntax.
- "etc/pr_o.ml": pretty print in normal syntax.
- "etc/pr_rp.ml": rebuilding parsers in their original revised syntax.
- "etc/pr_op.ml": rebuilding parsers in their original normal syntax.
- "etc/pr_extend.ml": rebuilding EXTEND in its original syntax.
We present here how this system works inside these files. First, the general principles. Second, more details of the implementation.
Principles
Using module Pretty
All functions in OCaml pretty printing take a parameter named "the
printing context" (variable pc). It is a record holding :
- The current indendation :
pc.ind - What should be printed before, in the same line
:
pc.bef - What should be printed after, in the same line
:
pc.aft - The dangling token, useful in normal syntax to know whether
parentheses are necessary :
pc.dang
A typical pretty printing function calls the
function horiz_vertic of the library
module Pretty. This function takes two
functions as parameter:
- The way to print the data in one only line (horizontal printing)
- The way to print the data in two or more lines (vertical printing)
Both functions catenate the strings by using the
function sprintf of the library
module Pretty which controls whether the printed data
holds in the line or not. They generally call, recursively, other
pretty printing functions with the same behaviour.
Let us see an example (fictitious) of printing an OCaml
application. Let us suppose we have an application expression
"e1 e2" to pretty print where e1
and e2 are sub-expressions. If both expressions and
their application holds on one only line, we want to see:
e1 e2
On the other hand, if they do not hold on one only line, we want to
see e2 in another line with, say, an indendation of 2
spaces:
e1
e2
Here is a possible implementation. The function has been
named expr_app and can call the function expr to
print the sub-expressions e1 and e2:
value expr_app pc e1 e2 =
horiz_vertic
(fun () ->
let s1 = expr {(pc) with aft = ""} e1 in
let s2 = expr {(pc) with bef = ""} e2 in
sprintf "%s %s" s1 s2)
(fun () ->
let s1 = expr {(pc) with aft = ""} e1 in
let s2 =
expr
{(pc) with
ind = pc.ind + 2;
bef = tab (pc.ind + 2)}
e2
in
sprintf "%s\n%s" s1 s2)
;
The first function is the horizontal printing. It ends with a
sprintf separating the printing of e1
and e2 by a space. The possible "before part"
(pc.bef) and "after part" (pc.aft) are
transmitted in the calls of the sub-functions.
The second function is the vertical printing. It ends with a
sprintf separating the printing of e1
and e2 by a newline. The second line starts with an
indendation, using the "before part" (pc.bef) of the
second call to expr.
The pretty printing library
function Pretty.horiz_vertic calls the first
(horizontal) function, and if it fails (either
because s1 or s2 are too long or hold
newlines, or because the final string produced
by sprintf is too long), calls the second
(vertical) function.
Notice that the parameter pc contains a
field pc.bef (what should be printed before in the same
line), which in both cases is transmitted to the printing
of e1 (since the syntax {(pc) with aft =
""} is a record with pc.bef kept). Same for the
field pc.aft transmitted to the printing
of e2.
Using EXTEND_PRINTER statement
This system is combined to the extensible printers to allow the extensibility of the pretty printing.
The code above actually looks like:
EXTEND_PRINTER
pr_expr:
[ [ <:expr< $e1$ $e2$ >> ->
horiz_vertic
(fun () ->
let s1 = curr {(pc) with aft = ""} e1 in
let s2 = next {(pc) with bef = ""} e2 in
sprintf "%s %s" s1 s2)
(fun () ->
let s1 = curr {(pc) with aft = ""} e1 in
let s2 =
next
{(pc) with
ind = pc.ind + 2;
bef = tab (pc.ind + 2)}
e2
in
sprintf "%s\n%s" s1 s2) ] ]
;
END;
The variable "pc" is implicit in the semantic actions of the syntax "EXTEND_PRINTER", as well as two other variables: "curr" and "next".
These parameters, "curr" and "next", correspond
to the pretty printing of, respectively, the current level and the
next level. Since the application in OCaml is left associative, the
first sub-expression is printed at the same (current) level and the
second one is printed at the next level. We also see a call
to next in the last (2nd) case of the function to treat
the other cases in the next level.
Dangling else, bar, semicolon
In normal syntax, there are cases where it is necessary to enclose
expressions between parentheses (or
between begin
and end, which is equivalent in
that syntax). Three tokens may cause problems: the
"else", the vertical bar "|" and the
semicolon ";". Here are examples where the presence of
these tokens constrains the previous expression to be
parenthesized. In these three examples, removing
the begin..end
enclosers would change the meaning of the expression because the
dangling token would be included in that expression:
Dangling else:
if a then begin if b then c end else d
Dangling bar:
function
A ->
begin match a with
B -> c
| D -> e
end
| F -> g
Dangling semicolon:
if a then b else begin let c = d in e end; f
The information is transmitted by the
value pc.dang. In the first example above, while
displaying the "then" part of the outer
"if", the sub-expression is called with the
value pc.dang set to
"else" to inform the last sub-sub-expression that it is
going to be followed by that token. When a "if"
expression should be displayed without "else" part, and
that its "pc.dang" is "else", it should be enclosed
with spaces.
This problem does not exist in revised syntax. While pretty
printing in revised syntax, the parameter pc.dang is
not necessary and remains the empty string.
By level
As explained in the chapter about the extensible printers (with the EXTEND_PRINTER statement), printers contain levels. The global printer variable of expressions is named "pr_expr" and contain all definitions for pretty printing expressions, organized by levels, just like the parsing of expressions. The definition of "pr_expr" actually looks like this:
EXTEND_PRINTER
pr_expr:
[ "top"
[ (* code for level "top" *) ]
| "add"
[ (* code for level "add" *) ]
| "mul"
[ (* code for level "mul" *) ]
| "apply"
[ (* code for level "apply" *) ]
| "simple"
[ (* code for level "add" *) ] ]
;
END;
The Prtools module
The Prtools module is defined inside Camlp5 for pretty printing kits. It provides variables and functions to process comments, and meta-functions to process lists (horizontally, vertically, paragraphly).
Comments
- value comm_bef : int -> MLast.loc -> string;
- "comm_bef ind loc" get the comment from the source just before the given location "loc". This comment may be reindented using "ind". Returns the empty string if no comment found.
- value source : ref string;
- The initial source string, which must be set by the pretty printing kit. Used by [comm_bef] above.
- value set_comm_min_pos : int -> unit;
- Set the minimum position of the source where comments can be found, (to prevent possible duplication of comments).
Meta functions for lists
- type pr_fun 'a = pr_context -> 'a -> string;
- Type of printer functions.
- value hlist : pr_fun 'a -> pr_fun (list 'a);
- [hlist elem pc el] returns the horizontally pretty printed
string of a list of elements; elements are separated with
spaces.
The list is displayed in one only line. If this function is called in the context of the [horiz] function of the function [horiz_vertic] of the module Printing, and if the line overflows or contains newlines, the function internally fails (the exception is catched by [horiz_vertic] for a vertical pretty print). - value hlist2 : pr_fun 'a -> pr_fun 'a -> pr_fun (list 'a);
- horizontal list with a different function from 2nd element on.
- value hlistl : pr_fun 'a -> pr_fun 'a -> pr_fun (list 'a);
- horizontal list with a different function for the last element.
- value vlist : pr_fun 'a -> pr_fun (list 'a);
- [vlist elem pc el] returns the vertically pretty printed string of a list of elements; elements are separated with newlines and indentations.
- value vlist2 : pr_fun 'a -> pr_fun 'a -> pr_fun (list 'a);
- vertical list with different function from 2nd element on.
- value vlist3 : pr_fun ('a * bool) -> pr_fun ('a * bool) -> pr_fun (list 'a);
- vertical list with different function from 2nd element on, the boolean value being True for the last element of the list.
- value vlistl : pr_fun 'a -> pr_fun 'a -> pr_fun (list 'a);
- vertical list with different function for the last element.
- value plist : pr_fun 'a -> int -> pr_fun (list ('a * string));
- [plist elem sh pc el] returns the pretty printed string of a list of elements with separators. The elements are printed horizontally as far as possible. When an element does not fit on the line, a newline is added and the element is displayed in the next line with an indentation of [sh]. [elem] is the function to print elements, [el] a list of pairs (element * separator) (the last separator being ignored).
- value plistb : pr_fun 'a -> int -> pr_fun (list ('a * string));
- [plist elem sh pc el] returns the pretty printed string of the list of elements, like with [plist] but the value of [pc.bef] corresponds to an element already printed, as it were on the list. Therefore, if the first element of [el] does not fit in the line, a newline and a tabulation is added after [pc.bef].
- value plistl : pr_fun 'a -> pr_fun 'a -> int -> pr_fun (list ('a * string));
- paragraph list with a different function for the last element.
- value hvlistl : pr_fun 'a -> pr_fun 'a -> pr_fun (list 'a);
- applies "hlistl" if the context is horizontal; else applies "vlistl".
Miscellaneous
- value tab : int -> string;
- [tab ind] is equivalent to [String.make ind ' ']
- value flatten_sequence : MLast.expr -> option (list MLast.expr);
- [flatten_sequence e]. If [e] is an expression representing a sequence, return the list of expressions of the sequence. If some of these expressions are already sequences, they are flattened in the list. If that list contains expressions of the form let..in sequence, this sub-sequence is also flattened with the let..in applying only to the first expression of the sequence. If [e] is a let..in sequence, it works the same way. If [e] is not a sequence nor a let..in sequence, return None.
Example : repeat..until
This pretty prints the example repeat..until statement programmed in the chapter Syntax extensions (first version generating a "while" statement).
The code
The pattern generated by the "repeat" statement is recognized (sequence ending with a "while" whose contents is the same than the beginning of the sequence) by the function "is_repeat" and the repeat statement is pretty printed in its initial form using the function "horiz_vertic" of the Pretty module. File "pr_repeat.ml":
#load "pa_extprint.cmo";
#load "q_MLast.cmo";
open Pcaml;
open Pretty;
open Prtools;
value eq_expr_list el1 el2 =
if List.length el1 <> List.length el2 then False
else List.for_all2 eq_expr el1 el2
;
value is_repeat el =
match List.rev el with
[ [<:expr< while not $e$ do { $list:el2$ } >> :: rel1] ->
eq_expr_list (List.rev rel1) el2
| _ -> False ]
;
value semi_after pr pc = pr {(pc) with aft = sprintf "%s;" pc.aft};
EXTEND_PRINTER
pr_expr:
[ [ <:expr< do { $list:el$ } >> when is_repeat el ->
match List.rev el with
[ [<:expr< while not $e$ do { $list:el$ } >> :: _] ->
horiz_vertic
(fun () ->
sprintf "%srepeat %s until %s%s" pc.bef
(hlistl (semi_after curr) curr
{(pc) with bef = ""; aft = ""} el)
(curr {(pc) with bef = ""; aft = ""} e)
pc.aft)
(fun () ->
let s1 = sprintf "%srepeat" (tab pc.ind) in
let s2 =
vlistl (semi_after curr) curr
{(pc) with
ind = pc.ind + 2;
bef = tab (pc.ind + 2);
aft = ""}
el
in
let s3 =
sprintf "%suntil %s" (tab pc.ind)
(curr {(pc) with bef = ""} e)
in
sprintf "%s\n%s\n%s" s1 s2 s3)
| _ -> assert False ] ] ]
;
END;
Compilation
ocamlc -pp camlp5r -I +camlp5 -c pr_repeat.ml
Testing
Getting the same files "foo.ml" and "bar.ml" of the repeat syntax example:
$ cat bar.ml
#load "./foo.cmo";
value x = ref 42;
repeat
print_int x.val;
print_endline "";
x.val := x.val + 3
until x.val > 70;
$ camlp
Without the pretty printing kit:
$ camlp5r pr_r.cmo bar.ml
#load "./foo.cmo";
value x = ref 42;
do {
print_int x.val;
print_endline "";
x.val := x.val + 3;
while not (x.val > 70) do {
print_int x.val;
print_endline "";
x.val := x.val + 3
}
};
With the pretty printing kit:
$ camlp5r pr_r.cmo ./pr_repeat.cmo bar.ml -l 75
#load "./foo.cmo";
value x = ref 42;
repeat
print_int x.val;
print_endline "";
x.val := x.val + 3
until x.val > 70;
↑