| 1 |
io: high-level I/O abstraction and low-level file I/O |
| 2 |
|
| 3 |
The io module provides input and output (I/O) functionality for Hare programs, |
| 4 |
such as reading from or writing to files. The I/O module is not generally |
| 5 |
responsible for provisioning the I/O objects themselves; see modules like |
| 6 |
[[os::]] and [[net::]] for this purpose. |
| 7 |
|
| 8 |
I/O operations such as [[read]] or [[write]] accept an I/O handle, [[handle]], |
| 9 |
to specify the object of the I/O operation. This type is a tagged union of |
| 10 |
[[file]] and *[[stream]]. Most programmers should prefer to use [[handle]] |
| 11 |
unless they specifically require the special semantics of one of its subtypes. |
| 12 |
|
| 13 |
The [[file]] type provides access to an object, usually a file descriptor, which |
| 14 |
is provided by the host operating system. It represents objects such as a file |
| 15 |
on disk, an open network connection, and so on. The use of [[file]] is generally |
| 16 |
required when working with host I/O, such as with [[unix::poll::]]. |
| 17 |
|
| 18 |
The [[stream]] type is an abstraction that allows Hare programs to implement |
| 19 |
their own I/O objects by providing implementations of [[read]], [[write]], and |
| 20 |
other functions, for an [[handle]]. Several standard library modules offer |
| 21 |
implementations of [[stream]] for one reason or another, such as [[bufio::]]. |
| 22 |
Additionally, the io module provides some useful general-purpose I/O streams, |
| 23 |
such as [[tee]]. |