3.45. kink/io/OUTPUT

Companion mod for output vals.

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

Output.write_byte(Byte ...[$on_error])

Output.write_byte writes a byte.

Precondition:

• Byte is an int num in the range [0, 255]

Example:

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

[:Out :gen_bin] <- BIN_OUTPUT.new_pair
Out.write_byte(1)
Out.write_byte(2)
Out.write_byte(3)
stdout.print_line(gen_bin.repr) # => BIN.of(0x01 0x02 0x03)

When an error occurs, Output.write_byte tail-calls $on_error with an error message, or raises an exception if $on_error is not given.

Example:

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

:Out <- FILE.open_to_write('/tmp/tmpfile')
Out.close
Out.write_byte(42){(:Msg)
  stderr.print_line(Msg)
}
# => java.io.IOException: Stream Closed

CONTROL.try(
  { Out.write_byte(42) }
  {(:R) raise('not here') }
  {(:Msg :Traces)
    stderr.print_line(Msg)
  }
)
# => Stream_output.write_byte: java.io.IOException: Stream Closed

Output.write_bin(Bin ...[$on_error])

Output.write_bin writes a bin.

Example:

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

[:Out :gen_bin] <- BIN_OUTPUT.new_pair
Out.write_bin(BIN.of(1 2 3))
Out.write_bin(BIN.of(4 5))
stdout.print_line(gen_bin.repr) # => BIN.of(0x01 0x02 0x03 0x04 0x05)

When an error occurs, Output.write_bin tail-calls $on_error with an error message, or raises an exception if $on_error is not given.

Example:

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

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

Output.flush(...[$on_error])

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

When an error occurs, it tail-calls $on_error with an error message, or raises an exception if $on_error is not given.

Output.close(...[$on_error])

Output.close closes the underlying destination.

When an error occurs, it tail-calls $on_error with an error message, or raises an exception if $on_error is not given.

3.45.2. OUTPUT.output?(Val)

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