# Unit utils

This unit contains a "grab bag" of procedures without a good home, and which don't have to be available by default (as compared to the [[Unit extras|extras]] unit).
This unit uses the `extras` and `srfi-13` units.

## Executing shell commands with formatstring and error checking

### system*

     [procedure] (system* FORMATSTRING ARGUMENT1 ...)

Similar to `(system (sprintf FORMATSTRING ARGUMENT1 ...))`, but signals an error if the invoked program should return a nonzero exit status.

## Iterating over input lines and files

### for-each-line

     [procedure] (for-each-line PROCEDURE [PORT])

Calls `PROCEDURE` for each line read from `PORT` (which defaults to the value of `(current-input-port)`. The argument passed to `PROCEDURE` is a string with the contents of the line, excluding any line-terminators. When all input has been read from the port, `for-each-line` returns some unspecified value.

### for-each-argv-line

     [procedure] (for-each-argv-line PROCEDURE)

Opens each file listed on the command line in order, passing one line at a time into `PROCEDURE`. The filename `-` is interpreted as `(current-input-port)`. If no arguments are given on the command line it again uses the value of `(current-input-port)`. During execution of `PROCEDURE`, the current input port will be correctly bound to the current input source.
This code will act as a simple Unix cat(1) command:

    (for-each-argv-line print)

## Reading a file's contents

### read-all

     [procedure] (read-all [FILE-OR-PORT])

If `FILE-OR-PORT` is a string, then this procedure returns the contents of the file as a string. If `FILE-OR-PORT` is a port, all remaining input is read and returned as a string. The port is not closed. If no argument is provided, input will be read from the port that is the current value of `(current-input-port)`.

## Shell argument quoting

### qs

     [procedure] (qs STRING [PLATFORM])

Escapes `STRING` suitably for passing to a shell command on `PLATFORM`. `PLATFORM` defaults to the value of `(build-platform)` and indicates in which style the argument should be quoted. On Windows systems, the string is simply enclosed in double-quote (`"`) characters, on UNIXish systems, characters that would have a special meaning to the shell are escaped using backslash (`\`).

Previous: Unit posix
Next: Unit tcp