5.58. kink/io/INPUT

Companion mod for input vals.

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

5.58.1.1. Input.read(Max_size ...[$config={}])

`read` reads bytes from the stream. `read` blocks until one or more bytes are read, the end-of-file is detected, or an IO error occurs.

Config methods:

• C.on_success($success): default = VAL.identity

• C.on_eof($eof): default = fun which raises an exception

• C.on_error($error): default = fun which raises an exception

If one or more bytes are read, `read` tail-calls $success with a `bin` val of the bytes. The size of the `bin` val does not exceed `Max_size`.

If the end-of-file is detected, `read` tail-calls $eof with no arg.

If an IO error occurs, `read` tail-calls $error with an `exception`.

Preconditions

• `Max_size` must be an int num which is equal to or bigger than 1.

• $success must be a fun which takes a `bin`.

• $eof must be a fun which takes no arg.

• $error must be a fun which takes an `exception`.

Example

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

:In <- BIN_INPUT.new(BIN.of(1 2 3))
:loop <- {(:Vec)
  In.read(2){(:C)
    C.on_success{(:Bin) loop(Vec + [Bin]) }
    C.on_eof{ Vec }
  }
}
:Result <- loop([])
stdout.print_line(Result.repr)  # => [(bin 0x01 0x02) (bin 0x03)]

Example: IO error

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

:In <- FILE.open_to_read('/etc/passwd')
In.close
In.read(10){(:C)
  C.on_error{(:Exc)
    stderr.print_line(Exc.message)
  }
}
# => already closed

In.read(10)
# Output:
#   -- main exception
#   [..root..]
#   {..call by host..}
#   ,,,
#   {builtin:kink-mods/kink/EXCEPTION.kn L117 C13 current_traces} { TRACE.-->current_traces }
#   already closed

5.58.1.2. Input.close(...[$config={}])

`close` closes the resource of the underlying source of bytes.

Config methods:

• C.on_success($success): default = {}

• C.on_error($error): default = a fun which raises an exception

If the resource is closed with no error, `close` tail-calls $success with no arg.

If an IO error occurs, `close` tail-calls $error with an `exception`.

Preconditions

• $success must be a fun which takes no arg

• $error must be a fun which takes an `exception`

5.58.2. INPUT.is?(Val)

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

5.58.3. INPUT.read_all(Input ...[$config={}])

`read_all` reads all the remaining bytes from `Input`.

Config methods:

• C.on_success($success): default = VAL.identity

• C.on_error($error): default = a fun which raises an exception

If one or more bytes are read with no IO error, `read_all` tail-calls $success with a `bin` of the bytes.

If there is no remaining bytes, `read_all` tail-calls $success with an empty `bin`.

If an IO error occurs, `read_all` tail-calls $error with an `exception`.

Precondition

• `Input` must be an `input`

• $success must be a fun which takes a `bin`

• $error must be a fun which takes an `exception`

Example

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

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