SCANNER¶

Companion mod of scanners.

6.67.1. type scanner¶

`scanner` is an input port for strings or Unicode code points. A scanner provides sequential forward access to the underlying source.

Example

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

CONTROL.with_finally{(:finally)
  :S = FILE.open_to_scan('/etc/passwd' CHARSET.utf8)
  # result of FILE.open_to_scan also supports .close method of input type
  finally{ S.close }

  S.scan_line{
    C.on_success{(:Line)
      stdout.print_line(Line.repr)
    }
    C.on_eof{ stdout.print_line('no line found') }
  }
}
# => "root:x:0:0:root:/root:/bin/bash\n"

6.67.1.1. Scanner.scan(Max_codepoints ...[$config])¶

`scan` reads a `str` consisting of up to `Max_codepoints` code points.

Config methods:

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

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

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

If the end-of-file has not been reached, `scan` tail-calls $success with a `str` read from the source.

If the end-of-file has been reached, `scan` tail-calls $eof with no arg.

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

Preconditions

$success must be a fun which takes a `str`.

$eof must be a fun which takes no arg.

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

Example

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

:S <- STR_SCANNER.new("foo\nbar")
:loop <- {(:Vec)
  S.scan(3){(:C)
    C.on_success{(:Line) loop(Vec + [Line]) }
    C.on_eof{ Vec }
  }
}
:Result <- loop([])
stdout.print_line(Result.repr)  # => ["foo" "\nba" "r"]

6.67.1.2. Scanner.scan_line(...[$config={}])¶

`scan_line` reads a `str` until "\n" or the end-of-file is reached.

Config methods:

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

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

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

If "\n" is reached, `scan_line` tail-calls $success with a `str`. The `str` contains "\n" at the back.

If the end-of-file has been reached, `scan_line` tail-calls $eof with no arg.

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

Preconditions

$success must be a fun which takes a `str`.

$eof must be a fun which takes no arg.

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

Example

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

:S <- STR_SCANNER.new("foo\nbar")
:loop <- {(:Vec)
  S.scan_line{(:C)
    C.on_success{(:Line) loop(Vec + [Line]) }
    C.on_eof{ Vec }
  }
}
:Result <- loop([])
stdout.print_line(Result.repr)  # => ["foo\n" "bar"]

6.67.1.3. Scanner.scan_all(...[$config={}])¶

`scan_all` reads a `str` until the end-of-file.

Config methods:

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

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

If the end-of-file has been reached, `scan_all` tail-calls $success with a `str` read from the source.

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

Preconditions

$success must be a fun which takes a `str`

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

Example

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

:S <- STR_SCANNER.new("foo\nbar")
stdout.print_line(S.scan_all.repr)   # => "foo\nbar"
stdout.print_line(S.scan_all.repr)   # => ""
stdout.print_line(S.scan_all.repr)   # => ""

Example: IO error

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

:S <- FILE.open_to_scan('/etc/passwd' CHARSET.utf8)
S.close
S.scan_all{(:C)
  C.on_error{(:Exc)
    stderr.print_line(Exc.message)
  }
}
# => already closed

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

6.67.2. SCANNER.is?(Val)¶

`is?` returns whether `Val` is a `scanner`.

6.67.3. SCANNER.mixin¶

``mixin`` returns a mixin trait which provides an implementation of Scanner.scan_all. `scan_all` will be implemented using `scan` method.