模块 Stdlib.Format

module Format: Format

简介

您可以将此模块视为对 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 Format.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> 使用 open_hovbox 2 打开一个缩进为 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”是一个小数点后最多3位的float打印机；"%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派生器来自动从类型定义派生漂亮打印机。