4.51. kink/io/PRINTER

Companion mod for printers.

4.51.1. type printer

A printer is an output port for strs to an underlying destination of runes such as a file.

A 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"

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

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/WRAP_PRINTER.new makes a printer which is backed by an output.

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

Printer.print writes the Str to the underlying destination.

Preconditions:

• Str must be a str

• $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 Printer.print succeeds to write the Str, it tail-calls the success cont with no args

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

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"

When an error occurs, Printer.print tail-calls the error cont with an error message, or raises an exception if it is not given.

Example:

: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{(:Msg)
    stderr.print_line(Msg)
  }
}
# => java.io.IOException: Stream Closed

CONTROL.try(
  { P.print('foo') }
  { raise('not here') }
  {(:Exc)
    stderr.print_line(Exc.message)
  }
)
# => Stream_output.write_bin: java.io.IOException: Stream Closed

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

Printer.print_line writes the Str, adding newline, to the underlying destination.

Precondition:

• Str must be a str

• $config, if given, must be a fun which takes a conf val

Preconditions:

• Str must be a str

• $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 Printer.print_line succeeds to write the line, it tail-calls the success cont with no args

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

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"

When an error occurs, Printer.print_line 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/')
: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{(:Msg)
    stderr.print_line(Msg)
  }
}
# => java.io.IOException: Stream Closed

CONTROL.try(
  { P.print_line('foo') }
  { raise('not here') }
  {(:Exc)
    stderr.print_line(Exc.message)
  }
)
# => Stream_output.write_bin: java.io.IOException: Stream Closed

4.51.1.3. Printer.newline

Printer.newline returns the newline str of the Printer.

4.51.2. PRINTER.is?(Val)

PRINTER.is? returns whether the Val is a printer.