From 86281b16aabc69fe607c6cfc2f56d5c1e565408c Mon Sep 17 00:00:00 2001
From: Ali Caglayan <alizter@gmail.com>
Date: Tue, 17 Oct 2023 18:50:22 -0700
Subject: [PATCH] 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 <alizter@gmail.com>
---
 src/pp.ml     |   2 +
 src/pp.mli    |   8 ++++
 test/tests.ml | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 112 insertions(+)

diff --git a/src/pp.ml b/src/pp.ml
index 8a088c6..5332dad 100644
--- 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
index bbca61c..8104736 100644
--- 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
index 9ec07c4..857281d 100644
--- 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. |}]