Module `BatInnerIO`Source

Core of the BatIO module.

This module contains the core definitions of BatIO, so as to avoid circular dependencies between modules which only need simple functions of BatIO and that module itself.

Don't use this module, use BatIO.

author Nicolas Cannasse

author David Teller

author Philippe Strauss

author Edgar Friendly

Sourcetype input

Sourcetype 'a output

Sourceexception No_more_input

This exception is raised when reading on an input with the read or nread functions while there is no available token to read.

Sourceexception Input_closed

This exception is raised when reading on a closed input.

Sourceexception Output_closed

This exception is raised when reading on a closed output.

Sourceval read : input -> char

Read a single char from an input or raise No_more_input if no input available.

Sourceval read_all : input -> string

read all the contents of the input until No_more_input is raised.

Sourceval pipe : unit -> input * unit output

Create a pipe between an input and an output. Data written from the output can be read from the input.

Sourceval 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.

Sourceval really_nread : input -> int -> string

really_nread i n reads a string of exactly n characters from the input.

raises No_more_input
if at least n characters are not available.

raises Invalid_argument
if n < 0.

Sourceval input : input -> Bytes.t -> int -> int -> int

input i s p len reads up to len bytes from the given input, storing them in byte sequence s, starting at position p. It returns the actual number of bytes read 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.

Sourceval really_input : input -> Bytes.t -> int -> int -> int

really_input i s p len reads exactly len characters from the given input, storing them in the byte sequence s, starting at position p. For consistency with BatIO.input it returns len.

raises No_more_input
if at least len characters are not available.

raises Invalid_argument
if p and len do not designate a valid subsequence of s.

Sourceval close_in : input -> unit

Close the input. It can no longer be read from.

Sourceval write : 'a output -> char -> unit

Write a single char to an output.

Sourceval nwrite : 'a output -> string -> unit

Write a string to an output.

Sourceval nwrite_bytes : 'a output -> Bytes.t -> unit

Write a byte sequence to an output.

since 2.8.0

Sourceval output : 'a output -> Bytes.t -> int -> int -> int

output o s p len writes up to len characters from byte sequence len, 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.

Sourceval output_substring : 'a output -> string -> int -> int -> int

like output above, but outputs from a substring instead of a subsequence of bytes

since 2.8.0

Sourceval really_output : 'a output -> Bytes.t -> int -> int -> int

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.

raises Invalid_argument
if p and len do not designate a valid subsequence of s.

Sourceval really_output_substring : 'a output -> string -> int -> int -> int

like really_output above, but outputs from a substring instead of a subsequence of bytes

since 2.8.0

Sourceval flush : 'a output -> unit

Flush an output.

Sourceval flush_all : unit -> unit

Flush all outputs.

Sourceval close_out : 'a output -> 'a

Close the output and return its accumulator data. It can no longer be written.

Sourceval close_all : unit -> unit

Close all outputs. Ignore errors.

Sourceval input_string : string -> input

Create an input that will read from a string.

Sourceval output_string : unit -> string output

Create an output that will write into a string in an efficient way. When closed, the output returns all the data written into it.

Sourceval on_close_out : 'a output -> ('a output -> unit) -> unit

Source

val create_in : 
  read:(unit -> char) ->
  input:(Bytes.t -> int -> int -> int) ->
  close:(unit -> unit) ->
  input

Fully 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.

Source

val inherit_in : 
  ?read:(unit -> char) ->
  ?input:(Bytes.t -> int -> int -> int) ->
  ?close:(unit -> unit) ->
  input ->
  input

Simplified and optimized version of wrap_in whenever only one input appears as dependency.

Source

val wrap_in : 
  read:(unit -> char) ->
  input:(Bytes.t -> int -> int -> int) ->
  close:(unit -> unit) ->
  underlying:input list ->
  input

Fully 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.

Source

