diff --git a/src/lib_protocol_environment/sigs/v1/format.mli b/src/lib_protocol_environment/sigs/v1/format.mli index 927b154a8..73cc075b8 100644 --- a/src/lib_protocol_environment/sigs/v1/format.mli +++ b/src/lib_protocol_environment/sigs/v1/format.mli @@ -13,6 +13,19 @@ (* *) (**************************************************************************) +(* TEZOS CHANGES + + * Import version 4.06.1 + * Remove channel functions + * Remove toplevel effect based functions + * Remove deprecated functions + * Remove redirecting the standard formatter output + * Remove redefining formatter output and output functions + * Remove redefining semantic tag operations (too complex and + imperative for the need of error message generation) + * Remove defining formatters and symbolic pretty printing +*) + (** Pretty-printing. This module implements a pretty-printing facility to format values @@ -136,7 +149,6 @@ type formatter *) val pp_open_box : formatter -> int -> unit -val open_box : int -> unit (** [pp_open_box ppf d] opens a new compacting pretty-printing box with offset [d] in the formatter [ppf]. @@ -159,11 +171,9 @@ val open_box : int -> unit val pp_close_box : formatter -> unit -> unit -val close_box : unit -> unit (** Closes the most recently open pretty-printing box. *) val pp_open_hbox : formatter -> unit -> unit -val open_hbox : unit -> unit (** [pp_open_hbox ppf ()] opens a new 'horizontal' pretty-printing box. This box prints material on a single line. @@ -173,7 +183,6 @@ val open_hbox : unit -> unit *) val pp_open_vbox : formatter -> int -> unit -val open_vbox : int -> unit (** [pp_open_vbox ppf d] opens a new 'vertical' pretty-printing box with offset [d]. @@ -186,7 +195,6 @@ val open_vbox : int -> unit *) val pp_open_hvbox : formatter -> int -> unit -val open_hvbox : int -> unit (** [pp_open_hvbox ppf d] opens a new 'horizontal/vertical' pretty-printing box with offset [d]. @@ -198,7 +206,6 @@ val open_hvbox : int -> unit *) val pp_open_hovbox : formatter -> int -> unit -val open_hovbox : int -> unit (** [pp_open_hovbox ppf d] opens a new 'horizontal-or-vertical' pretty-printing box with offset [d]. @@ -214,29 +221,23 @@ val open_hovbox : int -> unit (** {1 Formatting functions} *) val pp_print_string : formatter -> string -> unit -val print_string : string -> unit (** [pp_print_string ppf s] prints [s] in the current pretty-printing box. *) val pp_print_as : formatter -> int -> string -> unit -val print_as : int -> string -> unit (** [pp_print_as ppf len s] prints [s] in the current pretty-printing box. The pretty-printer formats [s] as if it were of length [len]. *) val pp_print_int : formatter -> int -> unit -val print_int : int -> unit (** Print an integer in the current pretty-printing box. *) val pp_print_float : formatter -> float -> unit -val print_float : float -> unit (** Print a floating point number in the current pretty-printing box. *) val pp_print_char : formatter -> char -> unit -val print_char : char -> unit (** Print a character in the current pretty-printing box. *) val pp_print_bool : formatter -> bool -> unit -val print_bool : bool -> unit (** Print a boolean in the current pretty-printing box. *) (** {1:breaks Break hints} *) @@ -261,7 +262,6 @@ val print_bool : bool -> unit *) val pp_print_space : formatter -> unit -> unit -val print_space : unit -> unit (** [pp_print_space ppf ()] emits a 'space' break hint: the pretty-printer may split the line at this point, otherwise it prints one space. @@ -270,7 +270,6 @@ val print_space : unit -> unit *) val pp_print_cut : formatter -> unit -> unit -val print_cut : unit -> unit (** [pp_print_cut ppf ()] emits a 'cut' break hint: the pretty-printer may split the line at this point, otherwise it prints nothing. @@ -279,7 +278,6 @@ val print_cut : unit -> unit *) val pp_print_break : formatter -> int -> int -> unit -val print_break : int -> int -> unit (** [pp_print_break ppf nspaces offset] emits a 'full' break hint: the pretty-printer may split the line at this point, otherwise it prints [nspaces] spaces. @@ -289,7 +287,6 @@ val print_break : int -> int -> unit *) val pp_force_newline : formatter -> unit -> unit -val force_newline : unit -> unit (** Force a new line in the current pretty-printing box. The pretty-printer must split the line at this point, @@ -301,7 +298,6 @@ val force_newline : unit -> unit *) val pp_print_if_newline : formatter -> unit -> unit -val print_if_newline : unit -> unit (** Execute the next formatting command if the preceding line has just been split. Otherwise, ignore the next formatting command. @@ -310,7 +306,6 @@ val print_if_newline : unit -> unit (** {1 Pretty-printing termination} *) val pp_print_flush : formatter -> unit -> unit -val print_flush : unit -> unit (** End of pretty-printing: resets the pretty-printer to initial state. All open pretty-printing boxes are closed, all pending text is printed. @@ -336,7 +331,6 @@ val print_flush : unit -> unit *) val pp_print_newline : formatter -> unit -> unit -val print_newline : unit -> unit (** End of pretty-printing: resets the pretty-printer to initial state. All open pretty-printing boxes are closed, all pending text is printed. @@ -352,7 +346,6 @@ val print_newline : unit -> unit (** {1 Margin} *) val pp_set_margin : formatter -> int -> unit -val set_margin : int -> unit (** [pp_set_margin ppf d] sets the right margin to [d] (in characters): the pretty-printer splits lines that overflow the right margin according to the break hints given. @@ -366,13 +359,11 @@ val set_margin : int -> unit *) val pp_get_margin : formatter -> unit -> int -val get_margin : unit -> int (** Returns the position of the right margin. *) (** {1 Maximum indentation limit} *) val pp_set_max_indent : formatter -> int -> unit -val set_max_indent : int -> unit (** [pp_set_max_indent ppf d] sets the maximum indentation limit of lines to [d] (in characters): once this limit is reached, new pretty-printing boxes are rejected to the @@ -387,7 +378,6 @@ val set_max_indent : int -> unit *) val pp_get_max_indent : formatter -> unit -> int -val get_max_indent : unit -> int (** Return the maximum indentation limit (in characters). *) (** {1 Maximum formatting depth} *) @@ -400,7 +390,6 @@ val get_max_indent : unit -> int *) val pp_set_max_boxes : formatter -> int -> unit -val set_max_boxes : int -> unit (** [pp_set_max_boxes ppf max] sets the maximum number of pretty-printing boxes simultaneously open. @@ -411,13 +400,11 @@ val set_max_boxes : int -> unit *) val pp_get_max_boxes : formatter -> unit -> int -val get_max_boxes : unit -> int (** Returns the maximum number of pretty-printing boxes allowed before ellipsis. *) val pp_over_max_boxes : formatter -> unit -> bool -val over_max_boxes : unit -> bool (** Tests if the maximum number of pretty-printing boxes allowed have already been opened. *) @@ -441,7 +428,6 @@ val over_max_boxes : unit -> bool *) val pp_open_tbox : formatter -> unit -> unit -val open_tbox : unit -> unit (** [open_tbox ()] opens a new tabulation box. This box prints lines separated into cells of fixed width. @@ -456,15 +442,12 @@ val open_tbox : unit -> unit *) val pp_close_tbox : formatter -> unit -> unit -val close_tbox : unit -> unit (** Closes the most recently opened tabulation box. *) val pp_set_tab : formatter -> unit -> unit -val set_tab : unit -> unit (** Sets a tabulation marker at current insertion point. *) val pp_print_tab : formatter -> unit -> unit -val print_tab : unit -> unit (** [print_tab ()] emits a 'next' tabulation break hint: if not already set on a tabulation marker, the insertion point moves to the first tabulation marker on the right, or the pretty-printer splits the line and insertion @@ -473,7 +456,6 @@ val print_tab : unit -> unit It is equivalent to [print_tbreak 0 0]. *) val pp_print_tbreak : formatter -> int -> int -> unit -val print_tbreak : int -> int -> unit (** [print_tbreak nspaces offset] emits a 'full' tabulation break hint. If not already set on a tabulation marker, the insertion point moves to the @@ -491,13 +473,11 @@ val print_tbreak : int -> int -> unit (** {1 Ellipsis} *) val pp_set_ellipsis_text : formatter -> string -> unit -val set_ellipsis_text : string -> unit (** Set the text of the ellipsis printed when too many pretty-printing boxes are open (a single dot, [.], by default). *) val pp_get_ellipsis_text : formatter -> unit -> string -val get_ellipsis_text : unit -> string (** Return the text of the ellipsis. *) (** {1:tags Semantic tags} *) @@ -575,7 +555,6 @@ type tag = string *) val pp_open_tag : formatter -> string -> unit -val open_tag : tag -> unit (** [pp_open_tag ppf t] opens the semantic tag named [t]. The [print_open_tag] tag-printing function of the formatter is called with @@ -584,7 +563,6 @@ val open_tag : tag -> unit *) val pp_close_tag : formatter -> unit -> unit -val close_tag : unit -> unit (** [pp_close_tag ppf ()] closes the most recently opened semantic tag [t]. The closing tag marker, as given by [mark_close_tag t], is written into the @@ -593,342 +571,22 @@ val close_tag : unit -> unit *) val pp_set_tags : formatter -> bool -> unit -val set_tags : bool -> unit (** [pp_set_tags ppf b] turns on or off the treatment of semantic tags (default is off). *) val pp_set_print_tags : formatter -> bool -> unit -val set_print_tags : bool -> unit (** [pp_set_print_tags ppf b] turns on or off the tag-printing operations. *) val pp_set_mark_tags : formatter -> bool -> unit -val set_mark_tags : bool -> unit (** [pp_set_mark_tags ppf b] turns on or off the tag-marking operations. *) val pp_get_print_tags : formatter -> unit -> bool -val get_print_tags : unit -> bool (** Return the current status of tag-printing operations. *) val pp_get_mark_tags : formatter -> unit -> bool -val get_mark_tags : unit -> bool (** Return the current status of tag-marking operations. *) -(** {1 Redirecting the standard formatter output} *) -val pp_set_formatter_out_channel : - formatter -> Pervasives.out_channel -> unit -val set_formatter_out_channel : Pervasives.out_channel -> unit -(** Redirect the standard pretty-printer output to the given channel. - (All the output functions of the standard formatter are set to the - default output functions printing to the given channel.) - - [set_formatter_out_channel] is equivalent to - {!pp_set_formatter_out_channel} [std_formatter]. -*) - -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 -(** [pp_set_formatter_output_functions ppf out flush] redirects the - standard pretty-printer output functions to the functions [out] and - [flush]. - - The [out] function performs all the pretty-printer string output. - It is called with a string [s], a start position [p], and a number of - characters [n]; it is supposed to output characters [p] to [p + n - 1] of - [s]. - - The [flush] function is called whenever the pretty-printer is flushed - (via conversion [%!], or pretty-printing indications [@?] or [@.], or - using low level functions [print_flush] or [print_newline]). -*) - -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) -(** Return the current output functions of the standard pretty-printer. *) - -(** {1:meaning Redefining formatter output} *) - -(** The [Format] module is versatile enough to let you completely redefine - the meaning of pretty-printing output: you may provide your own functions - to define how to handle indentation, line splitting, and even printing of - all the characters that have to be printed! -*) - -(** {2 Redefining output functions} *) - -type formatter_out_functions = { - out_string : string -> int -> int -> unit; - out_flush : unit -> unit; - out_newline : unit -> unit; - out_spaces : int -> unit; - out_indent : int -> unit; -} -(** The set of output functions specific to a formatter: - - the [out_string] function performs all the pretty-printer string output. - It is called with a string [s], a start position [p], and a number of - characters [n]; it is supposed to output characters [p] to [p + n - 1] of - [s]. - - the [out_flush] function flushes the pretty-printer output device. - - [out_newline] is called to open a new line when the pretty-printer splits - the line. - - the [out_spaces] function outputs spaces when a break hint leads to spaces - instead of a line split. It is called with the number of spaces to output. - - the [out_indent] function performs new line indentation when the - pretty-printer splits the line. It is called with the indentation value of - the new line. - - By default: - - fields [out_string] and [out_flush] are output device specific; - (e.g. {!Pervasives.output_string} and {!Pervasives.flush} for a - {!Pervasives.out_channel} device, or [Buffer.add_substring] and - {!Pervasives.ignore} for a [Buffer.t] output device), - - field [out_newline] is equivalent to [out_string "\n" 0 1]; - - fields [out_spaces] and [out_indent] are equivalent to - [out_string (String.make n ' ') 0 n]. - @since 4.01.0 -*) - -val pp_set_formatter_out_functions : - formatter -> formatter_out_functions -> unit -val set_formatter_out_functions : formatter_out_functions -> unit -(** [pp_set_formatter_out_functions ppf out_funs] - Set all the pretty-printer output functions of [ppf] to those of - argument [out_funs], - - This way, you can change the meaning of indentation (which can be - something else than just printing space characters) and the meaning of new - lines opening (which can be connected to any other action needed by the - application at hand). - - Reasonable defaults for functions [out_spaces] and [out_newline] are - respectively [out_funs.out_string (String.make n ' ') 0 n] and - [out_funs.out_string "\n" 0 1]. - @since 4.01.0 -*) - -val pp_get_formatter_out_functions : - formatter -> unit -> formatter_out_functions -val get_formatter_out_functions : unit -> formatter_out_functions -(** Return the current output functions of the pretty-printer, - including line splitting and indentation functions. Useful to record the - current setting and restore it afterwards. - @since 4.01.0 -*) - -(** {1:tagsmeaning Redefining semantic tag operations} *) - -type formatter_tag_functions = { - mark_open_tag : tag -> string; - mark_close_tag : tag -> string; - print_open_tag : tag -> unit; - print_close_tag : tag -> unit; -} -(** The semantic tag handling functions specific to a formatter: - [mark] versions are the 'tag-marking' functions that associate a string - marker to a tag in order for the pretty-printing engine to write - those markers as 0 length tokens in the output device of the formatter. - [print] versions are the 'tag-printing' functions that can perform - regular printing when a tag is closed or opened. -*) - -val pp_set_formatter_tag_functions : - formatter -> formatter_tag_functions -> unit -val set_formatter_tag_functions : formatter_tag_functions -> unit -(** [pp_set_formatter_tag_functions ppf tag_funs] changes the meaning of - opening and closing semantic tag operations to use the functions in - [tag_funs] when printing on [ppf]. - - When opening a semantic tag with name [t], the string [t] is passed to the - opening tag-marking function (the [mark_open_tag] field of the - record [tag_funs]), that must return the opening tag marker for - that name. When the next call to [close_tag ()] happens, the semantic tag - name [t] is sent back to the closing tag-marking function (the - [mark_close_tag] field of record [tag_funs]), that must return a - closing tag marker for that name. - - The [print_] field of the record contains the tag-printing functions that - are called at tag opening and tag closing time, to output regular material - in the pretty-printer queue. -*) - -val pp_get_formatter_tag_functions : - formatter -> unit -> formatter_tag_functions -val get_formatter_tag_functions : unit -> formatter_tag_functions -(** Return the current semantic tag operation functions of the standard - pretty-printer. *) - -(** {1:formatter Defining formatters} - - Defining new formatters permits unrelated output of material in - parallel on several output devices. - All the parameters of a formatter are local to the formatter: - right margin, maximum indentation limit, maximum number of pretty-printing - boxes simultaneously open, ellipsis, and so on, are specific to - each formatter and may be fixed independently. - - For instance, given a {!Buffer.t} buffer [b], {!formatter_of_buffer} [b] - returns a new formatter using buffer [b] as its output device. - Similarly, given a {!Pervasives.out_channel} output channel [oc], - {!formatter_of_out_channel} [oc] returns a new formatter using - channel [oc] as its output device. - - Alternatively, given [out_funs], a complete set of output functions for a - formatter, then {!formatter_of_out_functions} [out_funs] computes a new - formatter using those functions for output. -*) - -val formatter_of_out_channel : out_channel -> formatter -(** [formatter_of_out_channel oc] returns a new formatter writing - to the corresponding output channel [oc]. -*) - -val std_formatter : formatter -(** The standard formatter to write to standard output. - - It is defined as {!formatter_of_out_channel} {!Pervasives.stdout}. -*) - -val err_formatter : formatter -(** A formatter to write to standard error. - - It is defined as {!formatter_of_out_channel} {!Pervasives.stderr}. -*) - -val formatter_of_buffer : Buffer.t -> formatter -(** [formatter_of_buffer b] returns a new formatter writing to - buffer [b]. At the end of pretty-printing, the formatter must be flushed - using {!pp_print_flush} or {!pp_print_newline}, to print all the - pending material into the buffer. -*) - -val stdbuf : Buffer.t -(** The string buffer in which [str_formatter] writes. *) - -val str_formatter : formatter -(** A formatter to output to the {!stdbuf} string buffer. - - [str_formatter] is defined as {!formatter_of_buffer} {!stdbuf}. -*) - -val flush_str_formatter : unit -> string -(** Returns the material printed with [str_formatter], flushes - the formatter and resets the corresponding buffer. -*) - -val make_formatter : - (string -> int -> int -> unit) -> (unit -> unit) -> formatter -(** [make_formatter out flush] returns a new formatter that outputs with - function [out], and flushes with function [flush]. - - For instance, {[ - make_formatter - (Pervasives.output oc) - (fun () -> Pervasives.flush oc) ]} - returns a formatter to the {!Pervasives.out_channel} [oc]. -*) - -val formatter_of_out_functions : - formatter_out_functions -> formatter -(** [formatter_of_out_functions out_funs] returns a new formatter that writes - with the set of output functions [out_funs]. - - See definition of type {!formatter_out_functions} for the meaning of argument - [out_funs]. - - @since 4.06.0 -*) - -(** {2:symbolic Symbolic pretty-printing} *) - -(** - Symbolic pretty-printing is pretty-printing using a symbolic formatter, - i.e. a formatter that outputs symbolic pretty-printing items. - - When using a symbolic formatter, all regular pretty-printing activities - occur but output material is symbolic and stored in a buffer of output items. - At the end of pretty-printing, flushing the output buffer allows - post-processing of symbolic output before performing low level output - operations. - - In practice, first define a symbolic output buffer [b] using: - - [let sob = make_symbolic_output_buffer ()]. - Then define a symbolic formatter with: - - [let ppf = formatter_of_symbolic_output_buffer sob] - - Use symbolic formatter [ppf] as usual, and retrieve symbolic items at end - of pretty-printing by flushing symbolic output buffer [sob] with: - - [flush_symbolic_output_buffer sob]. -*) - -type symbolic_output_item = - | Output_flush (** symbolic flush command *) - | Output_newline (** symbolic newline command *) - | Output_string of string - (** [Output_string s]: symbolic output for string [s]*) - | Output_spaces of int - (** [Output_spaces n]: symbolic command to output [n] spaces *) - | Output_indent of int - (** [Output_indent i]: symbolic indentation of size [i] *) -(** Items produced by symbolic pretty-printers - @since 4.06.0 -*) - -type symbolic_output_buffer -(** - The output buffer of a symbolic pretty-printer. - - @since 4.06.0 -*) - -val make_symbolic_output_buffer : unit -> symbolic_output_buffer -(** [make_symbolic_output_buffer ()] returns a fresh buffer for - symbolic output. - - @since 4.06.0 -*) - -val clear_symbolic_output_buffer : symbolic_output_buffer -> unit -(** [clear_symbolic_output_buffer sob] resets buffer [sob]. - - @since 4.06.0 -*) - -val get_symbolic_output_buffer : - symbolic_output_buffer -> symbolic_output_item list -(** [get_symbolic_output_buffer sob] returns the contents of buffer [sob]. - - @since 4.06.0 -*) - -val flush_symbolic_output_buffer : - symbolic_output_buffer -> symbolic_output_item list -(** [flush_symbolic_output_buffer sob] returns the contents of buffer - [sob] and resets buffer [sob]. - [flush_symbolic_output_buffer sob] is equivalent to - [let items = get_symbolic_output_buffer sob in - clear_symbolic_output_buffer sob; items] - - @since 4.06.0 -*) - -val add_symbolic_output_item : - symbolic_output_buffer -> symbolic_output_item -> unit -(** [add_symbolic_output_item sob itm] adds item [itm] to buffer [sob]. - - @since 4.06.0 -*) - -val formatter_of_symbolic_output_buffer : symbolic_output_buffer -> formatter -(** [formatter_of_symbolic_output_buffer sob] returns a symbolic formatter - that outputs to [symbolic_output_buffer] [sob]. - - @since 4.06.0 -*) - (** {1 Convenience formatting functions.} *) val pp_print_list: @@ -1037,12 +695,6 @@ val fprintf : formatter -> ('a, formatter, unit) format -> 'a *) -val printf : ('a, formatter, unit) format -> 'a -(** Same as [fprintf] above, but output on [std_formatter]. *) - -val eprintf : ('a, formatter, unit) format -> 'a -(** Same as [fprintf] above, but output on [err_formatter]. *) - val sprintf : ('a, unit, string) format -> 'a (** Same as [printf] above, but instead of printing on a formatter, returns a string containing the result of formatting the arguments. @@ -1102,51 +754,3 @@ val kasprintf : (string -> 'a) -> ('b, formatter, unit, 'a) format4 -> 'b @since 4.03 *) - -(** {1 Deprecated} *) - -val bprintf : Buffer.t -> ('a, formatter, unit) format -> 'a -[@@ocaml.deprecated] -(** @deprecated This function is error prone. Do not use it. - This function is neither compositional nor incremental, since it flushes - the pretty-printer queue at each call. - - If you need to print to some buffer [b], you must first define a - formatter writing to [b], using [let to_b = formatter_of_buffer b]; then - use regular calls to [Format.fprintf] with formatter [to_b]. -*) - -val kprintf : (string -> 'a) -> ('b, unit, string, 'a) format4 -> 'b -[@@ocaml.deprecated "Use Format.ksprintf instead."] -(** @deprecated An alias for [ksprintf]. *) - -val set_all_formatter_output_functions : - out:(string -> int -> int -> unit) -> - flush:(unit -> unit) -> - newline:(unit -> unit) -> - spaces:(int -> unit) -> - unit -[@@ocaml.deprecated "Use Format.set_formatter_out_functions instead."] -(** @deprecated Subsumed by [set_formatter_out_functions]. *) - -val get_all_formatter_output_functions : - unit -> - (string -> int -> int -> unit) * - (unit -> unit) * - (unit -> unit) * - (int -> unit) -[@@ocaml.deprecated "Use Format.get_formatter_out_functions instead."] -(** @deprecated Subsumed by [get_formatter_out_functions]. *) - -val pp_set_all_formatter_output_functions : - formatter -> out:(string -> int -> int -> unit) -> flush:(unit -> unit) -> - newline:(unit -> unit) -> spaces:(int -> unit) -> unit -[@@ocaml.deprecated "Use Format.pp_set_formatter_out_functions instead."] -(** @deprecated Subsumed by [pp_set_formatter_out_functions]. *) - -val pp_get_all_formatter_output_functions : - formatter -> unit -> - (string -> int -> int -> unit) * (unit -> unit) * (unit -> unit) * - (int -> unit) -[@@ocaml.deprecated "Use Format.pp_get_formatter_out_functions instead."] -(** @deprecated Subsumed by [pp_get_formatter_out_functions]. *)