OUTPUT¶

Companion mod for output vals.

4.55.1. type output¶

An 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.

Operations on an output may cause IO errors, thus the methods take $on_error optional parameter to handle an IO error.

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

`write` writes a sequence of bytes in `Bin`, from the specified offset, to the end of `Bin`.

The invocation of `write` finishes in the three modes:

• Success: Every byte is written. In this case, `write` tail-calls the success cont with no arg.

• Partial: Bytes in the range [Offset, End) are written, but `End` is smaller than the size of `Bin`. So `write` should be called again with `End` as the new offset, when the output is ready. In this case, `write` tail-calls the partial cont with `End`.

• Error: An IO error occurs. In this case, `write` tail-calls the error cont with a str as an error message.

Preconditions

• `Bin` must be a bin.

• $config, if specified, must be a fun which takes a conf val.

Conf val

The conf val provides the following methods:

• C.offset(Offset) : uses `Offset` as the offset where the byte sequence to write starts. `Offset` must be an int num in the range [0, Bin.size]. If `offset` is not called, 0 is used as the default offset.

• C.on_success($success_cont) : uses $success_cont as the success cont. $success_cont must be a fun which takes no arg. If `on_success` is not called, {} is used as the default success cont.

• C.on_partial($partial_cont) : uses $partial_cont as the partial cont. $partial_cont must be a fun which takes an int num like {(:End) ,,, }. If `on_partial` is not called, a fun which raises an exception is used as the default partial cont.

• C.on_error($error_cont) : uses $error_cont as the error cont. $error_cont must be a fun which takes a str like {(:Msg) ,,, }. If `on_error` is not called, a fun which raises an exception is used as the default error cont.

Example 1

: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.of(0x01 0x02 0x03 0x04 0x05)

When an error occurs, `write` tail-calls the error cont with an error message, or raises an exception if it is not given.

Example 2

: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{(:Msg)
    stderr.print_line(Msg)
  }
}
# => java.io.IOException: Stream Closed

CONTROL.try(
  { Out.write(BIN.of(1 2 3)) }
  {(:R) raise('not here') }
  {(:Exc)
    stderr.print_line(Exc.message)
  }
)
# => Stream_output.write: java.io.IOException: Stream Closed

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

`flush` flushes the pending bin to the underlying destination.

Precondition:

• $config, if given, must be a fun which takes a conf val.

The conf val provides the following methods:

• C.on_success($success_cont) : uses $success_cont as the success cont. If not called, {} is used as the default success cont.

• C.on_partial($partial_cont) : uses $partial_cont as the partial cont. If not called, a fun which raises an exception is used as the default partial cont.

• C.on_error($error_cont) : uses $error_cont as the error cont. If not called, the default error cont raises an exception on an IO error.

Result:

• If `flush` succeeds to flush all the remaining bytes, `flush` tail-calls the success cont with no args.

• If `flush` didn't write all the remaining bytes, so there are still remaining bytes, `flush` tail-calls the partial cont with no args.

• If an IO error occurs, Output.flush tail-calls the error cont with an error message.

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

Output.close closes the underlying destination.

Precondition:

• $config, if given, must be a fun which takes a conf val.

The conf val provides the following methods:

• C.on_success($success_cont) : uses $success_cont as the success cont. If not called, {} is used as the default success cont.

• C.on_error($error_cont) : uses $error_cont as the error cont. If not called, the default error cont raises an exception on an IO error.

Result:

• If Output.close succeeds to close the destination, it tail-calls the success cont with no args.

• If an IO error occurs, Output.close tail-calls the error cont with an error message.

4.55.2. OUTPUT.is?(Val)¶

OUTPUT.is? returns whether the Val is an output.