模块 Format

module Format: sig .. end

简介

您可以将此模块视为对 printf 功能的扩展，以提供自动换行功能。在您的常规 printf 格式字符串中添加美观打印注释会为您提供漂亮的缩进和换行。美观打印注释在函数 Format.fprintf 的文档中进行了描述。

您还可以使用此模块提供的显式美观打印框管理和打印函数。这种样式比简洁的 fprintf 格式字符串更基本但更冗长。

例如，序列 open_box 0; print_string "x ="; print_space ();
    print_int 1; close_box (); print_newline () 在美观打印框中打印 x = 1，可以简写为 printf "@[%s@ %i@]@." "x =" 1，甚至可以更短地写为 printf "@[x =@ %i@]@." 1。

此库的休闲用户经验法则

• 使用简单的美观打印框（如通过 open_box 0 获取的框）；
• 使用简单的断点提示，如通过 print_cut () 获取的提示（它输出一个简单的断点提示），或通过 print_space () 获取的提示（它输出一个空格，表示断点提示）；
• 打开美观打印框后，使用基本打印函数（例如 print_int 和 print_string）显示其内容；
• 打印完美观打印框的内容后，调用 close_box () 关闭该框；
• 在美观打印结束时，刷新美观打印器以显示所有剩余内容，例如，评估 print_newline ()。

如果没有任何打开的美观打印框，则美观打印命令的行为未定义。通过以下 open_ 函数之一打开的每个框都必须使用 close_box 关闭，以确保格式正确。否则，一些在框中打印的内容可能不会输出，或者可能格式不正确。

在交互式使用的情况下，每个短语都在标准美观打印器的初始状态下执行：在每个短语执行后，交互式系统会关闭所有打开的美观打印框，刷新所有待处理的文本，并重置标准美观打印器。

警告：将此模块的美观打印函数调用与 Stdlib 低级输出函数调用混合在一起可能会导致错误。

美观打印函数输出的内容会延迟到美观打印器队列中，并按顺序堆叠，以便计算正确的换行。相反，基本 I/O 输出函数会直接写入其输出设备。因此，基本 I/O 函数的输出可能会出现在之前调用的美观打印函数的输出之前。例如，
    Stdlib.print_string "<";
    Format.print_string "PRETTY";
    Stdlib.print_string ">";
    Format.print_string "TEXT";
    导致输出 <>PRETTYTEXT。

格式化器

type formatter 

美观打印框

美观打印引擎使用美观打印框和断点提示的概念来驱动美观打印器的缩进和换行行为。

每个不同的美观打印框类型都会引入一个特定的换行策略

• 在水平框内，断点提示永远不会换行（但行可能会在更深层的框中换行），
• 在垂直框内，断点提示总是换行，
• 在水平/垂直框内，如果框适合当前行，则断点提示永远不会换行，否则断点提示总是换行，
• 在压缩框内，断点提示永远不会换行，除非当前行没有更多空间。

请注意，换行策略是特定于框的：框的策略不决定内部框的策略。例如，如果一个垂直框嵌套在一个水平框中，则垂直框内的所有断点提示都会换行。

此外，在 最大缩进限制 后打开一个框会换行，无论该框最终是否适合该行。

val pp_open_box : formatter -> int -> unit

val open_box : int -> unit

val pp_close_box : formatter -> unit -> unit

val close_box : unit -> unit

val pp_open_hbox : formatter -> unit -> unit

val open_hbox : unit -> unit

val pp_open_vbox : formatter -> int -> unit

val open_vbox : int -> unit

val pp_open_hvbox : formatter -> int -> unit

val open_hvbox : int -> unit

val pp_open_hovbox : formatter -> int -> unit

val open_hovbox : int -> unit

格式化函数

val pp_print_string : formatter -> string -> unit

val print_string : string -> unit

val pp_print_bytes : formatter -> bytes -> unit

val print_bytes : bytes -> unit

val pp_print_as : formatter -> int -> string -> unit

val print_as : int -> string -> unit

val pp_print_int : formatter -> int -> unit

val print_int : int -> unit

val pp_print_float : formatter -> float -> unit

val print_float : float -> unit

val pp_print_char : formatter -> char -> unit

val print_char : char -> unit

val pp_print_bool : formatter -> bool -> unit

val print_bool : bool -> unit

