11.5 file.filter - Filtering file content

Module: file.filter

This module provides utilities for a common pattern in filter-type commands, that is, to take an input, to process the content, and to write the result. The common occurring pattern is:

• Input may be a specified file, or an input port (the current input port by default).
• Output may be a specified file, or an output port (the current output port by default).
• Output may be a temporary file, which will be renamed upon completion of the processing.
• Output file may be removed when an error occurs in the processing.

Function: file-filter proc &keyword input output temporary-file keep-output?

Calls proc with two arguments, an input port and an output port. Returns the result(s) of proc. The input port and output port are chosen depending on the keyword arguments.

input

The argument must be either an input port or a string that specifies a file name. If it's an input port, it is passed to proc as is. If it's a string, the named file is opened for input and the resulting port is passed to proc, and the port is closed when proc returns. If this argument is omitted, the current input port is passed.

output

The argument must be either an output port or a string that specifies a file name. If it's an output port, it is passed to proc as is. If it's a string, the named file is opened for output (unless temporary-file is given, in that case a temporary file is opened instead), and the resulting port is passed to proc. This port is closed when proc returns. If this argument is omitted, the current output port is passed.

temporary-file

If a string file name is given to this argument, the named file is opened for output during the processing, instead of the file name as output. The output port proc receives is connected to this file. When proc returns normally, the file is renamed to the name given to output keyword argument.

If the given file name begins with characters except "/", "./" or "../", the directory of the file name given to output argument is attached before it. Furthermore, a unique name is attached to the temporary file name (the temporary file is opened by sys-mkstemp.)

This argument is ignored when output argument is not a string file name.

keep-output?

If a true value is given, the output is not deleted even when proc signals an error. By default, the output (or the temporary file when temporary-file is given) will be deleted on error.