5.60. kink/io/OUTPUT

Companion mod for output vals.

5.60.1. type output

`output` is an output port of bytes to an underlying destination such as a file.

An `output` provides sequential operations which append bytes to the tail.

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

`write` writes a sequence of bytes in `Bin`. Some or all bytes can be written to the buffer, depending on the implementation.

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

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

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

5.60.2. OUTPUT.is?(Val)

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