module Scanf: BatScanf
The module Scanf
provides formatted input functions or scanners.
The formatted input functions can read from any kind of input, including
strings, files, or anything that can return characters. The more general
source of characters is named a scanning buffer and has type
BatScanf.Scanning.scanbuf
. The more general formatted input function reads from
any scanning buffer and is named bscanf
.
Generally speaking, the formatted input functions have 3 arguments:
Hence, a typical call to the formatted input function Scanf.bscanf
is
bscanf ib fmt f
, where:
ib
is a source of characters (typically a scanning buffer with type BatScanf.Scanning.scanbuf
),fmt
is a format string (the same format strings as those used to print
material with module Printf
or Format
),f
is a function that has as many arguments as the number of values to
read in the input.As suggested above, the expression bscanf ib "%d" f
reads a decimal
integer n
from the source of characters ib
and returns f n
.
For instance,
stdib
as the source of characters (BatScanf.Scanning.stdib
is
the predefined input buffer that reads from standard input),f
as let f x = x + 1
,then bscanf stdib "%d" f
reads an integer n
from the standard input
and returns f n
(that is n + 1
). Thus, if we evaluate bscanf stdib
, and then enter
"%d" f41
at the keyboard, we get 42
as the final
result.
The OCaml scanning facility is reminiscent of the corresponding C feature. However, it is also largely different, simpler, and yet more powerful: the formatted input functions are higher-order functionals and the parameter passing mechanism is just the regular function application not the variable assignment based mechanism which is typical for formatted input in imperative languages; the OCaml format strings also feature useful additions to easily define complex tokens; as expected within a functional programming language, the formatted input functions also support polymorphism, in particular arbitrary interaction with polymorphic user-defined scanners. Furthermore, the OCaml formatted input facility is fully type-checked at compile time.
module Scanning:sig
..end
Scanning buffers
type('a, 'b, 'c, 'd)
scanner =('a, Scanning.scanbuf, 'b, 'c, 'a -> 'd, 'd) Stdlib.format6 -> 'c
The type of formatted input scanners: ('a, 'b, 'c, 'd) scanner
is the
type of a formatted input function that reads from some scanning buffer
according to some format string; more precisely, if scan
is some
formatted input function, then scan ib fmt f
applies f
to the arguments
specified by the format string fmt
, when scan
has read those arguments
from the scanning input buffer ib
.
For instance, the scanf
function below has type ('a, 'b, 'c, 'd)
, since it is a formatted input function that reads from
scannerstdib
:
scanf fmt f
applies f
to the arguments specified by fmt
, reading
those arguments from stdin
as expected.
If the format fmt
has some %r
indications, the corresponding input
functions must be provided before the receiver f
argument. For
instance, if read_elem
is an input function for values of type t
,
then bscanf ib "%r;" read_elem f
reads a value v
of type t
followed
by a ';'
character, and returns f v
.
exception Scan_failure of string
The exception that formatted input functions raise when the input cannot be read according to the given format.
val bscanf : Scanning.scanbuf -> ('a, 'b, 'c, 'd) scanner
bscanf ib fmt r1 ... rN f
reads arguments for the function f
, from the
scanning buffer ib
, according to the format string fmt
, and applies f
to these values.
The result of this call to f
is returned as the result of the entire
bscanf
call.
For instance, if f
is the function fun s i -> i + 1
, then
Scanf.sscanf "x= 1" "%s = %i" f
returns 2
.
Arguments r1
to rN
are user-defined input functions that read the
argument corresponding to a %r
conversion.
The format is a character string which contains three types of objects:
f
,As mentioned above, a plain character in the format string is just matched with the characters of the input; however, one character is a special exception to this simple rule: the space character (ASCII code 32) does not match a single space character, but any amount of ``whitespace'' in the input. More precisely, a space inside the format string matches any number of tab, space, line feed and carriage return characters.
Matching any amount of whitespace, a space in the format string
also matches no amount of whitespace at all; hence, the call bscanf ib
succeeds and returns
"Price = %d $" (fun p -> p)1
when reading an
input with various whitespace in it, such as Price = 1 $
,
Price = 1 $
, or even Price=1$
.
Conversion specifications consist in the %
character, followed by
an optional flag, an optional field width, and followed by one or
two conversion characters. The conversion characters and their
meanings are:
d
: reads an optionally signed decimal integer.i
: reads an optionally signed integer
(usual input formats for hexadecimal (0x[d]+
and 0X[d]+
),
octal (0o[d]+
), and binary 0b[d]+
notations are understood).u
: reads an unsigned decimal integer.x
or X
: reads an unsigned hexadecimal integer.o
: reads an unsigned octal integer.s
: reads a string argument that spreads as much as possible, until the
following bounding condition holds: a whitespace has been found, a
scanning indication has been encountered, or the end-of-input has been
reached.
Hence, this conversion always succeeds: it returns an empty
string, if the bounding condition holds when the scan begins.S
: reads a delimited string argument (delimiters and special
escaped characters follow the lexical conventions of OCaml).c
: reads a single character. To test the current input character
without reading it, specify a null field width, i.e. use
specification %0c
.Scanning indications appear just after the string conversions %s
and %[ range ]
to delimit the end of the token. A scanning
indication is introduced by a @
character, followed by some
constant character c
. It means that the string token should end
just before the next matching c
(which is skipped). If no c
character is encountered, the string token spreads as much as
possible. For instance, "%s@\t"
reads a string up to the next
tab character or to the end of input. If a scanning
indication @c
does not follow a string conversion, it is treated
as a plain c
character.
Note:
Scanf
format strings, compared to those used for the Printf
module. However, the scanning indications are similar to those used in
the Format
module; hence, when producing formatted text to be scanned
by !Scanf.bscanf
, it is wise to use printing functions from the
Format
module (or, if you need to use functions from Printf
, banish
or carefully double check the format strings that contain '@'
characters).Scanners may raise the following exceptions when the input cannot be read according to the format string:
-
val fscanf : Stdlib.in_channel -> ('a, 'b, 'c, 'd) scanner
Same as Scanf.bscanf
, but reads from the given channel.
Warning: since all formatted input functions operate from a scanning
buffer, be aware that each fscanf
invocation will operate with a
scanning buffer reading from the given channel. This extra level of
bufferization can lead to strange scanning behaviour if you use low level
primitives on the channel (reading characters, seeking the reading
position, and so on).
As a consequence, never mixt direct low level reading and high level scanning from the same input channel.
val sscanf : string -> ('a, 'b, 'c, 'd) scanner
Same as Scanf.bscanf
, but reads from the given string.
val scanf : ('a, 'b, 'c, 'd) scanner
Same as Scanf.bscanf
, but reads from the predefined scanning
buffer Scanf.Scanning.stdib
that is connected to stdin
.
val kscanf : Scanning.scanbuf ->
(Scanning.scanbuf -> exn -> 'd) -> ('a, 'b, 'c, 'd) scanner
Same as Scanf.bscanf
, but takes an additional function argument
ef
that is called in case of error: if the scanning process or
some conversion fails, the scanning function aborts and calls the
error handling function ef
with the scanning buffer and the
exception that aborted the scanning process.
val bscanf_format : Scanning.scanbuf ->
('a, 'b, 'c, 'd, 'e, 'f) Stdlib.format6 ->
(('a, 'b, 'c, 'd, 'e, 'f) Stdlib.format6 -> 'g) -> 'g
bscanf_format ib fmt f
reads a format string token from the scanning
buffer ib
, according to the given format string fmt
, and applies f
to
the resulting format string value.
Scan_failure
if the format string value read does not have the
same type as fmt
.val sscanf_format : string ->
('a, 'b, 'c, 'd, 'e, 'f) Stdlib.format6 ->
(('a, 'b, 'c, 'd, 'e, 'f) Stdlib.format6 -> 'g) -> 'g
Same as Scanf.bscanf_format
, but reads from the given string.
val format_from_string : string ->
('a, 'b, 'c, 'd, 'e, 'f) Stdlib.format6 ->
('a, 'b, 'c, 'd, 'e, 'f) Stdlib.format6
format_from_string s fmt
converts a string argument to a format string,
according to the given format string fmt
.
Scan_failure
if s
, considered as a format string, does not
have the same type as fmt
.