val pp_print_nothing : formatter -> unit -> unit

断点提示

“断点提示”告诉美观打印器输出一些空格或换行，具体取决于当前美观打印框的拆分规则更适合哪种方式。

断点提示用于分隔打印项，并且是让美观打印器正确换行和缩进项所必需的。

简单的断点提示是

• “空格”：在适当情况下输出空格或换行，
• “剪切”：在适当情况下换行。

注意：“空格”和“换行”的概念对于美观打印引擎来说是抽象的，因为这些概念可以由程序员完全重新定义。但是，在美观打印器的默认设置中，“输出空格”简单地意味着打印一个空格字符（ASCII 码 32），而“换行”则意味着打印一个换行符（ASCII 码 10）。

val pp_print_space : formatter -> unit -> unit

val print_space : unit -> unit

val pp_print_cut : formatter -> unit -> unit

val print_cut : unit -> unit

val pp_print_break : formatter -> int -> int -> unit

val print_break : int -> int -> unit

val pp_print_custom_break : formatter ->
       fits:string * int * string -> breaks:string * int * string -> unit

[
  a;
  b;
  c;
]
   

printf "@[<v 0>[@;<0 2>@[<v 0>a;@,b;@,c@]%t]@]@\n"
  (pp_print_custom_break ~fits:("", 0, "") ~breaks:(";", 0, ""))
   

val pp_force_newline : formatter -> unit -> unit

val force_newline : unit -> unit

val pp_print_if_newline : formatter -> unit -> unit

val print_if_newline : unit -> unit

美观打印终止

val pp_print_flush : formatter -> unit -> unit

val print_flush : unit -> unit

val pp_print_newline : formatter -> unit -> unit

val print_newline : unit -> unit

边距

val pp_infinity : int

val pp_set_margin : formatter -> int -> unit

val set_margin : int -> unit

val pp_get_margin : formatter -> unit -> int

val get_margin : unit -> int

最大缩进限制

val pp_set_max_indent : formatter -> int -> unit

val set_max_indent : int -> unit

 set_margin 10; set_max_indent 5; printf "@[123456@[7@]89A@]@." 

    123456
    789A
  

 printf "@[123456@[7@]89@]@." 

 printf "@[123@[456@[7@]89@]A@]@." 

val pp_get_max_indent : formatter -> unit -> int

val get_max_indent : unit -> int

几何

几何函数可用于同时操作耦合变量，即边距和最大缩进限制。

