6.64. kink/io/OUTPUT

Companion mod for `output` vals.

6.64.1. type output

`output` is an abstract type of output port of bytes. `output` values must implement the following methods.

An `output` provides sequential forward access to the underlying destination.

6.64.1.1. Output.write(Bin ...[$config={}])

`write` writes the sequence of bytes of `Bin`.

Config methods:

• C.on_success($success): default = {}

• C.on_error($error): default = a fun which raises an exception

If every byte is written without an IO error, `write` tail-calls $success with no arg.

If an IO error occurs, `write` tail-calls $error with an `exception`.

Preconditions

`Bin` must be a `bin`.

$success must be a fun which takes no arg.

$error must be a fun which takes an `exception`.

Example

:BIN_OUTPUT.require_from('kink/io/')
:BIN.require_from('kink/')

:Out <- BIN_OUTPUT.new
Out.write(BIN.of(1 2 3))
Out.write(BIN.of(4 5))
stdout.print_line(Out.bin.repr) # => (bin 0x01 0x02 0x03 0x04 0x05)

Example: IO error

:FILE.require_from('kink/io/')
:BIN.require_from('kink/')
:CONTROL.require_from('kink/')

:Out <- FILE.open_to_write('/tmp/tmpfile')
Out.close
Out.write(BIN.of(1 2 3)){(:C)
  C.on_error{(:Exc)
    stderr.print_line(Exc.message)
  }
}
# => already closed

Out.write(BIN.of(1 2 3))
# Output:
#   -- main exception
#   [..root..]
#   {..call by host..}
#   ,,,
#   already closed

6.64.1.2. Output.flush(...[$config={}])

`flush` writes the buffered bytes to the underlying destination.

Config methods:

• C.on_success($success): default = {}

• C.on_error($error): default = a fun which raises an exception

If the remaining bytes are written without an IO error, `flush` tail-calls $success with no args.

If an IO error occurs, `flush` tail-calls $error with an `exception`.

Precondition

$success must be a fun which takes no arg.

$error must be a fun which takes an `exception`.

6.64.1.3. Output.close(...[$config={}])

`close` flushes the buffer, and closes the resource of the underlying destination.

Config methods:

• C.on_success($success): default = {}

• C.on_error($error): default = a fun which raises an exception

If the buffer is flushed, and the resource is closed without an IO error, `close` tail-calls $success with no arg.

If an IO error occurs, `close` tail-calls $error with an `exception`.

Precondition

$success must be a fun which takes no arg.

$error must be a fun which takes an `exception`.

6.64.2. OUTPUT.is?(Val)

`is?` returns whether `Val` is an `output`.