feature: Pp.paragraph (#16)

We add two new Pp helpers for building paragraphs of text. This surrounds Pp.text in a Pp.hovbox which allows it to be used freely without being distorted by a surrounding Pp.vbox which is a common occurance. We demonstrate the use with a test contrasting it with the other ways to write paragraphs. Signed-off-by: Ali Caglayan <[email protected]>
ocaml-dune · Oct 18, 2023 · 86281b1 · 86281b1
1 parent 5197d6e
commit 86281b1
Show file tree

Hide file tree

Showing 3 changed files with 112 additions and 0 deletions.
diff --git a/src/pp.ml b/src/pp.ml
@@ -198,6 +198,8 @@ let newline = Newline
 let text s = Text s
 let textf fmt = Printf.ksprintf text fmt
 let tag tag t = Tag (tag, t)
+let paragraph s = hovbox (text s)
+let paragraphf fmt = hovbox (textf fmt)
 
 let enumerate l ~f =
   vbox

diff --git a/src/pp.mli b/src/pp.mli
@@ -142,6 +142,14 @@ val filter_map_tags :
 
 (** {1 Convenience functions} *)
 
+(** [paragraph s] is [hovbox (text s)]. This is useful to preserve the structure
+    of a paragraph of text without worrying about it being broken by a [vbox]. *)
+val paragraph : string -> 'tag t
+
+(** [paragraphf s] is [textf s] followed by a [hovbox]. The [textf] version of
+    [paragraph]. *)
+val paragraphf : ('tag t, unit, string, 'b t) format4 -> 'tag t
+
 (** [enumerate l ~f] produces an enumeration of the form:
 
     {v

diff --git a/test/tests.ml b/test/tests.ml
@@ -234,3 +234,105 @@ let%expect_test "comparison" =
     comparison result: -1
     comparison result: 0
     comparison result: 1 |}]
+
+(* The differnces between [Pp.paragraph], [Pp.text], [Pp.verbatim] and box +
+   [Pp.text] when inside a [Pp.vbox]. *)
+let%expect_test "paragraph" =
+  let lorem =
+    "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum \
+     euismod, nisl eget aliquam ultricies."
+  in
+  let seperator text _ =
+    Pp.vbox
+    @@ Pp.seq Pp.space
+         (Pp.hbox
+         @@ Pp.textf "-< %s >-%s" text
+              (String.init (20 - String.length text) ~f:(fun _ -> '-')))
+  in
+  print @@ Pp.vbox
+  @@ Pp.concat_map ~sep:Pp.space
+       ~f:(fun f -> f lorem)
+       [ seperator "verbatim"
+       ; Pp.verbatim
+       ; seperator "text"
+       ; Pp.text
+       ; seperator "paragraph"
+       ; Pp.paragraph
+       ; seperator "hovbox + text"
+       ; (fun x -> Pp.hovbox (Pp.text x))
+       ; seperator "hvbox + text"
+       ; (fun x -> Pp.hvbox (Pp.text x))
+       ; seperator "hbox + text"
+       ; (fun x -> Pp.hbox (Pp.text x))
+       ; seperator "vbox + text"
+       ; (fun x -> Pp.vbox (Pp.text x))
+       ; seperator "box + text"
+       ; (fun x -> Pp.box (Pp.text x))
+       ];
+  [%expect
+    {|
+    -< verbatim >-------------
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum euismod, nisl eget aliquam ultricies.
+
+    -< text >-----------------
+    Lorem
+    ipsum
+    dolor
+    sit
+    amet,
+    consectetur
+    adipiscing
+    elit.
+    Vestibulum
+    euismod,
+    nisl
+    eget
+    aliquam
+    ultricies.
+
+    -< paragraph >------------
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum euismod,
+    nisl eget aliquam ultricies.
+
+    -< hovbox + text >--------
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum euismod,
+    nisl eget aliquam ultricies.
+
+    -< hvbox + text >---------
+    Lorem
+    ipsum
+    dolor
+    sit
+    amet,
+    consectetur
+    adipiscing
+    elit.
+    Vestibulum
+    euismod,
+    nisl
+    eget
+    aliquam
+    ultricies.
+
+    -< hbox + text >----------
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum euismod, nisl eget aliquam ultricies.
+
+    -< vbox + text >----------
+    Lorem
+    ipsum
+    dolor
+    sit
+    amet,
+    consectetur
+    adipiscing
+    elit.
+    Vestibulum
+    euismod,
+    nisl
+    eget
+    aliquam
+    ultricies.
+
+    -< box + text >-----------
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum euismod,
+    nisl eget aliquam ultricies. |}]