anil.recoil.org
My working unpac repository
1(**************************************************************************)
2(* *)
3(* OCaml *)
4(* *)
5(* Xavier Leroy and Pierre Weis, projet Cristal, INRIA Rocquencourt *)
6(* *)
7(* Copyright 1996 Institut National de Recherche en Informatique et *)
8(* en Automatique. *)
9(* *)
10(* All rights reserved. This file is distributed under the terms of *)
11(* the GNU Lesser General Public License version 2.1, with the *)
12(* special exception on linking described in the file LICENSE. *)
13(* *)
14(**************************************************************************)
15
16(** Formatted output functions. *)
17
18val fprintf : out_channel -> ('a, out_channel, unit) format -> 'a
19(** [fprintf outchan format arg1 ... argN] formats the arguments
20 [arg1] to [argN] according to the format string [format], and
21 outputs the resulting string on the channel [outchan].
22
23 The format string is a character string which contains two types of
24 objects: plain characters, which are simply copied to the output
25 channel, and conversion specifications, each of which causes
26 conversion and printing of arguments.
27
28 Conversion specifications have the following form:
29
30 [% [flags] [width] [.precision] type]
31
32 In short, a conversion specification consists in the [%] character,
33 followed by optional modifiers and a type which is made of one or
34 two characters.
35
36 The types and their meanings are:
37
38 - [d], [i]: convert an integer argument to signed decimal.
39 The flag [#] adds underscores to large values for readability.
40 - [u], [n], [l], [L], or [N]: convert an integer argument to
41 unsigned decimal. Warning: [n], [l], [L], and [N] are
42 used for [scanf], and should not be used for [printf].
43 The flag [#] adds underscores to large values for readability.
44 - [x]: convert an integer argument to unsigned hexadecimal,
45 using lowercase letters.
46 The flag [#] adds a [0x] prefix to non zero values.
47 - [X]: convert an integer argument to unsigned hexadecimal,
48 using uppercase letters.
49 The flag [#] adds a [0X] prefix to non zero values.
50 - [o]: convert an integer argument to unsigned octal.
51 The flag [#] adds a [0] prefix to non zero values.
52 - [s]: insert a string argument.
53 - [S]: convert a string argument to OCaml syntax (double quotes, escapes).
54 - [c]: insert a character argument.
55 - [C]: convert a character argument to OCaml syntax
56 (single quotes, escapes).
57 - [f]: convert a floating-point argument to decimal notation,
58 in the style [dddd.ddd].
59 - [F]: convert a floating-point argument to OCaml syntax ([dddd.]
60 or [dddd.ddd] or [d.ddd e+-dd]).
61 Converts to hexadecimal with the [#] flag (see [h]).
62 - [e] or [E]: convert a floating-point argument to decimal notation,
63 in the style [d.ddd e+-dd] (mantissa and exponent).
64 - [g] or [G]: convert a floating-point argument to decimal notation,
65 in style [f] or [e], [E] (whichever is more compact). Moreover,
66 any trailing zeros are removed from the fractional part of the result
67 and the decimal-point character is removed if there is no fractional
68 part remaining.
69 - [h] or [H]: convert a floating-point argument to hexadecimal notation,
70 in the style [0xh.hhhh p+-dd] (hexadecimal mantissa, exponent in
71 decimal and denotes a power of 2).
72 - [B]: convert a boolean argument to the string [true] or [false]
73 - [b]: convert a boolean argument (deprecated; do not use in new
74 programs).
75 - [ld], [li], [lu], [lx], [lX], [lo]: convert an [int32] argument to
76 the format specified by the second letter (decimal, hexadecimal, etc).
77 - [nd], [ni], [nu], [nx], [nX], [no]: convert a [nativeint] argument to
78 the format specified by the second letter.
79 - [Ld], [Li], [Lu], [Lx], [LX], [Lo]: convert an [int64] argument to
80 the format specified by the second letter.
81 - [a]: user-defined printer. Take two arguments and apply the
82 first one to [outchan] (the current output channel) and to the
83 second argument. The first argument must therefore have type
84 [out_channel -> 'b -> unit] and the second ['b].
85 The output produced by the function is inserted in the output of
86 [fprintf] at the current point.
87 - [t]: same as [%a], but take only one argument (with type
88 [out_channel -> unit]) and apply it to [outchan].
89 - [\{ fmt %\}]: convert a format string argument to its type digest.
90 The argument must have the same type as the internal format string
91 [fmt].
92 - [( fmt %)]: format string substitution. Take a format string
93 argument and substitute it to the internal format string [fmt]
94 to print following arguments. The argument must have the same
95 type as the internal format string [fmt].
96 - [!]: take no argument and flush the output.
97 - [%]: take no argument and output one [%] character.
98 - [\@]: take no argument and output one [\@] character.
99 - [,]: take no argument and output nothing: a no-op delimiter for
100 conversion specifications.
101
102 The optional [flags] are:
103 - [-]: left-justify the output (default is right justification).
104 - [0]: for numerical conversions, pad with zeroes instead of spaces.
105 - [+]: for signed numerical conversions, prefix number with a [+]
106 sign if positive.
107 - space: for signed numerical conversions, prefix number with a
108 space if positive.
109 - [#]: request an alternate formatting style for the integer types
110 and the floating-point type [F].
111
112 The optional [width] is an integer indicating the minimal
113 width of the result. For instance, [%6d] prints an integer,
114 prefixing it with spaces to fill at least 6 characters.
115
116 The optional [precision] is a dot [.] followed by an integer
117 indicating how many digits follow the decimal point in the [%f],
118 [%e], [%E], [%h], and [%H] conversions or the maximum number of
119 significant digits to appear for the [%F], [%g] and [%G] conversions.
120 For instance, [%.4f] prints a [float] with 4 fractional digits.
121
122 The integer in a [width] or [precision] can also be specified as
123 [*], in which case an extra integer argument is taken to specify
124 the corresponding [width] or [precision]. This integer argument
125 precedes immediately the argument to print.
126 For instance, [%.*f] prints a [float] with as many fractional
127 digits as the value of the argument given before the float. *)
128
129val printf : ('a, out_channel, unit) format -> 'a
130(** Same as {!Printf.fprintf}, but output on [stdout]. *)
131
132val eprintf : ('a, out_channel, unit) format -> 'a
133(** Same as {!Printf.fprintf}, but output on [stderr]. *)
134
135val sprintf : ('a, unit, string) format -> 'a
136(** Same as {!Printf.fprintf}, but instead of printing on an output channel,
137 return a string containing the result of formatting the arguments. *)
138
139val bprintf : Buffer.t -> ('a, Buffer.t, unit) format -> 'a
140(** Same as {!Printf.fprintf}, but instead of printing on an output channel,
141 append the formatted arguments to the given extensible buffer
142 (see module {!Buffer}). *)
143
144val ifprintf : 'b -> ('a, 'b, 'c, unit) format4 -> 'a
145(** Same as {!Printf.fprintf}, but does not print anything.
146 Useful to ignore some material when conditionally printing.
147 @since 3.10
148*)
149
150val ibprintf : Buffer.t -> ('a, Buffer.t, unit) format -> 'a
151(** Same as {!Printf.bprintf}, but does not print anything.
152 Useful to ignore some material when conditionally printing.
153 @since 4.11
154*)
155
156(** Formatted output functions with continuations. *)
157
158val kfprintf : (out_channel -> 'd) -> out_channel ->
159 ('a, out_channel, unit, 'd) format4 -> 'a
160(** Same as [fprintf], but instead of returning immediately,
161 passes the out channel to its first argument at the end of printing.
162 @since 3.09
163*)
164
165val ikfprintf : ('b -> 'd) -> 'b -> ('a, 'b, 'c, 'd) format4 -> 'a
166(** Same as [kfprintf] above, but does not print anything.
167 Useful to ignore some material when conditionally printing.
168 @since 4.01
169*)
170
171val ksprintf : (string -> 'd) -> ('a, unit, string, 'd) format4 -> 'a
172(** Same as [sprintf] above, but instead of returning the string,
173 passes it to the first argument.
174 @since 3.09
175*)
176
177val kbprintf : (Buffer.t -> 'd) -> Buffer.t ->
178 ('a, Buffer.t, unit, 'd) format4 -> 'a
179(** Same as [bprintf], but instead of returning immediately,
180 passes the buffer to its first argument at the end of printing.
181 @since 3.10
182*)
183
184val ikbprintf : (Buffer.t -> 'd) -> Buffer.t ->
185 ('a, Buffer.t, unit, 'd) format4 -> 'a
186(** Same as [kbprintf] above, but does not print anything.
187 Useful to ignore some material when conditionally printing.
188 @since 4.11
189*)
190
191(** Formatted output functions with heterogeneous argument lists.
192
193 The following functions behave the same as their non-'l' counter-parts, but
194 receive their arguments bundled in a single heterogeneous list.
195
196 The heterogeneous list serves as a syntactically-delimited
197 collection of arguments, eliminating the need for continuation variants.
198 This approach also improves the clarity of type error messages,
199 especially when there is a mismatch between the format string and the
200 number of arguments provided.
201
202 For example:
203 {[
204 Printf.lprintf "%s %d %.02f %c\n" [ "ocaml"; 42; 3.14; 'c' ]
205 ]}
206*)
207
208module Args : sig
209 type ('a, 'r) t =
210 | [] : ('r, 'r) t
211 | (::) : 'a * ('b, 'r) t -> ('a -> 'b, 'r) t
212
213 val apply : 'a -> ('a, 'r) t -> 'r
214
215 val ( @ ) : ('a, 'r1) t -> ('r1, 'r2) t -> ('a, 'r2) t
216end
217(** The [Args] module defines a heterogeneous list type, which can be
218 used as the argument of the [l*printf] functions.
219 For more documentation, see the similar module {!Format.Args}. *)
220
221val lfprintf : out_channel ->
222 ('a, out_channel, unit) format ->
223 ('a, unit) Args.t ->
224 unit
225(** Same as [fprintf] above, but with the arguments bundled in a single
226 heterogeneous list.
227 For example:
228 {[
229 Printf.lfprintf (open_out "some/file.txt") "@[%s@ %d@]@." [ "x ="; 1 ]
230 ]}
231 @since 5.5
232*)
233
234val lbprintf : Buffer.t ->
235 ('a, Buffer.t, unit) format ->
236 ('a, unit) Args.t ->
237 unit
238(** Same as [bprintf] above, but with the arguments bundled in a single
239 heterogeneous list.
240 @since 5.5
241*)
242
243val lprintf : ('a, out_channel, unit) format ->
244 ('a, unit) Args.t ->
245 unit
246(** Same as [printf] above, but with the arguments bundled in a single
247 heterogeneous list.
248 @since 5.5
249*)
250
251val leprintf : ('a, out_channel, unit) format ->
252 ('a, unit) Args.t ->
253 unit
254(** Same as [eprintf] above, but with the arguments bundled in a single
255 heterogeneous list.
256 @since 5.5
257*)
258
259val lsprintf : ('a, unit, string) format ->
260 ('a, string) Args.t ->
261 string
262(** Same as [sprintf] above, but with the arguments bundled in a single
263 heterogeneous list.
264 @since 5.5
265*)
266
267(** Deprecated *)
268
269val kprintf : (string -> 'b) -> ('a, unit, string, 'b) format4 -> 'a
270[@@ocaml.deprecated "Use Printf.ksprintf instead."]
271(** A deprecated synonym for [ksprintf]. *)