module BatScanf:sig
..end
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:
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.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
,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
"%d" f
, and then enter 41
at the keyboard, we get 42
as the final
result.module Scanning:sig
..end
type('a, 'b, 'c, 'd)
scanner =('a, Scanning.scanbuf, 'b, 'c, 'a -> 'd, 'd) format6 -> 'c
('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)
scanner
, since it is a formatted input function that reads from stdib
:
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
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.
f
,
Matching any amount of whitespace, a space in the format string
also matches no amount of whitespace at all; hence, the call bscanf ib
"Price = %d $" (fun p -> p)
succeds and returns 1
when reading an
input with various whitespace in it, such as Price = 1 $
,
Price = 1 $
, or even Price=1$
.
%
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
.%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).
-
val fscanf : Pervasives.in_channel -> ('a, 'b, 'c, 'd) scanner
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
Scanf.bscanf
, but reads from the given string.val scanf : ('a, 'b, 'c, 'd) scanner
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
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) format6 ->
(('a, 'b, 'c, 'd, 'e, 'f) format6 -> 'g) -> 'g
bscanf_format ib fmt f
reads a format string token from the scannning
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) format6 ->
(('a, 'b, 'c, 'd, 'e, 'f) format6 -> 'g) -> 'g
Scanf.bscanf_format
, but reads from the given string.val format_from_string : string ->
('a, 'b, 'c, 'd, 'e, 'f) format6 -> ('a, 'b, 'c, 'd, 'e, 'f) 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
.