Module BatPrintf

module BatPrintf: sig .. end
Formatted output functions (also known as unparsing).
Author(s): Xavier Leroy, Pierre Weiss, David Teller


Formatted output functions (also known as unparsing).

General overview

The functions of this module produce output according to a Pervasives.format, as described below. Some functions write to the standard output (i.e. the screen), some to error channels, some to strings or to buffers, or some to abstract outputs.

Note The types used in this module are confusing at first. If you are a beginner, you should probably ignore them in a first time and concentrate on formats.

For a first explanation, we will concentrate on function BatPrintf.printf. As all the functions in this module, the behavior of BatPrintf.printf is dictated by a format. This format is a string, composed of regular text and directives, and which dictates how to interpret the other arguments passed to the function. Every directive starts with character %. The most common directive is %s, which serves to display a string, something quite useful for pretty-printing or translation. Anther common directive is %i, which serves to display an integer.

For instance, "foobar" is a format with no directive. Calling printf "foobar" prints "foobar" on the screen and returns (). On the other hand, "%s" is a format with one directive for printing strings. printf "%s" does nothing yet but returns a function with type string -> unit. In turn, printf "%s"
   "foobar"
prints "foobar" on the screen and returns (). The main interest of this module is that directives may be combined together and with text, to allow more complex printing. For instance printf "(%s)\n" is a function with type string -> unit which, when passed string "foobar" prints "(foobar)" and ends the line. Similarly, printf "Here's the result: %s.\n\tComputation
   took %i seconds.\n"
 "foobar" 5
prints

Here's the result: foobar
         Computation took 5 seconds.

Note that \n (the newline character) and \t (the tabulation) are not specific to this module but rather part of the conventions on characters strings in OCaml.

Other directives and functions make this module extremely useful for printing, pretty-printing and translation of messages to the user's language. For more information, see the documentation of format and the various functions.

Formats

type ('a, 'b, 'c) t = ('a, 'b, 'c) Pervasives.format 
The format to use for displaying the various arguments passed to the function.

Syntactically, the format is a character string which contains two types of objects: plain characters, which are simply copied, and directives, each of which causes the conversion and printing of arguments.

Simple directives

All directives start with the % character. In their simplest form, a directive is % followed by exactly one character:

Unparsers

Formatting formats
Additional options
The general format of directives is

% [flags] [width] [.precision] type

type is one of d, i, n, l, L, N, u, x ..., ( fmt %) and behaves as explained above.

The optional flags are:

The optional width is an integer indicating the minimal width of the result. For instance, %6d prints an integer, prefixing it with spaces to fill at least 6 characters.

The optional precision is a dot . followed by an integer indicating how many digits follow the decimal point in the %f, %e, and %E conversions. For instance, %.4f prints a float with 4 fractional digits.

The integer in a width or precision can also be specified as *, in which case an extra integer argument is taken to specify the corresponding width or precision. This integer argument precedes immediately the argument to print. For instance, %.*f prints a float with as many fractional digits as the value of the argument given before the float.


Common functions

val printf : ('b, 'a BatInnerIO.output, unit) t -> 'b
The usual printf function, prints to the standard output stdout, i.e. normally to the screen. If you are lost, this is probably the function you're looking for.
val eprintf : ('b, 'a BatInnerIO.output, unit) t -> 'b
The usual eprintf function, prints to the standard error output stderr, used to display warnings and errors. Otherwise identical to BatPrintf.printf.
val sprintf : ('a, unit, string) t -> 'a
A function which doesn't print its result but returns it as a string. Useful for building messages, for translation purposes or for display in a window, for instance.

While this function is quite convenient, don't abuse it to create very large strings such as files, that's not its role. For this kind of usage, prefer the more modular and usually faster BatPrintf.fprintf.

Note that any function called with %a should return strings, i.e. should have type unit -> string.

val sprintf2 : ('a, 'b BatInnerIO.output, unit, string) Pervasives.format4 -> 'a
A function which doesn't print its result but returns it as a string. Useful for building messages, for translation purposes or for display in a window, for instance.

While this function is quite convenient, don't abuse it to create very large strings such as files, that's not its role. For this kind of usage, prefer the more modular and usually faster BatPrintf.fprintf. Note that any function called with %a should be able to print its result, i.e. should have type 'b output -> unit.

Warning: a partial application of this function can only be used once, because the BatInnerIO.output that it uses is closed afterwards. Example: let f = sprintf2 "%a" Int.print in [f 1; f 2] will fail.


General functions

val fprintf : 'a BatInnerIO.output -> ('b, 'a BatInnerIO.output, unit) t -> 'b
General function. This function prints to any output. Typically, if you are attempting to build a large output such as a file, this is probably the function you are looking for. If you are writing a pretty-printer, this is probably the function you are looking for. If you are you are looking for a function to use for argument %a with BatPrintf.printf, BatPrintf.eprintf, BatPrintf.sprintf2, BatPrintf.ifprintf, BatPrintf.bprintf2, BatPrintf.kfprintf, BatPrintf.ksprintf2, BatPrintf.kbprintf2 or any other function with type (_, _ output, unit) format or (_, _ output, unit, _) format4, this is also probably the function you are looking for.
val ifprintf : 'c -> ('b, 'a BatInnerIO.output, unit) t -> 'b
As BatPrintf.fprintf but doesn't actually print anything. Sometimes useful for debugging.
val bprintf : Buffer.t -> ('a, Buffer.t, unit) t -> 'a
As BatPrintf.fprintf, but with buffers instead of outputs. In particular, any unparser called with %a should write to a buffer rather than to an output
val bprintf2 : Buffer.t -> ('b, 'a BatInnerIO.output, unit) t -> 'b
As BatPrintf.printf but writes to a buffer instead of printing to the output. By opposition to BatPrintf.bprintf, only the result is changed with respect to BatPrintf.printf, not the inner workings.

Functions with continuations

val kfprintf : ('a BatInnerIO.output -> 'b) ->
'a BatInnerIO.output ->
('c, 'a BatInnerIO.output, unit, 'b) Pervasives.format4 -> 'c
Same as fprintf, but instead of returning immediately, passes the output to its first argument at the end of printing.
val ksprintf : (string -> 'a) -> ('b, unit, string, 'a) Pervasives.format4 -> 'b
Same as sprintf above, but instead of returning the string, passes it to the first argument.
val ksprintf2 : (string -> 'b) ->
('c, 'a BatInnerIO.output, unit, 'b) Pervasives.format4 -> 'c
Same as sprintf2 above, but instead of returning the string, passes it to the first argument.
val kbprintf : (Buffer.t -> 'a) ->
Buffer.t -> ('b, Buffer.t, unit, 'a) Pervasives.format4 -> 'b
Same as bprintf, but instead of returning immediately, passes the buffer to its first argument at the end of printing.
val kbprintf2 : (Buffer.t -> 'b) ->
Buffer.t -> ('c, 'a BatInnerIO.output, unit, 'b) Pervasives.format4 -> 'c
Same as bprintf2, but instead of returning immediately, passes the buffer to its first argument at the end of printing.
val kprintf : (string -> 'a) -> ('b, unit, string, 'a) Pervasives.format4 -> 'b
Deprecated.This is a deprecated synonym for ksprintf.

About formats

You only need to read this if you intend to create your new printf-like functions, which happens generally by toying with mkprintf.

Format4

('a, 'b, 'c, 'd) format4 is the type of arguments for printf-style functions such that

Format
('a, 'b, 'c) format or ('a, 'b, 'c) t is just a shortcut for ('a, 'b, 'c, 'c) format4.

Important
Note that Obj.magic is involved behind this, so be careful.