[[tags: manual]]
[[toc:]]


== 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 ...)</procedure>

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

=== Reading a file's contents

==== read-all

<procedure>(read-all [FILE-OR-PORT])</procedure>

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])</procedure>

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 ({{\}}).


=== Dynamic compilation

==== compile-file

<procedure>(compile-file FILENAME #!key options output-file load)</procedure>

Compiles the Scheme source file {{FILENAME}} into a dynamically
loadable library by invoking the {{csc}} compiler driver. If the
library can be successfully created and {{load}} is not given or
true, the file is loaded into the current
Scheme process. {{options}} may be a list of strings which are passed
as additional command line options to {{csc}}. If {{output-file}} is
not given, then the compiled file is stored in a temporary location
and will be deleted when the process exits successfully.
When compilation and loading succeeds, the name of the compiled file
is returned.

Notes:

* loading the same compiled file multiple times is only supported on Linux
  in the moment and should be considered unreliable. For this reason, a new temporary
  file is created for every invocation of {{compile-file}}, unless an explicit
  output file name is given.

* this procedure is compatible to the {{scheme-compile-file}} command in {{emacs}}' {{scheme-mode}}.

==== compile-file-options

<parameter>compile-file-options</parameter>

A parameter that holds a list of default options that should be given
to {{csc}} after invocation of the {{compile-file}} procedure. 
The initial default options are {{-scrutinize -O2 -d2}}.

=== Scanning through an input port

==== scan-input-lines

<procedure>(scan-input-lines REGEXP [PORT])</procedure>

Reads lines from {{PORT}} (defaults to the result of {{(current-input-port)}})
using {{read-line}} and returns the result of {{(string-search REGEXP LINE)}},
if the match succeeds. If no match could be found, {{#f}} is returned.

{{REGEXP}} may also be a procedure of one argument which is called for each
input line and should return a non-false value on success.


=== Asking the user for confirmation

==== yes-or-no?

<procedure>(yes-or-no? MESSAGE #!key default title abort)</procedure>

Prints the string {{MESSAGE}} and asks for entering "yes", "no" or "abort".
If running under Windows in GUI mode, then a suitable dialog box is shown.
Returns either {{#t}} or {{#f}} depending on whether {{yes}} or {{no}}
was entered. The {{default}} keyword argument specifies the default
answer that is effective if the user just presses ENTER (or the default
button in case of a dialog box). {{title}} specifies the text shown
in the caption of the dialog box and is ignored when not running in
GUI mode. {{abort}} should be a zero-argument procedure that is
called when the user selects "abort". The default value for {{abort}}
is the {{reset}} procedure. A value of {{#f}} for {{abort}} disables
aborting completely.


Previous: [[Unit posix]]

Next: [[Unit tcp]]
