| 1 |
// SPDX-License-Identifier: MPL-2.0 |
| 2 |
// (c) Hare authors <https://harelang.org> |
| 3 |
|
| 4 |
use errors; |
| 5 |
|
| 6 |
// Returned by [[readall]] if the I/O handle returned [[EOF]] prior to |
| 7 |
// completely reading an item. Stores the amount that was succesfully read. |
| 8 |
export type underread = !size; |
| 9 |
|
| 10 |
// Any error which may be returned from an I/O function. |
| 11 |
export type error = !(...errors::error | underread | nomem); |
| 12 |
|
| 13 |
// Indicates an end-of-file condition. |
| 14 |
export type EOF = done; |
| 15 |
|
| 16 |
// Converts an I/O [[error]] into a user-friendly string. |
| 17 |
export fn strerror(err: error) str = { |
| 18 |
match (err) { |
| 19 |
case underread => |
| 20 |
return "Insufficient data to read entire item"; |
| 21 |
case nomem => |
| 22 |
return errors::strerror(nomem); |
| 23 |
case let err: errors::error => |
| 24 |
return errors::strerror(err); |
| 25 |
}; |
| 26 |
}; |
| 27 |
|
| 28 |
// Used to indicate if a stream should be used for reading, or writing, or both. |
| 29 |
export type mode = enum u8 { |
| 30 |
NONE = 0, |
| 31 |
READ = 1 << 0, |
| 32 |
WRITE = 1 << 1, |
| 33 |
RDWR = READ | WRITE, |
| 34 |
}; |
| 35 |
|
| 36 |
// From "whence" a seek operation should occur. |
| 37 |
export type whence = enum { |
| 38 |
SET = 0, // Relative to beginning (i.e. set absolute position). |
| 39 |
CUR = 1, // Relative to current position. |
| 40 |
END = 2, // Relative to end of handle. |
| 41 |
}; |
| 42 |
|
| 43 |
// The interface for a stream which can be read from. Reads up to len(buf) |
| 44 |
// bytes from the reader into the given buffer, returning the number of bytes |
| 45 |
// read or an error. |
| 46 |
export type reader = fn(s: *stream, buf: []u8) (size | EOF | error); |
| 47 |
|
| 48 |
// The interface for a stream which can be written to. Writes up to len(buf) |
| 49 |
// bytes to the writer from the given buffer, returning the number of bytes |
| 50 |
// written or an error. |
| 51 |
export type writer = fn(s: *stream, buf: const []u8) (size | error); |
| 52 |
|
| 53 |
// The interface for a stream which can be closed. This function should close |
| 54 |
// and free any underlying resources, and cannot be used again. |
| 55 |
export type closer = fn(s: *stream) (void | error); |
| 56 |
|
| 57 |
// The interface for a stream which provides an efficient path for copying data |
| 58 |
// from a second I/O source. |
| 59 |
// |
| 60 |
// Returns the number of bytes copied, or an error if one occured. Do not close |
| 61 |
// either "to" or "from". |
| 62 |
// |
| 63 |
// Most implementations of copier only support certain configurations of "to" |
| 64 |
// and "from", such as requiring both to be the same kind of [[stream]]. In case |
| 65 |
// of an unsupported configuration, return [[errors::unsupported]]. [[copy]] |
| 66 |
// falls back to a read/write loop in this case. |
| 67 |
export type copier = fn(to: *stream, from: handle) (size | error); |
| 68 |
|
| 69 |
// The interface for a stream which can be seeked. Sets the offset for the next |
| 70 |
// read or write to offset, interpreted according to whence: |
| 71 |
// whence::SET means relative to the start of the file, |
| 72 |
// whence::CUR means relative to the current offset, and |
| 73 |
// whence::END means relative to the end. |
| 74 |
// |
| 75 |
// Returns the new offset relative to the start or an error. |
| 76 |
export type seeker = fn(s: *stream, off: off, w: whence) (off | error); |