refactor: re-organize code

src/Asai.ml

@@ -13,5 +13,5 @@ module MarkedSource = MarkedSource
 module SourceMarker = SourceMarker
 module SourceReader = SourceReader
 
-module SourceUtils = SourceUtils
+module StringUtils = StringUtils
 module RangeFlattener = RangeFlattener

src/Asai.mli

@@ -61,7 +61,7 @@ module SourceReader = SourceReader
 (**/**)
 
 (** Helper functions for handling user content. This is exposed for internal testing. Absolutely no stability guarantees. *)
-module SourceUtils = SourceUtils
+module StringUtils = StringUtils
 
 (** The internal flattener that is tightly coupled with {!module:MarkedSource}. This is exposed for internal testing. Absolutely no stability guarantees. *)
 module RangeFlattener = RangeFlattener

src/RangeFlattener.ml

@@ -90,21 +90,7 @@ struct
       partition_sorted ~block_splitting_threshold @@ Bwd.of_list @@ sort_tagged l
   end
 
-  (* Stage 2: for each block, flatten out ranges into markers
-
-     The code needs to handle several subtleties, using the XML-like notation to demonstrate:
-     1. The ordering of markers and text strings should be ordered like this:
-        <range1>...</range1><point/><range2>...</range2>
-        Note that, in the middle, RangeEnd goes first, and then Point, and then RangeBegin.
-     2. If the set of ranges is "well-scoped" (that is, a range is always completely included in,
-        completely including, or being disjoint from another range), then matching beginning and
-        ending markers will have the expected nested structures, like this:
-        <range1><range2>...</range2><range3>...</range3></range1>
-     3. For two ranges marking the same text with different priorities, the prioritized one goes inside.
-        For two ranges with the same text and priority, the order of beginning markers will follow
-        the order of the original input list. This is to reduce interruption of the prioritized highlighting.
-        <low_pri1><low_pri2><high_pri1><high_pri2>...</high_pri2></high_pri1></low_pri2></low_pri1>
-  *)
+  (* Stage 2: for each block, flatten out ranges into markers *)
   module BlockFlattener :
   sig
     val flatten : (Range.t * Tag.t) list -> (Range.position * Tag.t marker) list

src/RangeFlattener.mli

@@ -14,4 +14,20 @@ val dump : (Format.formatter -> 'tag -> unit) -> Format.formatter -> 'tag t -> u
 
 module Make (Tag : SourceMarkerSigs.Tag) : sig
   val flatten : block_splitting_threshold:int -> (Range.t * Tag.t) list -> Tag.t t
+  (**
+     The code needs to handle several subtle cases, expressing in an XML-like notation:
+     - The ordering of range markers and point markers at the same location should be ordered like this:
+       [...</range1><point/><range2>...]
+       [RangeEnd] goes first, and then [Point], and then [RangeBegin].
+     - If the set of ranges is "well-scoped" (that is, a range is always completely included in,
+       completely including, or being disjoint from another range), then matching beginning and
+       ending markers will have the expected nested structures, like this:
+       [<range1><range2>...</range2><range3>...</range3></range1>]
+     - For two ranges marking the same text with different priorities, the prioritized one goes inside.
+       This is to reduce interruption of the prioritized highlighting.
+       [<low_priority><high_priority>...</high_priority></low_priority>]
+     - For two ranges with the same text and priority, the order of ending markers will follow
+       the order of the original input list. This will help the TTY backend display the messages in order.
+       [<message2><message1>...</message1></message2>]
+  *)
 end

src/SourceMarker.ml

@@ -6,7 +6,7 @@ include SourceMarkerSigs
 
 (* helper functions used by the register_printer below *)
 
-let print_invalid_offset fmt : SourceUtils.invalid_offset -> unit =
+let print_invalid_offset fmt : StringUtils.invalid_offset -> unit =
   function
   | `Negative i ->
     Format.fprintf fmt "its@ offset@ %d@ is@ negative." i
@@ -15,7 +15,7 @@ let print_invalid_offset fmt : SourceUtils.invalid_offset -> unit =
   | `Within_newline (i, (s, e)) ->
     Format.fprintf fmt "its@ offset@ %d@ is@ within@ a@ newline@ sequence@ [%d,%d)." i s e
 
-let print_invalid_position fmt : SourceUtils.invalid_position -> unit =
+let print_invalid_position fmt : StringUtils.invalid_position -> unit =
   function
   | `Offset r ->
     print_invalid_offset fmt r
@@ -24,7 +24,7 @@ let print_invalid_position fmt : SourceUtils.invalid_position -> unit =
   | `Incorrect_line_num (ln, ln') ->
     Format.fprintf fmt "its@ line@ number@ is@ %d@ but@ it@ should@ have@ been@ %d." ln ln'
 
-let print_invalid_range fmt : SourceUtils.invalid_range -> unit =
+let print_invalid_range fmt : StringUtils.invalid_range -> unit =
   function
   | `Begin r ->
     Format.fprintf fmt "its@ beginning@ position@ is@ invalid;@ %a" print_invalid_position r
@@ -77,7 +77,7 @@ module Make (Tag : Tag) = struct
     | ((first_loc, _) :: _) as markers ->
       let source = SourceReader.load source in
       let eof = SourceReader.length source in
-      let find_eol i = SourceUtils.find_eol ~line_breaks (SourceReader.unsafe_get source) (i, eof) in
+      let find_eol i = StringUtils.find_eol ~line_breaks (SourceReader.unsafe_get source) (i, eof) in
       let rec go state : (Range.position * Tag.t marker) list -> _ =
         function
         | (loc, marker) :: markers when state.cursor.line_num = loc.line_num (* on the same line *) ->
@@ -163,8 +163,8 @@ module Make (Tag : Tag) = struct
          let source = SourceReader.load @@ Range.source range in
          let read = SourceReader.unsafe_get source in
          let eof = SourceReader.length source in
-         try SourceUtils.check_range ~line_breaks ~eof read range
-         with SourceUtils.Invalid_range reason -> raise @@ Invalid_range (range, reason))
+         try StringUtils.check_range ~line_breaks ~eof read range
+         with StringUtils.Invalid_range reason -> raise @@ Invalid_range (range, reason))
       ranges
 
   let mark ?(line_breaks=`Traditional) ?(block_splitting_threshold=5) ?(debug=false) ranges =

src/SourceMarkerSigs.ml

@@ -1,6 +1,6 @@
 open MarkedSource
 
-exception Invalid_range of Range.t * SourceUtils.invalid_range
+exception Invalid_range of Range.t * StringUtils.invalid_range
 (** [Invalid_range (range, reason)] means that [range] is an invalid range because of [reason]. This exception will be raised only when the debug mode is enabled. See the [debug] parameter of {!val:SourceMarker.S.mark} for enabling the debug mode. *)
 
 (** The signature of tags *)

src/SourceUtils.ml → src/StringUtils.ml

@@ -1,4 +1,4 @@
-include SourceUtilsData
+include StringUtilsData
 
 exception Invalid_offset of invalid_offset
 exception Invalid_position of invalid_position

src/SourceUtils.mli → src/StringUtils.mli

@@ -1,4 +1,4 @@
-include module type of SourceUtilsData
+include module type of StringUtilsData
 
 (** [find_eol ~line_breaks read (pos, eof)] returns the end position of the first line and the length of the first newline sequence (if any) within the range [\[pos, end)]. If no newlines are found, then [None] is returned as the length.
 

src/tty/Tty.ml

@@ -97,7 +97,7 @@ struct
     let style = TtyStyle.highlight ~param:param.ansi param.severity tag in
     Format.fprintf fmt (highlight "%s")
       (Ansi.style_string ~param:param.ansi style)
-      (SourceUtils.replace_control ~tab_size:param.tab_size segment)
+      (StringUtils.replace_control ~tab_size:param.tab_size segment)
       (Ansi.reset_string ~param:param.ansi style)
 
   (* Current design:

test/TestSourceUtils.ml → test/TestStringUtils.ml

@@ -1,10 +1,10 @@
 let of_test name ~tab_size input expected =
   Alcotest.test_case name `Quick @@ fun () ->
   Alcotest.(check string) "Output matched" expected @@
-  Asai.SourceUtils.replace_control ~tab_size input
+  Asai.StringUtils.replace_control ~tab_size input
 
 let () =
-  Alcotest.run "SourceUtils" [
+  Alcotest.run "StringUtils" [
     "replace_control",
     [
       of_test "tab" ~tab_size:2 "123\t4\t" "123  4  ";

test/dune

@@ -4,8 +4,8 @@
  (libraries asai alcotest))
 
 (tests
- (names TestSourceUtils TestText)
- (modules TestSourceUtils TestText)
+ (names TestStringUtils TestText)
+ (modules TestStringUtils TestText)
  (libraries asai alcotest))
 
 (test