4.56. kink/io/PRINTER¶
Companion mod for printers.
4.56.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.56.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: java.io.IOException: Stream Closed
4.56.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: java.io.IOException: Stream Closed
4.56.1.3. Printer.newline¶
Printer.newline returns the newline str of the Printer.
4.56.2. PRINTER.is?(Val)¶
PRINTER.is? returns whether the Val is a printer.