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