val create_out : 
  write:(char -> unit) ->
  output:(Bytes.t -> int -> int -> int) ->
  flush:(unit -> unit) ->
  close:(unit -> 'a) ->
  'a output

Fully create an output by giving all the needed functions.

parameter write
Write one character to the output (see write).

parameter output
Write a (sub)string to the output (see output).

parameter flush
Flush any buffers of this output (see flush).

parameter close
Close this output. The output will be automatically flushed.

Note Do not use this function for creating an output which writes to one or more underlying outputs. Rather, use wrap_out.

Source

val inherit_out : 
  ?write:(char -> unit) ->
  ?output:(Bytes.t -> int -> int -> int) ->
  ?flush:(unit -> unit) ->
  ?close:(unit -> unit) ->
  _ output ->
  unit output

Simplified and optimized version of wrap_out whenever only one output appears as dependency.

Source

val wrap_out : 
  write:(char -> unit) ->
  output:(Bytes.t -> int -> int -> int) ->
  flush:(unit -> unit) ->
  close:(unit -> 'a) ->
  underlying:'b output list ->
  'a output

Fully 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, which violates the protocol. Despite appearances, it is quite easy to reach such situation, especially in short programs.

The solution is to use wrap_out rather than create_out in f. Specifying that f out writes on out will then let the run-time flush and close f out when out is closed for any reason, which in turn avoids the issue.

parameter write
Write one character to the output (see write).

parameter output
Write a (sub)string to the output (see output).

parameter flush
Flush any buffers of this output (see flush).

parameter close
Close this output. The output will be automatically flushed.

parameter underlying
The list of outputs to which the new output will write.

Note Function close should not close underlying yourself. This is a common mistake which may cause sockets or standard output to be closed while they are still being used by another part of the program.

Sourceval default_buffer_size : int

The default size of buffers.

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.

Sourceexception Overflow of string

Exception raised when a read or write operation cannot be completed.

Sourceval read_byte : input -> int

Read an unsigned 8-bit integer.

Sourceval read_signed_byte : input -> int

Read an signed 8-bit integer.

Sourceval read_ui16 : input -> int

Read an unsigned 16-bit word.

Sourceval read_i16 : input -> int

Read a signed 16-bit word.

Sourceval read_i32 : input -> int

Read a signed 32-bit integer.

raises Overflow
if the read integer cannot be represented as an OCaml 31-bit integer.

Sourceval read_real_i32 : input -> int32

Read a signed 32-bit integer as an OCaml int32.

Sourceval read_i64 : input -> int64

Read a signed 64-bit integer as an OCaml int64.

Sourceval read_float : input -> float

Read an IEEE single precision floating point value.

Sourceval read_double : input -> float

Read an IEEE double precision floating point value.

Sourceval read_string : input -> string

Read a null-terminated string.

Sourceval read_line : input -> string

Read a LF or CRLF terminated string.

Sourceval write_byte : 'a output -> int -> unit

Write an unsigned 8-bit byte.

Sourceval write_ui16 : 'a output -> int -> unit

Write an unsigned 16-bit word.

Sourceval write_i16 : 'a output -> int -> unit

Write a signed 16-bit word.

Sourceval write_i32 : 'a output -> int -> unit

Write a signed 32-bit integer.

Sourceval write_real_i32 : 'a output -> int32 -> unit

Write an OCaml int32.

Sourceval write_i64 : 'a output -> int64 -> unit

Write an OCaml int64.

Sourceval write_double : 'a output -> float -> unit

Write an IEEE double precision floating point value.

Sourceval write_float : 'a output -> float -> unit

Write an IEEE single precision floating point value.

Sourceval write_string : 'a output -> string -> unit

Write a string and append an null character.

Sourceval write_line : 'a output -> string -> unit

Write a line and append a LF (it might be converted to CRLF on some systems depending on the underlying BatIO).

Sourceval cast_output : 'a output -> unit output

You can safely transform any output to an unit output in a safe way by using this function.

For compatibility purposes

Sourceval input_channel : ?autoclose:bool -> ?cleanup:bool -> in_channel -> input

Create an input that will read from a channel.

parameter autoclose
If true or unspecified, the input will be automatically closed when the underlying in_channel has reached its end.

parameter cleanup
If true, the channel will be automatically closed when the input is closed. Otherwise, you will need to close the channel manually.

Sourceval output_channel : ?cleanup:bool -> out_channel -> unit output

Create an output that will write into a channel.

parameter cleanup
If true, the channel will be automatically closed when the output is closed. Otherwise, you will need to close the channel manually.

Standard inputs/outputs

Sourceval stdin : input

Standard input, as per Unix/Windows conventions (by default, keyboard).

Sourceval stdout : unit output

Standard output, as per Unix/Windows conventions (by default, console).

Use this output to display regular messages.

Sourceval stderr : unit output

Standard error output, as per Unix/Windows conventions.

Use this output to display warnings and error messages.

Sourceval stdnull : unit output

An output which discards everything written to it.

Use this output to ignore messages.

Comparison

The following modules may be useful to create hashtables of inputs or outputs.

Sourcemodule Input : sig ... end

Sourcemodule Output : sig ... end

Install

Dune Dependency

Authors

Maintainers

Sources

doc/batteries.unthreaded/BatInnerIO/index.html

Module `BatInnerIO`Source

Binary files API

For compatibility purposes

Standard inputs/outputs

Comparison

package batteries

Install

Dune Dependency

Authors

Maintainers

Sources

doc/batteries.unthreaded/BatInnerIO/index.html

Module BatInnerIOSource

Binary files API

For compatibility purposes

Standard inputs/outputs

Comparison

Module `BatInnerIO`Source