type geometry = {

val check_geometry : geometry -> bool

val pp_set_geometry : formatter -> max_indent:int -> margin:int -> unit

val set_geometry : max_indent:int -> margin:int -> unit

val pp_safe_set_geometry : formatter -> max_indent:int -> margin:int -> unit

val safe_set_geometry : max_indent:int -> margin:int -> unit

val pp_update_geometry : formatter -> (geometry -> geometry) -> unit

val update_geometry : (geometry -> geometry) -> unit

val pp_get_geometry : formatter -> unit -> geometry

val get_geometry : unit -> geometry

最大格式化深度

最大格式化深度是同时打开的美化打印框的最大数量。

嵌套更深的框内的材料将以省略号的形式打印（更确切地说，是以 Format.get_ellipsis_text () 返回的文本形式打印）。

val pp_set_max_boxes : formatter -> int -> unit

val set_max_boxes : int -> unit

val pp_get_max_boxes : formatter -> unit -> int

val get_max_boxes : unit -> int

val pp_over_max_boxes : formatter -> unit -> bool

val over_max_boxes : unit -> bool

制表符框

制表符框将材料打印在分成固定长度单元格的行上。制表符框提供了一种简单的方式来显示左对齐文本的垂直列。

此框具有命令 set_tab 来定义单元格边界，以及命令 print_tab 来在单元格之间移动，并在行上没有更多单元格可打印时拆分行。

注意：制表符框内的打印是面向行的，因此在制表符框内任意拆分行会导致糟糕的渲染效果。但是，控制使用制表符框允许在模块 Format 中简单地打印列。

val pp_open_tbox : formatter -> unit -> unit

val open_tbox : unit -> unit

val pp_close_tbox : formatter -> unit -> unit

val close_tbox : unit -> unit

val pp_set_tab : formatter -> unit -> unit

val set_tab : unit -> unit

val pp_print_tab : formatter -> unit -> unit

val print_tab : unit -> unit

val pp_print_tbreak : formatter -> int -> int -> unit

val print_tbreak : int -> int -> unit

省略号

val pp_set_ellipsis_text : formatter -> string -> unit

val set_ellipsis_text : string -> unit

val pp_get_ellipsis_text : formatter -> unit -> string

val get_ellipsis_text : unit -> string

语义标签

type stag = ..

type stag += RGB of {r:int;g:int;b:int}

type tag = string 

type stag += 

val pp_open_stag : formatter -> stag -> unit

val open_stag : stag -> unit

val pp_close_stag : formatter -> unit -> unit

val close_stag : unit -> unit

val pp_set_tags : formatter -> bool -> unit

val set_tags : bool -> unit

val pp_set_print_tags : formatter -> bool -> unit

val set_print_tags : bool -> unit

val pp_set_mark_tags : formatter -> bool -> unit

val set_mark_tags : bool -> unit

val pp_get_print_tags : formatter -> unit -> bool

val get_print_tags : unit -> bool

val pp_get_mark_tags : formatter -> unit -> bool

val get_mark_tags : unit -> bool

val pp_set_formatter_out_channel : formatter -> out_channel -> unit

val set_formatter_out_channel : out_channel -> unit

val pp_set_formatter_output_functions : formatter -> (string -> int -> int -> unit) -> (unit -> unit) -> unit

val set_formatter_output_functions : (string -> int -> int -> unit) -> (unit -> unit) -> unit

val pp_get_formatter_output_functions : formatter -> unit -> (string -> int -> int -> unit) * (unit -> unit)

val get_formatter_output_functions : unit -> (string -> int -> int -> unit) * (unit -> unit)

重新定义格式化器输出

模块 Format 足够灵活，可以让你完全重新定义美化打印输出的含义：你可以提供自己的函数来定义如何处理缩进、行拆分，甚至打印所有必须打印的字符！

重新定义输出函数

type formatter_out_functions = {

val pp_set_formatter_out_functions : formatter -> formatter_out_functions -> unit

val set_formatter_out_functions : formatter_out_functions -> unit

val pp_get_formatter_out_functions : formatter -> unit -> formatter_out_functions

val get_formatter_out_functions : unit -> formatter_out_functions

重新定义语义标签操作

type formatter_stag_functions = {

val pp_set_formatter_stag_functions : formatter -> formatter_stag_functions -> unit

val set_formatter_stag_functions : formatter_stag_functions -> unit

val pp_get_formatter_stag_functions : formatter -> unit -> formatter_stag_functions

val get_formatter_stag_functions : unit -> formatter_stag_functions

定义格式化器

定义新的格式化程序允许在多个输出设备上并行输出不相关的材料。格式化程序的所有参数都是特定于格式化程序的：右边界、最大缩进限制、同时打开的最大漂亮打印框数、省略号等，都是特定于每个格式化程序的，可以独立地进行固定。

例如，给定一个 Buffer.t 缓冲区 b，Format.formatter_of_buffer b 返回一个使用缓冲区 b 作为其输出设备的新格式化程序。类似地，给定一个 out_channel 输出通道 oc，Format.formatter_of_out_channel oc 返回一个使用通道 oc 作为其输出设备的新格式化程序。

或者，给定 out_funs，一个完整的格式化程序输出函数集，那么 Format.formatter_of_out_functions out_funs 计算一个使用这些函数进行输出的新格式化程序。

val formatter_of_out_channel : out_channel -> formatter

val synchronized_formatter_of_out_channel : out_channel -> formatter Domain.DLS.key

val std_formatter : formatter

val get_std_formatter : unit -> formatter

val err_formatter : formatter

val get_err_formatter : unit -> formatter

val formatter_of_buffer : Buffer.t -> formatter

val stdbuf : Buffer.t

val get_stdbuf : unit -> Buffer.t

val str_formatter : formatter

val get_str_formatter : unit -> formatter

val flush_str_formatter : unit -> string

val make_formatter : (string -> int -> int -> unit) -> (unit -> unit) -> formatter

    make_formatter
      (Stdlib.output_substring oc)
      (fun () -> Stdlib.flush oc)
  

val make_synchronized_formatter : (string -> int -> int -> unit) ->
       (unit -> unit) -> formatter Domain.DLS.key

val formatter_of_out_functions : formatter_out_functions -> formatter

符号美观打印

符号漂亮打印是使用符号格式化程序进行的漂亮打印，即输出符号漂亮打印项目的格式化程序。

使用符号格式化程序时，将执行所有常规的漂亮打印活动，但输出材料是符号化的，并存储在输出项目缓冲区中。在漂亮打印结束时，刷新输出缓冲区允许在执行低级输出操作之前对符号输出进行后处理。

在实践中，首先使用以下代码定义一个符号输出缓冲区 b：

• let sob = make_symbolic_output_buffer (). 然后使用以下代码定义一个符号格式化程序：
• let ppf = formatter_of_symbolic_output_buffer sob

像往常一样使用符号格式化程序 ppf，并在漂亮打印结束时通过使用以下代码刷新符号输出缓冲区 sob 来检索符号项目：

• flush_symbolic_output_buffer sob.

type symbolic_output_item = 

type symbolic_output_buffer 

val make_symbolic_output_buffer : unit -> symbolic_output_buffer

val clear_symbolic_output_buffer : symbolic_output_buffer -> unit

val get_symbolic_output_buffer : symbolic_output_buffer -> symbolic_output_item list

val flush_symbolic_output_buffer : symbolic_output_buffer -> symbolic_output_item list

val add_symbolic_output_item : symbolic_output_buffer -> symbolic_output_item -> unit

val formatter_of_symbolic_output_buffer : symbolic_output_buffer -> formatter

便捷格式化函数。

val pp_print_iter : ?pp_sep:(formatter -> unit -> unit) ->
       (('a -> unit) -> 'b -> unit) ->
       (formatter -> 'a -> unit) -> formatter -> 'b -> unit

val pp_print_list : ?pp_sep:(formatter -> unit -> unit) ->
       (formatter -> 'a -> unit) -> formatter -> 'a list -> unit

val pp_print_array : ?pp_sep:(formatter -> unit -> unit) ->
       (formatter -> 'a -> unit) -> formatter -> 'a array -> unit

val pp_print_seq : ?pp_sep:(formatter -> unit -> unit) ->
       (formatter -> 'a -> unit) ->
       formatter -> 'a Seq.t -> unit

val pp_print_text : formatter -> string -> unit

val pp_print_option : ?none:(formatter -> unit -> unit) ->
       (formatter -> 'a -> unit) -> formatter -> 'a option -> unit

val pp_print_result : ok:(formatter -> 'a -> unit) ->
       error:(formatter -> 'e -> unit) ->
       formatter -> ('a, 'e) result -> unit

val pp_print_either : left:(formatter -> 'a -> unit) ->
       right:(formatter -> 'b -> unit) ->
       formatter -> ('a, 'b) Either.t -> unit

格式化美观打印

模块 Format 提供了一套完整的 printf 类函数，用于使用格式字符串规范进行漂亮打印。

可以在格式字符串中添加特定注释，以向漂亮打印引擎提供漂亮打印命令。

这些注释使用 @ 字符在格式字符串中引入。例如，@  表示空格断开，@, 表示切割，@[ 打开一个新框，@] 关闭最后一个打开的框。

val fprintf : formatter -> ('a, formatter, unit) format -> 'a

fprintf ff fmt arg1 ... argN 根据格式字符串 fmt 格式化参数 arg1 到 argN，并将生成的字符串输出到格式化程序 ff 上。

格式字符串 fmt 是一个包含三种类型对象的字符字符串：普通字符、Printf 模块中指定的转换说明符，以及特定于 Format 模块的漂亮打印指示。

漂亮打印指示字符由 @ 字符引入，其含义如下：

• @[：打开漂亮打印框。框的类型和偏移量可以可选地使用以下语法指定：< 字符，后跟可选的框类型指示，然后是可选的整数偏移量，最后是关闭的 > 字符。漂亮打印框类型是 h、v、hv、b 或 hov 之一。'h' 代表 '水平' 漂亮打印框，'v' 代表 '垂直' 漂亮打印框，'hv' 代表 '水平/垂直' 漂亮打印框，'b' 代表 '水平或垂直' 漂亮打印框，展示缩进，'hov' 代表简单的 '水平或垂直' 漂亮打印框。例如，@[<hov 2> 打开一个缩进为 2 的 '水平或垂直' 漂亮打印框，如使用 open_hovbox 2 获得的结果。有关漂亮打印框的更多详细信息，请参阅各种框打开函数 open_*box。
• @]：关闭最近打开的漂亮打印框。
• @,：输出 '切割' 断点提示，类似于 print_cut ()。
• @ ：输出 '空格' 断点提示，类似于 print_space ()。
• @;：输出 '完整' 断点提示，类似于 print_break。断点提示的 nspaces 和 offset 参数可以可选地使用以下语法指定：< 字符，后跟整数 nspaces 值，然后是整数 offset，最后是关闭的 > 字符。如果没有提供参数，则完整断点默认为 '空格' 断点提示。
• @.：刷新漂亮打印器并分割行，类似于 print_newline ()。
• @<n>：将下一个项目打印为长度为 n 的项目。因此，printf "@<0>%s" arg 将 arg 打印为零长度字符串。如果 @<n> 后面没有转换说明符，则格式中的下一个字符将被打印为长度为 n 的字符。
• @{：打开语义标签。标签的名称可以使用以下语法可选地指定：< 字符，后跟可选的字符串说明，最后是关闭的 > 字符。字符串说明是任何不包含关闭字符 '>' 的字符字符串。如果省略，则标签名称默认为空字符串。有关语义标签的更多详细信息，请参阅函数 Format.open_stag 和 Format.close_stag。
• @}：关闭最近打开的语义标签。
• @?：刷新漂亮打印器，类似于 print_flush ()。这等效于转换 %!。
• @\n：强制换行，类似于 force_newline ()，而不是漂亮打印的正常方式，您应该优先在垂直漂亮打印框内使用断点提示。

注意：为了防止将 @ 字符解释为漂亮打印指示，请使用 % 字符对其进行转义。旧的引号模式 @@ 已过时，因为它与字符 '@' 的格式化输入解释不兼容。

示例：printf "@[%s@ %d@]@." "x =" 1 等效于 open_box (); print_string "x ="; print_space ();
   print_int 1; close_box (); print_newline ()。它在漂亮打印的 '水平或垂直' 框内打印 x = 1。

val printf : ('a, formatter, unit) format -> 'a

val eprintf : ('a, formatter, unit) format -> 'a

val sprintf : ('a, unit, string) format -> 'a

val asprintf : ('a, formatter, unit, string) format4 -> 'a

val dprintf : ('a, formatter, unit, formatter -> unit) format4 -> 'a

  let t = Format.dprintf "%i@ %i@ %i" 1 2 3 in
  ...
  Format.printf "@[<v>%t@]" t

val ifprintf : formatter -> ('a, formatter, unit) format -> 'a

带有继续的格式化漂亮打印。

val kfprintf : (formatter -> 'a) ->
       formatter -> ('b, formatter, unit, 'a) format4 -> 'b

val kdprintf : ((formatter -> unit) -> 'a) ->
       ('b, formatter, unit, 'a) format4 -> 'b

val ikfprintf : (formatter -> 'a) ->
       formatter -> ('b, formatter, unit, 'a) format4 -> 'b

val ksprintf : (string -> 'a) -> ('b, unit, string, 'a) format4 -> 'b

val kasprintf : (string -> 'a) -> ('b, formatter, unit, 'a) format4 -> 'b

示例

一些预热示例，以了解如何使用 Format。

我们有一个 l 对列表，它们是 (int * bool)，顶层为我们打印这些对

# let l = List.init 20 (fun n -> n, n mod 2 = 0)
  val l : (int * bool) list =
  [(0, true); (1, false); (2, true); (3, false); (4, true); (5, false);
   (6, true); (7, false); (8, true); (9, false); (10, true); (11, false);
   (12, true); (13, false); (14, true); (15, false); (16, true); (17, false);
   (18, true); (19, false)]
 

如果我们想在没有顶层魔法的情况下自己打印它，我们可以尝试这样做

  # let pp_pair out (x,y) = Format.fprintf out "(%d, %b)" x y
  val pp_pair : Format.formatter -> int * bool -> unit = <fun>
  # Format.printf "l: [@[<hov>%a@]]@."
    Format.(pp_print_list ~pp_sep:(fun out () -> fprintf out ";@ ") pp_pair) l
    l: [(0, true); (1, false); (2, true); (3, false); (4, true); (5, false);
        (6, true); (7, false); (8, true); (9, false); (10, true); (11, false);
        (12, true); (13, false); (14, true); (15, false); (16, true);
        (17, false); (18, true); (19, false)]

  

简而言之，它的作用是

• pp_pair 打印一个用 "(" ")" 包裹的 bool*int 对。它接收一个格式化器（格式化发生在其中），以及对本身。打印完成后，它返回 ()。

• Format.printf "l = [@[<hov>%a@]]@." ... l 类似于 printf，但具有额外的格式化指令（用 "@" 表示）。对 "@[<hov>" 和 "@]" 是一个 '水平或垂直' 框。

• "@." 使用换行符结束格式化。它类似于 "\n"，但它也了解 Format.formatter 的状态。不要在 Format 中使用 "\n"。

• "%a" 是一种格式化指令，类似于 printf 中的 "%d" 或 "%s"。但是，"%d" 打印整数，"%s" 打印字符串，而 "%a" 接受一个打印机（类型为 Format.formatter -> 'a -> unit）和一个值（类型为 'a），并将打印机应用于该值。这是打印机组合性的关键。

• 我们使用 Format.pp_print_list ~pp_sep:(...) pp_pair 构建一个列表打印机。 pp_print_list 接受一个元素打印机并返回一个列表打印机。如果提供 ?pp_sep 可选参数，则会在每个元素之间调用它以打印分隔符。

• 这里，作为分隔符，我们使用 (fun out () -> Format.fprintf out ";@ ")。它打印 ";"，然后是 "@ "，这是一个断开空格（要么打印 " "，要么如果框即将溢出则打印换行符）。这个 "@ " 负责将列表打印分成几行。

如果我们省略 "@ "，我们会得到一个丑陋的单行打印

# Format.printf "l: [@[<hov>%a@]]@."
      Format.(pp_print_list ~pp_sep:(fun out () -> fprintf out "; ") pp_pair) l
  l: [(0, true); (1, false); (2, true); (* ... *); (18, true); (19, false)]
- : unit = ()
    

通常，为程序中的重要类型定义自定义打印机是一个好习惯。例如，如果您要这样定义基本几何类型

  type point = {
    x: float;
    y: float;
  }

  type rectangle = {
    ll: point; (* lower left *)
    ur: point; (* upper right *)
  }
  

为了调试目的，或在日志或控制台中显示信息，为这些类型定义打印机将很方便。这是一个示例。请注意，"%.3f" 是一个最多精确到小数点后三位的小数打印机；"%f" 会打印所有必需的位数，这有点冗长；"%h" 是一个十六进制浮点数打印机。

  let pp_point out (p:point) =
    Format.fprintf out "{ @[x=%.3f;@ y=%.3f@] }" p.x p.y

  let pp_rectangle out (r:rectangle) =
    Format.fprintf out "{ @[ll=%a;@ ur=%a@] }"
      pp_point r.ll pp_point r.ur
  

在 .mli 文件中，我们可以有

    val pp_point : Format.formatter -> point -> unit

    val pp_rectangle : Format.formatter -> rectangle -> unit
  

这些打印机现在可以在其他打印机内部使用 "%a"。

 # Format.printf "some rectangle: %a@."
        (Format.pp_print_option pp_rectangle)
        (Some {ll={x=1.; y=2.}; ur={x=42.; y=500.12345}})
  some rectangle: { l={ x=1.000; y=2.000 }; ur={ x=42.000; y=500.123 } }

  # Format.printf "no rectangle: %a@."
        (Format.pp_option pp_rectangle)
        None
  no rectangle:
  

让我们看看如何将 pp_print_option（选项打印器）与我们新定义的矩形打印器结合起来，就像我们之前使用 pp_print_list 一样。

更多详细的教程，请参阅 "使用 Format 模块"。

最后说明：Format 模块是一个起点。OCaml 生态系统中有一些库可以使格式化更轻松、更具表现力，包含更多组合器，更简洁的名称等。例如 Fmt 库。

还可以使用 https://github.com/ocaml-ppx/ppx_deriving 或类似的 ppx 衍生器，从类型定义自动生成美化打印器。