Merge pull request #412 from Leonidas-from-XIV/normal-markdown-rename

Leonidas-from-XIV · web-flow · commit 0644a331fbff · 2023-01-20T16:29:01.000+01:00
`Normal` -&gt; `Markdown` rename
diff --git a/CHANGES.md b/CHANGES.md
@@ -21,6 +21,8 @@
 #### Changed
 
 - Preserve indentation in multiline OCaml blocks in .mli files (#395, @panglesd)
+- Rename the `Normal` syntax to `Markdown` to better explain what the syntax is
+  and moved it to `Mdx.Syntax` (#412, @Leonidas-from-XIV)
 
 #### Fixed
 
diff --git a/bin/cli.mli b/bin/cli.mli
@@ -2,7 +2,7 @@ open Cmdliner.Term
 
 val named : ('a -> 'b) -> 'a t -> 'b t
 val non_deterministic : [> `Non_deterministic of bool ] t
-val syntax : [> `Syntax of Mdx.syntax option ] t
+val syntax : [> `Syntax of Mdx.Syntax.t option ] t
 val file : [> `File of string ] t
 val section : [> `Section of string option ] t
 val silent_eval : [> `Silent_eval of bool ] t
diff --git a/bin/main.ml b/bin/main.ml
@@ -20,7 +20,7 @@ let cmds = [ Test.cmd; Pp.cmd; Deps.cmd; Dune_gen.cmd ]
 let main (`Setup ()) = `Help (`Pager, None)
 
 let info =
-  let doc = "Execute markdown files." in
+  let doc = "Execute code in documentation files." in
   let man = [] in
   Cmd.info "ocaml-mdx" ~version:"%%VERSION%%" ~doc ~man
 
diff --git a/bin/pp.ml b/bin/pp.ml
@@ -73,7 +73,7 @@ let executable_contents (block : Block.t) =
          else (line, add_semi_semi contents))
 
 let run (`Setup ()) (`File file) (`Section section) =
-  Mdx.parse_file Normal file >>! fun t ->
+  Mdx.parse_file Markdown file >>! fun t ->
   let t =
     match section with
     | None -> t
diff --git a/bin/test.ml b/bin/test.ml
@@ -53,6 +53,6 @@ let term =
     $ Cli.silent $ Cli.verbose_findlib $ Cli.prelude $ Cli.prelude_str
     $ Cli.file $ Cli.section $ Cli.root $ Cli.force_output $ Cli.output)
 
-let doc = "Test markdown files."
+let doc = "Test code in documentation files."
 let info = Cmd.info "test" ~doc
 let cmd = Cmd.v info term
diff --git a/bin/test/main.ml b/bin/test/main.ml
@@ -82,7 +82,7 @@ let term =
 
 let info =
   let man = [] in
-  let doc = "Test markdown files." in
+  let doc = "Execute and test code in documentation files." in
   Cmd.info "ocaml-mdx-test" ~version:"%%VERSION%%" ~doc ~man
 
 let cmd = Cmd.v info term
diff --git a/lib/block.ml b/lib/block.ml
@@ -173,7 +173,7 @@ let pp_footer ?syntax ppf _ =
   match syntax with
   | Some Syntax.Mli -> Fmt.string ppf "]}"
   | Some Syntax.Cram -> Fmt.string ppf "\n"
-  | Some Syntax.Normal | None -> Fmt.string ppf "```\n"
+  | Some Syntax.Markdown | None -> Fmt.string ppf "```\n"
 
 let pp_legacy_labels ppf = function
   | [] -> ()
@@ -191,7 +191,7 @@ let pp_labels ?syntax ppf labels =
       | [ Non_det (Some Nd_command) ] ->
           Fmt.pf ppf "<-- non-deterministic command\n"
       | _ -> failwith "cannot happen: checked during parsing")
-  | Some Syntax.Normal | None -> (
+  | Some Syntax.Markdown | None -> (
       match labels with
       | [] -> ()
       | l ->
@@ -216,7 +216,7 @@ let pp_header ?syntax ppf t =
       in
       Fmt.pf ppf "{%a%a[" pp_lang_header lang_headers pp_labels other_labels
   | Some Syntax.Cram -> pp_labels ?syntax ppf t.labels
-  | Some Syntax.Normal | None ->
+  | Some Syntax.Markdown | None ->
       if t.legacy_labels then
         Fmt.pf ppf "```%a%a"
           Fmt.(option Header.pp)
diff --git a/lib/document.ml b/lib/document.ml
@@ -14,7 +14,6 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  *)
 
-type syntax = Syntax.t = Normal | Cram | Mli
 type section = int * string
 type line = Section of section | Text of string | Block of Block.t
 type t = line list
diff --git a/lib/document.mli b/lib/document.mli
@@ -16,20 +16,18 @@
 
 (** {2 Lines} *)
 
-type syntax = Syntax.t = Normal | Cram | Mli
-
 (** The type for the lines of a markdown or cram file. *)
 type line = Section of (int * string) | Text of string | Block of Block.t
 
-val pp_line : ?syntax:syntax -> line Fmt.t
+val pp_line : ?syntax:Syntax.t -> line Fmt.t
 (** [pp_line] is the pretty-printer for markdown or cram lines. *)
 
 (** {2 Document} *)
 
 type t = line list
 (** The type for mdx documents. *)
 
-val pp : ?syntax:syntax -> t Fmt.t
+val pp : ?syntax:Syntax.t -> t Fmt.t
 (** [pp] is the pretty printer for mdx documents. Should be idempotent
    with {!of_string}. *)
 
diff --git a/lib/mdx.ml b/lib/mdx.ml
@@ -71,7 +71,7 @@ let parse l =
 let parse_lexbuf syntax Misc.{ string; lexbuf } =
   match syntax with
   | Syntax.Mli -> Mli_parser.parse_mli string
-  | Normal ->
+  | Markdown ->
       Util.Result.to_error_list @@ Lexer_mdx.markdown_token lexbuf >>= parse
   | Cram -> Util.Result.to_error_list @@ Lexer_mdx.cram_token lexbuf >>= parse
 
@@ -80,7 +80,7 @@ let parse_file syntax f = Misc.load_file ~filename:f |> parse_lexbuf syntax
 let of_string syntax s =
   match syntax with
   | Syntax.Mli -> Mli_parser.parse_mli s
-  | Syntax.Normal | Syntax.Cram ->
+  | Syntax.Markdown | Syntax.Cram ->
       Misc.{ lexbuf = Lexing.from_string s; string = s } |> parse_lexbuf syntax
 
 let dump_line ppf (l : line) =
@@ -107,15 +107,15 @@ let write_file ~outfile content =
   output_string oc content;
   close_out oc
 
-let run_to_stdout ?(syntax = Normal) ~f infile =
+let run_to_stdout ?(syntax = Syntax.Markdown) ~f infile =
   let+ _, corrected = run_str ~syntax ~f infile in
   print_string corrected
 
-let run_to_file ?(syntax = Normal) ~f ~outfile infile =
+let run_to_file ?(syntax = Syntax.Markdown) ~f ~outfile infile =
   let+ _, corrected = run_str ~syntax ~f infile in
   write_file ~outfile corrected
 
-let run ?(syntax = Normal) ?(force_output = false) ~f infile =
+let run ?(syntax = Syntax.Markdown) ?(force_output = false) ~f infile =
   let outfile = infile ^ ".corrected" in
   let+ test_result, corrected = run_str ~syntax ~f infile in
   match (force_output, test_result) with
diff --git a/lib/mdx.mli b/lib/mdx.mli
@@ -46,34 +46,34 @@ val dump : line list Fmt.t
 
 (** {2 Document} *)
 
-val of_string : syntax -> string -> (t, [ `Msg of string ] list) result
+val of_string : Syntax.t -> string -> (t, [ `Msg of string ] list) result
 (** [of_string syntax s] is the document [t] such that
     [to_string ~syntax t = s]. *)
 
-val parse_file : syntax -> string -> (t, [ `Msg of string ] list) result
+val parse_file : Syntax.t -> string -> (t, [ `Msg of string ] list) result
 (** [parse_file s] is {!of_string} of [s]'s contents. *)
 
 (** {2 Evaluation} *)
 
 val run_to_stdout :
-  ?syntax:syntax ->
+  ?syntax:Syntax.t ->
   f:(string -> t -> string) ->
   string ->
   (unit, [ `Msg of string ] list) result
 (** [run_to_stdout ?syntax ~f file] runs the callback [f] on the raw and
-    structured content of [file], as specified  by [syntax] (defaults to [Normal]).
+    structured content of [file], as specified  by [syntax] (defaults to [Markdown]).
     The returned corrected version is then written to stdout. *)
 
 val run_to_file :
-  ?syntax:syntax ->
+  ?syntax:Syntax.t ->
   f:(string -> t -> string) ->
   outfile:string ->
   string ->
   (unit, [ `Msg of string ] list) result
 (** Same as [run_to_stdout] but writes the corrected version to [outfile]*)
 
 val run :
-  ?syntax:syntax ->
+  ?syntax:Syntax.t ->
   ?force_output:bool ->
   f:(string -> t -> string) ->
   string ->
diff --git a/lib/syntax.ml b/lib/syntax.ml
@@ -1,7 +1,7 @@
-type t = Normal | Cram | Mli
+type t = Markdown | Cram | Mli
 
 let pp fs = function
-  | Normal -> Fmt.string fs "normal"
+  | Markdown -> Fmt.string fs "markdown"
   | Cram -> Fmt.string fs "cram"
   | Mli -> Fmt.string fs "mli"
 
@@ -10,12 +10,12 @@ let equal x y = x = y
 let infer ~file =
   match Filename.extension file with
   | ".t" -> Some Cram
-  | ".md" -> Some Normal
+  | ".md" -> Some Markdown
   | ".mli" -> Some Mli
   | _ -> None
 
 let of_string = function
-  | "markdown" | "normal" -> Some Normal
+  | "markdown" | "normal" -> Some Markdown
   | "cram" -> Some Cram
   | "mli" -> Some Mli
   | _ -> None
diff --git a/lib/syntax.mli b/lib/syntax.mli
@@ -1,4 +1,4 @@
-type t = Normal | Cram | Mli
+type t = Markdown | Cram | Mli
 
 val pp : Format.formatter -> t -> unit
 val equal : t -> t -> bool
diff --git a/test/lib/test_dep.ml b/test/lib/test_dep.ml
@@ -50,7 +50,7 @@ let test_of_line =
     let test_name = Printf.sprintf "of_line: %S" line_des in
     let test_fun () =
       let actual =
-        let+ lines = Mdx.of_string Mdx.Normal lines in
+        let+ lines = Mdx.of_string Mdx.Syntax.Markdown lines in
         Mdx.Dep.of_lines lines
       in
       Alcotest.(check (result (list Testable.dep) (list Testable.msg)))
diff --git a/test/lib/test_syntax.ml b/test/lib/test_syntax.ml
@@ -15,7 +15,7 @@ let test_infer =
   in
   [
     make_test ~file:"" ~expected:None ();
-    make_test ~file:"test.md" ~expected:(Some Normal) ();
+    make_test ~file:"test.md" ~expected:(Some Markdown) ();
     make_test ~file:"test.t" ~expected:(Some Cram) ();
     make_test ~file:"test.ml" ~expected:None ();
     make_test ~file:"test.mli" ~expected:(Some Mli) ();
