# Module Batteries.IO

    module IO: BatIO

    type input = BatInnerIO.input

The abstract input type.

    type 'a output = 'a BatInnerIO.output

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 -> unit

The type of a printing function to print a `'a` to an output that produces `'b` as result.

    type 'a f_printer = Format.formatter -> 'a -> unit

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

    exception Input_closed

This exception is raised when reading on a closed input.

    exception Output_closed

This exception is raised when reading on a closed output.

###### Standard inputs/outputs

    val stdin : input

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";`

    val stdout : unit output

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);`

    val stderr : unit output

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";`

    val stdnull : unit output

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

    val read : input -> char

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

- `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`.
Raises

- `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

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

Example: `close_in network_in;`

    val write : (char, 'a) printer

Write a single char to an output.

Example: `write stdout 'x';`

    val nwrite : (string, 'a) printer

Write a string to an output.

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`.
Raises `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

Flush an output.

If previous write operations have caused errors, this may trigger an exception.

Example: `flush stdout;`

    val flush_all : unit -> unit

Flush all outputs, ignore errors.

Example: `flush_all ();`

    val close_out : 'a output -> 'a

Close 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)`

    val comb : 'a output * 'a output -> 'a output

Old name of `combine`

    val make_enum : (input -> 'a) -> input -> 'a BatEnum.t

###### Debugging facilities

    val get_output_id : 'a output -> int

    val get_input_id : input -> int

    module Incubator: sig .. end