3.44. kink/io/INPUT

Companion mod for input vals.

3.44.1. type input

An input is an input port for bytes and bins from an underlying source of bytes such as files.

An input provides sequential forward access to the underlying source of bytes. It does not provide random access operations such as seek.

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

Input.read_byte(...[$on_error])

Input.read_byte reads a byte from the underlying source. If the byte exists, the method returns a single element vec [byte]; otherwise, returns [].

Example:

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

:In <- BIN_INPUT.new(BIN.of(1 2 3))
stdout.print_line(In.read_byte.repr)  # => [1]
stdout.print_line(In.read_byte.repr)  # => [2]
stdout.print_line(In.read_byte.repr)  # => [3]
stdout.print_line(In.read_byte.repr)  # => []
stdout.print_line(In.read_byte.repr)  # => []

When an error occurs, Input.read_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/')

:In <- FILE.open_to_read('/etc/passwd')
In.close
In.read_byte{(:Msg)
  stderr.print_line(Msg)
}
# => java.io.IOException: Stream Clsoed

CONTROL.try(
  { In.read_byte }
  {(:R) raise('not here') }
  {(:Msg :Traces)
    stderr.print_line(Msg)
  }
)
# => Stream_input.read_byte: java.io.IOException: Stream Closed

Input.read_bin(Max_size ...[$on_error])

Input.read_bin reads bytes till the size reaches Max_size, or reaches the end of the stream. The method then returns the bin of the bytes.

Precondition:

• Max_size must be a non-negative int num.

If there is no bytes remaining, the method returns an empty bin.

Example:

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

:In <- BIN_INPUT.new(BIN.of(1 2 3))
stdout.print_line(In.read_bin(2).repr)  # => BIN.of(0x01 0x02)
stdout.print_line(In.read_bin(2).repr)  # => BIN.of(0x03)
stdout.print_line(In.read_bin(2).repr)  # => BIN.of()

When an error occurs, Input.read_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/')
:CONTROL.require_from('kink/')

:In <- FILE.open_to_read('/etc/passwd')
In.close
In.read_bin(10){(:Msg)
  stderr.print_line(Msg)
}
# => java.io.IOException: Stream Clsoed

CONTROL.try(
  { In.read_bin(10) }
  {(:R) raise('not here') }
  {(:Msg :Traces)
    stderr.print_line(Msg)
  }
)
# => Stream_input.read_bin: java.io.IOException: Stream Closed

Input.read_all_bin(...[$on_error])

Input.read_all_bin reads all the remaining bytes and returns the bin.

If there is no bytes remaining, the method returns an empty bin.

Example:

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

:In <- BIN_INPUT.new(BIN.of(1 2 3))
stdout.print_line(In.read_all_bin.repr)  # => BIN.of(0x01 0x02 0x03)
stdout.print_line(In.read_all_bin.repr)  # => BIN.of()
stdout.print_line(In.read_all_bin.repr)  # => BIN.of()

When an error occurs, Input.read_all_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/')
:CONTROL.require_from('kink/')

:In <- FILE.open_to_read('/etc/passwd')
In.close
In.read_all_bin{(:Msg)
  stderr.print_line(Msg)
}
# => java.io.IOException: Stream Clsoed

CONTROL.try(
  { In.read_all_bin }
  {(:R) raise('not here') }
  {(:Msg :Traces)
    stderr.print_line(Msg)
  }
)
# => Stream_input.read_all_bin: java.io.IOException: Stream Closed

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

Input.close closes the underlying source of bytes.

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

3.44.2. INPUT.input?(Val)

INPUT.input? returns whether the Val is an input.