High-order abstract I/O.
This module deals with inputs and
outputs. 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 input or your 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 input, you may read the data it contains by using functions such as read (to read one character), nread or 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 output, you may write data to this output by using functions scuh as write (to write one char), nwrite or 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 call function flush.
Once you have finished using your input or your
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
input/output, but this is generally a good policy, as this will let other programs access the resources which are currently allocated to that input/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 input, use function close_in and to close an output, use function close_out.
Note Some inputs are built on top of other inputs to provide transparent translations (e.g. on-the-fly decompression of a file or network information) and that some outputs are built on top of other outputs for the same purpose (e.g. on-the-fly compression of a file or network information). In this case, closing the "outer" input/output (e.g. the decompressor/compressor) will not close the "inner" input/output (e.g. access to the file or to the network). You will need to close the "inner" input/output, which will automatically flush the outer input/output and close it.
@documents BatInnerIO
The abstract output type, 'a is the accumulator data, it is returned when the close_out function is called.
type ('a, 'b) printer = 'b output -> 'a -> unitThe type of a printing function to print a 'a to an output that produces 'b as result.
This exception is raised when reading on an input with the read or nread functions while there is no available token to read.
This exception is raised when reading on a closed input.
This exception is raised when reading on a closed output.
Standard input, as per Unix/Windows conventions (by default, keyboard).
Example: if read_line stdin |> Int.of_string > 10 then failwith "too big a number read";
Standard output, as per Unix/Windows conventions (by default, console).
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);
Standard error output, as per Unix/Windows conventions.
Use this output to display warnings and error messages.
Example:
write_line stderr "Error on Internet - please delete google.com";
An output which discards everything written to it.
Use this output to ignore messages.
Example:
let out_ch = if debug then stderr else stdnull in
write_line out_ch "Program running.";
Standard API
Read a single char from an input or raise 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 -> stringnread 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 -> stringreally_nread i n reads a string of exactly n characters from the input.
input i s p len reads up to len characters from the given input, storing them in byte sequence 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 len do not designate a valid subsequence 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 -> ()
really_input ic s p len reads exactly len characters from the input ic, storing them in the string s, starting at position p. For consistency with BatIO.input it returns len.
val close_in : input -> unitClose the input. It can no longer be read from.
Example: close_in network_in;
Write a single char to an output.
Example: write stdout 'x';
Write a string to an output.
Example: nwrite stdout "Enter your name: ";
output o s p len writes up to len characters from byte sequence s, starting at offset p. It returns the number of characters written. It will raise Invalid_argument if p and len do not designate a valid subsequence of s.
Example: let written = output stdout (Bytes.to_string "Foo Bar Baz") 2 4
This writes "o Ba" to stdout, and returns 4.
val output_substring : 'a output -> string -> int -> int -> intlike output above, but outputs from a substring instead of a subsequence of bytes
really_output o s p len writes exactly len characters from byte sequence s onto the the output, starting with the character at offset p. For consistency with BatIO.output it returns len.
val really_output_substring : 'a output -> string -> int -> int -> intlike really_output above, but outputs from a substring instead of a subsequence of bytes
Flush an output.
If previous write operations have caused errors, this may trigger an exception.
Example: flush stdout;
val flush_all : unit -> unitFlush all outputs, ignore errors.
Example: flush_all ();
val close_out : 'a output -> 'aClose the output and return its accumulator data.
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)
To open a file for reading/writing, see File.open_in and File.open_out
Create an input that will read from a string.
Example:
let inch = input_string "1234554321" in
let str1 = nread inch 3 in (* "123" *)
let str2 = nread inch 5 in (* "45543" *)
let str3 = nread inch 2 in (* "21" *)
try string_of_char(read inch) with BatIO.No_more_input -> "End of string";
val output_string : unit -> string outputCreate an output that will write into a string in an efficient way. When closed, the output returns all the data written into it.
Create an input that will read from an enum.
Create an output that will write into an enum. The final enum is returned when the output is closed.
combine (a,b) creates a new output c such that writing to c will actually write to both a and b
Create an output shifted to the right by a number of spaces (or other character as specified by tab).
tab_out n out produces a new output for writing into out, in which every new line starts with n spaces.
Utilities
val read_all : input -> stringread all the contents of the input until No_more_input is raised.
Create a pipe between an input and an output. Data written from the output can be read from the input.
Read everything from an input and copy it to an output.
Create an input that provide a count function of the number of bytes read from it.
val progress_in : input -> (unit -> unit) -> inputprogress_in inp f create an input that calls f () whenever some content is successfully read from it.
Create an output that provide a count function of the number of bytes written through it.
val progress_out : 'a output -> (unit -> unit) -> unit outputprogress_out out f create an output that calls f () whenever some content is successfully written to it.
You can safely transform any output to an unit output in a safe way by using this function.
Binary files API
Here is some API useful for working with binary files, in particular binary files generated by C applications. By default, encoding of multibyte integers is low-endian. The BigEndian module provide multibyte operations with other encoding.
exception Overflow of stringException raised when a read or write operation cannot be completed.
val read_byte : input -> intRead an unsigned 8-bit integer.
val read_signed_byte : input -> intRead an signed 8-bit integer.
val read_ui16 : input -> intRead an unsigned 16-bit word.
val read_i16 : input -> intRead a signed 16-bit word.
val read_i32 : input -> intRead a signed 32-bit integer.
val read_real_i32 : input -> int32Read a signed 32-bit integer as an OCaml int32.
val read_i64 : input -> int64Read a signed 64-bit integer as an OCaml int64.
val read_float : input -> floatRead an IEEE single precision floating point value.
val read_double : input -> floatRead an IEEE double precision floating point value.
val read_string : input -> stringRead a null-terminated string.
val read_line : input -> stringRead a LF or CRLF terminated string. If the source runs out of input before a LF is found, returns a string of the remaining input. Will raise No_more_input only if no characters are available.
Write an unsigned 8-bit byte.
Write an unsigned 16-bit word.
Write a signed 16-bit word.
Write a signed 32-bit integer.
val write_real_i32 : (int32, _) printerval write_double : (float, _) printerWrite an IEEE double precision floating point value.
val write_float : (float, _) printerWrite an IEEE single precision floating point value.
val write_string : (string, _) printerWrite a string and append an null character.
val write_line : (string, _) printerWrite a line and append a line end.
This adds the correct line end for your operating system. That is, if you are writing to a file and your system imposes that files should end lines with character LF (or '\n'), as Unix, then a LF is inserted at the end of the line. If your system favors CRLF (or '\r\n'), then this is what will be inserted.
Same operations as module BatIO, but with big-endian encoding
Bits API
This enable you to read and write from an BatIO bit-by-bit or several bits at the same time.
val read_bits : in_bits -> int -> intRead up to 31 bits, raise Bits_error if n < 0 or n > 31
val write_bits : out_bits -> nbits:int -> int -> unitWrite up to 31 bits represented as a value, raise Bits_error if nbits < 0 or nbits > 31 or the value representation excess nbits.
Flush remaining unwritten bits, adding up to 7 bits which values 0.
Drop up to 7 buffered bits and restart to next input character.
val create_in :
read:(unit -> char) ->
input:(Bytes.t -> int -> int -> int) ->
close:(unit -> unit) ->
inputFully create an input by giving all the needed functions.
Note Do not use this function for creating an input which reads from one or more underlying inputs. Rather, use wrap_in.
val wrap_in :
read:(unit -> char) ->
input:(Bytes.t -> int -> int -> int) ->
close:(unit -> unit) ->
underlying:input list ->
inputFully create an input reading from other inputs by giving all the needed functions.
This function is a more general version of create_in which also handles dependency management between inputs.
Note When you create an input which reads from another input, function close should not close the inputs of underlying. Doing so is a common error, which could result in inadvertently closing stdin or a network socket, etc.
val inherit_in :
?read:(unit -> char) ->
?input:(Bytes.t -> int -> int -> int) ->
?close:(unit -> unit) ->
input ->
inputSimplified and optimized version of wrap_in which may be used whenever only one input appears as dependency.
inherit_in inp will return an input identical to inp. inherit_in ~read inp will return an input identical to inp except for method read, etc.
You do not need to close inp in close.
val create_out :
write:(char -> unit) ->
output:(Bytes.t -> int -> int -> int) ->
flush:(unit -> unit) ->
close:(unit -> 'a) ->
'a outputFully create an output by giving all the needed functions.
val wrap_out :
write:(char -> unit) ->
output:(Bytes.t -> int -> int -> int) ->
flush:(unit -> unit) ->
close:(unit -> 'a) ->
underlying:'b output list ->
'a outputFully create an output that writes to one or more underlying outputs.
This function is a more general version of create_out, which also handles dependency management between outputs.
To illustrate the need for dependency management, let us consider the following values:
- an output
out - a function
f : _ output -> _ output, using create_out to create a new output for writing some data to an underyling output (for instance, a function comparale to tab_out or a function performing transparent compression or transparent traduction between encodings)
With these values, let us consider the following scenario
- a new output
f out is created - some data is written to
f out but not flushed - output
out is closed, perhaps manually or as a consequence of garbage-collection, or because the program has ended - data written to
f out is flushed.
In this case, data reaches out only after out has been closed. Despite appearances, it is quite easy to reach such situation, especially in short programs.
If, instead, f uses wrap_out, then when output out is closed, f out is first automatically flushed and closed, which avoids the issue.
val inherit_out :
?write:(char -> unit) ->
?output:(Bytes.t -> int -> int -> int) ->
?flush:(unit -> unit) ->
?close:(unit -> unit) ->
'a output ->
unit outputSimplified and optimized version of wrap_out whenever only one output appears as dependency.
inherit_out out will return an output identical to out. inherit_out ~write out will return an output identical to out except for its write method, etc.
You do not need to close out in close.
For compatibility purposes
Create an input that will read from a channel.
Create an output that will write into a channel.
Create a channel that will read from an input.
Note This function is extremely costly and is provided essentially for debugging purposes or for reusing legacy libraries which can't be adapted. As a general rule, if you can avoid using this function, don't use it.
Generic BatIO Object Wrappers
These OO Wrappers have been written to provide easy support of BatIO by external libraries. If you want your library to support BatIO without actually requiring Batteries to compile, you can implement the classes in_channel, out_channel, poly_in_channel and/or poly_out_channel which are the common BatIO specifications established for ExtLib, OCamlNet and Camomile.
(see http://www.ocaml-programming.de/tmp/BatIO-Classes.html for more details).
Note In this version of Batteries Included, the object wrappers are not closed automatically by garbage-collection.
Enumeration API
Read an enumeration of unsigned 8-bit integers.
Read an enumeration of signed 8-bit integers.
Read an enumeration of unsigned 16-bit words.
Read an enumartion of signed 16-bit words.
Read an enumeration of signed 32-bit integers.
Read an enumeration of signed 32-bit integers as OCaml int32s.
Read an enumeration of signed 64-bit integers as OCaml int64s.
Read an enumeration of IEEE double precision floating point values.
Read an enumeration of IEEE single precision floating point values.
Read an enumeration of null-terminated strings.
Read an enumeration of LF or CRLF terminated strings.
Buffered version of lines_of, for performance.
Read an input as an enumeration of strings of given length. If the input isn't a multiple of that length, the final string will be smaller than the rest.
Read an enumeration of Latin-1 characters.
Note Usually faster than calling read several times.
Read an enumeration of bits
Write an enumeration of bits
val default_buffer_size : intThe default size for internal buffers.
Thread-safety
synchronize_in inp produces a new input which reads from input in a thread-safe way. In other words, a lock prevents two distinct threads from reading from that input simultaneously, something which would potentially wreak havoc otherwise
synchronize_out out produces a new output which writes to output in a thread-safe way. In other words, a lock prevents two distinct threads from writing to that output simultaneously, something which would potentially wreak havoc otherwise
Thread-safety internals
Unless you are attempting to adapt Batteries Included to a new model of concurrency, you probably won't need this.
A lock used to synchronize internal operations.
By default, this is BatConcurrent.nolock. However, if you're using a version of Batteries compiled in threaded mode, this uses BatMutex. If you're attempting to use Batteries with another concurrency model, set the lock appropriately.
val to_string : ('a, string) printer -> 'a -> string