3.44. kink/io/PRINTER

Companion mod for printers.

3.44.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 :gen_str] <- STR_PRINTER.new_pair("\r\n")
P.print_line('foo')
P.print('bar')
stdout.print_line(gen_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:

• kink/CORE.stdout is a printer+output connected to the standard output.

• kink/CORE.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_pair makes an in-memory printer to build a str.

• kink/io/PRINTER.wrap makes a printer which is backed by an output.

Printer.print(Str ...[$on_error])

Printer.print writes the Str to the underlying destination.

Precondition:

• Str must be a str

Example:

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

[:P :gen_str] <- STR_PRINTER.new_pair("\r\n")
P.print('foo')
P.print('bar')
stdout.print_line(gen_str.repr) # => "foobar"

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

Example:

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

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

P.print('foo'){(:Msg)
  stderr.print_line(Msg)
}
# => java.io.IOException: Stream Closed

{ P.print('foo') }.try(
  { raise('not here') }
  {(:Msg :Traces)
    stderr.print_line(Msg)
  }
)
# => java.io.IOException: Stream Closed

Printer.print_line(Str ...[$on_error])

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

Precondition:

• Str must be a str

Example:

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

[:P :gen_str] <- STR_PRINTER.new_pair("\r\n")
P.print_line('foo')
P.print_line('bar')
stdout.print_line(gen_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/')

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

P.print_line('foo'){(:Msg)
  stderr.print_line(Msg)
}
# => java.io.IOException: Stream Closed

{ P.print_line('foo') }.try(
  { raise('not here') }
  {(:Msg :Traces)
    stderr.print_line(Msg)
  }
)
# => java.io.IOException: Stream Closed

Printer.new_line

Printer.new_line returns the new_line str of the Printer.

3.44.2. PRINTER.printer?(Val)

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

3.44.3. PRINTER.wrap(Output Encoding_name New_line ...[$config={}])

PRINTER.wrap makes a printer+output, which encodes str using Encoding_name, and writes bin to Output.

Preconditions:

• Output must be an output

• Encoding_name must be a str

• New_line must be a str

The result supports both printer and output types.

The optional fun param $config takes Conf as an arg, which is a wrap_printer_conf val. If $config is not specified, the result printer+output uses the default configuration.

Example:

:BIN_OUTPUT.require_from('kink/io/')
:PRINTER.require_from('kink/io/')

[:Out :gen_bin] <- BIN_OUTPUT.new_pair
:P <- PRINTER.wrap(Out 'UTF-8' "\r\n"){(:W)
  W.flush_on_print
}
P.print_line('foo')
stdout.print_line(gen_bin.repr) # => BIN.of(0x66 0x6f 0x6f 0x0d 0x0a)

3.44.4. type wrap_printer_conf

A wrap_printer_conf is a conf val of PRINTER.wrap.

Conf.flush_on_print

Conf.flush_on_print configures that the printer+output flushes bytes when .printer or .print_line is called.

If Conf.flush_on_print is not called, the printer+output resulted by PRINTER.wrap does not flush bytes when .printer or .print_line is called.