OUTPUT¶

Companion mod for output vals.

3.51.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 ...[$config={}])¶

Output.write_byte writes a byte.

Preconditions:

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

• $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 write_byte succeeds to write a byte, it tail-calls the success cont with no argument.

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

Example:

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

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

When an error occurs, Output.write_byte tail-calls the error cont with an error message, or raises an exception if not specified.

Example:

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

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

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

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

Output.write_bin writes a bin.

Preconditions:

• Bin must be a bin

• $config, if specified, 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 write_bin succeeds to write the bin, it tail-calls the success cont with no args.

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

Example:

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

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

When an error occurs, Output.write_bin tail-calls the error cont with an error message, or raises an exception if it 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)){(:C)
  C.on_error{(:Msg)
    stderr.print_line(Msg)
  }
}
# => java.io.IOException: Stream Closed

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

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

Output.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_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.flush succeeds to flush bytes, it tail-calls the success cont with no args.

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

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.

3.51.2. OUTPUT.is?(Val)¶

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