5.62. kink/io/PRINTER

Companion mod for printers.

5.62.1. type printer

`printer` is an output port of strs to an underlying destination such as a file.

`scanner` provides sequential forward operations to the underlying destination.

Example:

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

:P <- STR_PRINTER.new("\r\n")
P.print_line('foo')
P.print('bar')
stdout.print_line(P.str.repr) # => "foo\r\nbar"

Commonly used printers:

• `stdout` is a printer+output connected to the standard output.

• `stderr` is a printer+output connected to the standard error output.

• kink/io/FILE.open_to_print returns a printer+output for a file.

• kink/io/STR_PRINTER.new makes an in-memory printer to build a str.

• kink/io/OUTPUT_PRINTER.new makes a printer which is backed by an output.

5.62.1.1. Printer.print(Str ...[$config={}])

`print` writes `Str` to the underlying destination.

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

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

If `Str` is written without an IO error, `print` tail-calls $success with no arg.

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

Preconditions

• Str must be a str

• $success must be a fun which takes no arg

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

Example

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

:P <- STR_PRINTER.new("\r\n")
P.print('foo')
P.print('bar')
stdout.print_line(P.str.repr) # => "foobar"

Example: IO error

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

:P <- FILE.open_to_print('/tmp/print.txt' CHARSET.utf8 "\r\n")
P.close

P.print('foo'){(:C)
  C.on_error{(:Exc)
    stderr.print_line(Exc.message)
  }
}
# => already closed

P.print('foo')
# Output:
#   -- main exception
#   [..root..]
#   {..call by host..}
#   ,,,
#   already closed

5.62.1.2. Printer.print_line(Str ...[$config={}])

`print_line` writes `Str` and `newline` to the underlying destination.

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

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

If `Str` and `newline` are written without an IO error, `print_line` tail-calls $success with no arg.

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

Preconditions

• Str must be a str

• $success must be a fun which takes no arg

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

Example

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

:P <- STR_PRINTER.new("\r\n")
P.print_line('foo')
P.print_line('bar')
stdout.print_line(P.str.repr) # => "foo\r\nbar\r\n"

Example: IO error

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

:P <- FILE.open_to_print('/tmp/print.txt' CHARSET.utf8 "\r\n")
P.close

P.print_line('foo'){(:C)
  C.on_error{(:Exc)
    stderr.print_line(Exc.message)
  }
}
# => already closed

P.print_line('foo')
# Output:
#   -- main exception
#   [..root..]
#   {..call by host..}
#   ,,,
#   already closed

5.62.1.3. Printer.newline

`newline` returns the newline used by `print_line`.

5.62.2. PRINTER.is?(Val)

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