12.33 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 :key input output temporary-file keep-output? rename-hook ¶

{file.filter} 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

The value must be a boolean or a string. If a non-false value is given, and output is a file, then a fresh temporary file is created and opened for output and passed to proc. When proc returns normally, the file is renamed to the name given to output keyword argument.

If #t is given, a temporary file name is generated based on the name of the output file. If a string file name is given to this argument, the name is used for sys-mkstemp.

If the given file name begins with characters except "/", "./" or "../", the directory of the file name given to output argument is attached before it.

The default value is #f (do not use a temporary file).

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.

leave-unchanged

When a temporary file is used, and a true value is given to this argument, the existing output file is left intact when the generated output in the temporary file exactly matches the original content of the output file. It is useful if touching output file may trigger some actions (e.g. by make) and you want to avoid invoking unnecessary actions. The default value is #f (always replace the output).

Function: file-filter-fold proc seed :key reader input output temporary-file keep-output? rename-hook ¶

{file.filter} A convenience wrapper of file-filter. Call proc for each item read from input by reader (read-line by default). The argument proc receives is the item, the seed value and the output port; proc can emit the output, as well as returning some value that is passed along as the seed value. Other keyword arguments are passed to file-filter.

For example, the following code reads each line from file.txt and displays lines matching #/regexp/ with line numbers.

(file-filter-fold
  (^[line nc out]
    (when (#/regexp/ line) (format out "~3d: ~a\n" nc line))
    (+ nc 1))
  1 :input "file.txt")

Function: file-filter-map proc :key reader input output temporary-file keep-output? rename-hook ¶

Function: file-filter-for-each proc :key reader input output temporary-file keep-output? rename-hook ¶

{file.filter} Utilities similar to file-filter-fold, like map and for-each to fold.

The procedure proc is called with two arguments, an item read from the input and an output port. The results of proc are collected as a list and returned by file-filter-map, and discarded by file-filter-for-each.

The meaning of keyword arguments are the same as file-filter-fold.