New feature: highlighted_roots to trim output

Only keeps highlighted toplevel boxes.

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - A new optional PrintBox-only setting `highlight_terms`, which applies a frame / border on paths to leaves matching a regular expression.
 - A corresponding setting `exclude_on_path` -- if this regular expression matches on a log, its children have no effect on its highlight status. I.e., `exclude_on_path` stops the continued propagation of highlights.
+- A flag `highlighted_roots` prevents outputting toplevel boxes that have not been highlighted.
 
 ## [0.6.2] -- 2023-12-21
 

README.md

@@ -142,7 +142,9 @@ regular expression. For example:
 ![PrintBox runtime with collapsible/foldable trees](docs/ppx_minidebug-highlight_term_169.png)
 
 To limit the highlight noise, some log entries can be excluded from propagating the highlight status
-using the `exclude_on_path` setting.
+using the `exclude_on_path` setting. To trim excessive logging while still providing all the context,
+you can set `highlighted_roots:true`, which only outputs highlighted toplevel boxes.
+
 
 #### `PrintBox` creating helpers with defaults: `debug` and `debug_html`
 

index.mld

@@ -84,6 +84,8 @@ regular expression in the PrintBox runtime. Paths to logs that match [highlight_
 a frame / border: around the log and around summaries on the path to the log. A corresponding setting
 `exclude_on_path` will disable highlighting on logs (summaries) this regular expression matches on,
 regardless of children. Therefore, `exclude_on_path` stops the propagation of highlights upward.
+There is also an optional flag [highlighted_roots], to only output highlighted toplevel boxes.
+This makes it simpler to trim excessive logging while still providing all the context.
 
 
 {2 VS Code suggestions}

minidebug_runtime.ml

@@ -197,6 +197,7 @@ module PrintBox (Log_to : Debug_ch) = struct
   let to_html = ref false
   let boxify_sexp_from_size = ref (-1)
   let highlight_terms = ref None
+  let highlighted_roots = ref false
   let exclude_on_path = ref None
 
   module B = PrintBox
@@ -251,6 +252,7 @@ module PrintBox (Log_to : Debug_ch) = struct
           }
           :: bs3
       | { cond = false; _ } :: bs -> bs
+      | { highlight = false; _ } :: bs when !highlighted_roots -> bs
       | [ ({ cond = true; _ } as entry) ] ->
           let box = stack_to_tree entry in
           if !to_html then
@@ -374,27 +376,30 @@ module PrintBox (Log_to : Debug_ch) = struct
 end
 
 let debug_html ?(time_tagged = false) ?max_nesting_depth ?max_num_children
-    ?highlight_terms ?exclude_on_path ?(for_append = false) ?(boxify_sexp_from_size = 50)
-    filename : (module Debug_runtime_cond) =
+    ?highlight_terms ?exclude_on_path ?(highlighted_roots = false) ?(for_append = false)
+    ?(boxify_sexp_from_size = 50) filename : (module Debug_runtime_cond) =
   let module Debug =
     PrintBox
       ((val debug_ch ~time_tagged ~for_append ?max_nesting_depth ?max_num_children
               filename)) in
   Debug.to_html := true;
   Debug.boxify_sexp_from_size := boxify_sexp_from_size;
   Debug.highlight_terms := Option.map Re.compile highlight_terms;
+  Debug.highlighted_roots := highlighted_roots;
   Debug.exclude_on_path := Option.map Re.compile exclude_on_path;
   (module Debug)
 
 let debug ?(debug_ch = stdout) ?(time_tagged = false) ?max_nesting_depth ?max_num_children
-    ?highlight_terms ?exclude_on_path () : (module Debug_runtime_cond) =
+    ?highlight_terms ?exclude_on_path ?(highlighted_roots = false) () :
+    (module Debug_runtime_cond) =
   let module Debug = PrintBox (struct
     let debug_ch = debug_ch
     let time_tagged = time_tagged
     let max_nesting_depth = max_nesting_depth
     let max_num_children = max_num_children
   end) in
   Debug.highlight_terms := Option.map Re.compile highlight_terms;
+  Debug.highlighted_roots := highlighted_roots;
   Debug.exclude_on_path := Option.map Re.compile exclude_on_path;
   (module Debug)
 

minidebug_runtime.mli

@@ -81,6 +81,10 @@ module PrintBox : functor (_ : Debug_ch) -> sig
   val exclude_on_path : Re.re option ref
   (** Does not propagate the highlight status from child logs through log headers matching
       the given regular expression. *)
+
+  val highlighted_roots : bool ref
+  (** If set to true, only ouptputs highlighted toplevel boxes. This makes it simpler to trim
+      excessive logging while still providing all the context. Defaults to [false]. *)
 end
 
 val debug_html :
@@ -89,6 +93,7 @@ val debug_html :
   ?max_num_children:int ->
   ?highlight_terms:Re.t ->
   ?exclude_on_path:Re.t ->
+  ?highlighted_roots:bool ->
   ?for_append:bool ->
   ?boxify_sexp_from_size:int ->
   string ->
@@ -104,6 +109,7 @@ val debug :
   ?max_num_children:int ->
   ?highlight_terms:Re.t ->
   ?exclude_on_path:Re.t ->
+  ?highlighted_roots:bool ->
   unit ->
   (module Debug_runtime_cond)
 (** Creates a PrintBox-based debug runtime. By default it will log to [stdout] and will not be