module BatIO:sig
..end
This module deals with BatIO.input
s and BatIO.output
s. Inputs are manners of getting information from the
outside world and into your program (for instance, reading from
the network, from a file, etc.) Outputs are manners of getting
information out from your program and into the outside world (for
instance, sending something onto the network, onto a file, etc.)
In other words, if you are looking for a way to modify files, read
from the network, etc., you're in the right place.
To perform I/O, you first need to open your BatIO.input
or
your BatIO.output
. Chances are that there is an opening
operation for this task. Note that most opening operations are
defined in their respective module. Operations for opening files
are defined in module File
, operations for opening
communications with the network or with other processes are
defined in module Unix
. Opening operations related to
compression and decompression are defined in module Compress
,
etc.
Once you have opened an BatIO.input
, you may read the data it
contains by using functions such as BatIO.read
(to read one
character), BatIO.nread
or BatIO.input
(to read one string) or one
of the read_*
functions. If you need not one information but a
complete enumeration, for instance for processing many information
before writing them, you may also convert the input into an
enumeration, by using one of the *s_of
functions.
Once you have opened an BatIO.output
, you may write data to
this output by using functions scuh as BatIO.write
(to write one
char), BatIO.nwrite
or BatIO.output
(to write one string) or one of
the write_*
functions. If you have not just one piece of data
but a complete enumeration, you may write this whole enumeration
to the output by using one of the write_*s
functions. Note that
most operations on output are said to be buffered. This means
that small writing operations may be automatically delayed and
grouped into large writing operations, as these are generally
faster and induce less wear on the hardware. Occasionally, you
may wish to force all waiting operations to take place now.
For this purpose, you may either function BatIO.flush
or function
I flush_out
.
Once you have finished using your BatIO.input
or your BatIO.output
, chances are that you will want to close it. This is not a
strict necessity, as OCaml will eventually close it for you when
it detects that you have no more need of that BatIO.input
/BatIO.output
, but this is generally a good policy, as
this will let other programs access the resources which are
currently allocated to that BatIO.input
/BatIO.output
--
typically, under Windows, if you are reading the contents of a
file from a program, no other program may read the contents of
that file simultaneously and you may also not rename or move the
file to another directory. To close an BatIO.input
, use
function BatIO.close_in
and to close an BatIO.output
, use function
BatIO.close_out
.
Note Some BatIO.input
s are built on top of other
BatIO.input
s to provide transparent translations (e.g.
on-the-fly decompression of a file or network information) and
that some BatIO.output
s are built on top of other
BatIO.output
s for the same purpose (e.g. on-the-fly compression
of a file or network information). In this case, closing the
"outer" BatIO.input
/BatIO.output
(e.g. the
decompressor/compressor) will not close the "inner"
BatIO.input
/BatIO.output
(e.g. access to the file or to the
network). You will need to close the "inner"
BatIO.input
/BatIO.output
, which will automatically flush
the outer BatIO.input
/BatIO.output
and close it.
Author(s): Nicolas Cannasse, David Teller, Philippe Strauss, Edgar Friendly
typeinput =
BatInnerIO.input
type'a
output ='a BatInnerIO.output
'a
is the accumulator data, it is returned
when the close_out
function is called.type('a, 'b)
printer ='b output -> 'a -> unit
'a
to an output that
produces 'b
as result.type'a
f_printer =Format.formatter -> 'a -> unit
exception No_more_input
read
or
nread
functions while there is no available token to read.exception Input_closed
exception Output_closed
val stdin : input
Example: if read_line stdin |> Int.of_string > 10 then failwith "too big a number read";
val stdout : unit output
Use this output to display regular messages.
Example:
write_string stdout "Enter your name:";
let name = read_line stdin in
write_line stdout ("Your name is " ^ name);
val stderr : unit output
Use this output to display warnings and error messages.
Example:
write_line stderr "Error on Internet - please delete google.com";
val stdnull : unit output
Use this output to ignore messages.
Example:
let out_ch = if debug then stderr else stdnull in
write_line out_ch "Program running.";
val read : input -> char
No_more_input
if
no input is available.
Example: let rec skip_line ch = if read ch = '\n' then skip_line ch else ();
val nread : input -> int -> string
nread i n
reads a string of size up to n
from an input.
The function will raise No_more_input
if no input is available.
It will raise Invalid_argument
if n
< 0.
Example: let read_md5 ch = nread ch 32
val really_nread : input -> int -> string
really_nread i n
reads a string of exactly n
characters
from the input.No_more_input
if at least n
characters are
not available.Invalid_argument
if n
< 0.
Example: let read_md5 ch = really_nread ch 32
val input : input -> string -> int -> int -> int
input i s p l
reads up to l
characters from the given input,
storing them in string s
, starting at character number p
. It
returns the actual number of characters read (which may be 0) or
raise No_more_input
if no character can be read. It will raise
Invalid_argument
if p
and l
do not designate a valid
substring of s
.
Example: let map_ch f ?(block_size=100) =
let b = String.create block_size in
try while true do
let l = input ch b 0 block_size in
f b 0 l;
done with No_more_input -> ()
val really_input : input -> string -> int -> int -> int
really_input i s p l
reads exactly l
characters from the
given input, storing them in the string s
, starting at
position p
. For consistency with BatIO.input
it returns
l
.No_more_input
if at l
characters are not
available.Invalid_argument
if p
and l
do not
designate a valid substring of s
.
Example: let _ = really_input stdin b 0 3
val close_in : input -> unit
Example: close_in network_in;
val write : (char, 'a) printer
Example: write stdout 'x';
val nwrite : (string, 'a) printer
Example: nwrite stdout "Enter your name: ";
val output : 'a output -> string -> int -> int -> int
output o s p l
writes up to l
characters from string s
, starting at
offset p
. It returns the number of characters written. It will raise
Invalid_argument
if p
and l
do not designate a valid substring of s
.
Example: let str = "Foo Bar Baz" in let written = output stdout str 2 4;
This writes "o Ba" to stdout.
val really_output : 'a output -> string -> int -> int -> int
really_output o s p l
writes exactly l
characters from string s
onto
the the output, starting with the character at offset p
. For consistency with
BatIO.output
it returns l
.Invalid_argument
if p
and l
do not
designate a valid substring of s
.
This function is useful for networking situations where the output
buffer might fill resulting in not the entire substring being
readied for transmission. Uses output
internally, and will
raise Sys_blocked_io
in the case that any call returns 0.
val flush : 'a output -> unit
If previous write operations have caused errors, this may trigger an exception.
Example: flush stdout;
val flush_all : unit -> unit
Example: flush_all ();
val close_out : 'a output -> 'a
The output is flushed before being closed and can no longer be written. Attempting to flush or write after the output has been closed will have no effect.
Example:
let strout = output_string () in
write strout 'x';
if 2+3>5 then write strout "y";
print_string (close_out strout)
val comb : 'a output * 'a output -> 'a output
combine
val make_enum : (input -> 'a) -> input -> 'a BatEnum.t
val get_output_id : 'a output -> int
val get_input_id : input -> int
module Incubator:sig
..end