You are looking at historical revision 3765 of this page. It may differ significantly from its current revision.

• manual

Unit utils

This unit contains file/pathname oriented procedures, apropos, plus acts as a "grab bag" for procedures without a good home, and which don't have to be available by default (as compared to the extras unit.

This unit uses the extras and regex units.

Environment Query

apropos

[procedure] (apropos SYMBOL-PATTERN [ENVIRONMENT])

Displays symbols matching SYMBOL-PATTERN in the ENVIRONMENT on the (current-output-port).

SYMBOL-PATTERN

A symbol, string, or regex. When symbol or string substring matching is performed.

ENVIRONMENT

An environment. When missing the (interaction-environment) is assumed.

apropos-list

[procedure] (apropos-list SYMBOL-PATTERN [ENVIRONMENT])

Like apropos but returns a list of matching symbols.

Pathname operations

absolute-pathname?

[procedure] (absolute-pathname? PATHNAME)

Returns #t if the string PATHNAME names an absolute pathname, and returns #f otherwise.

decompose-pathname

[procedure] (decompose-pathname PATHNAME)

Returns three values: the directory-, filename- and extension-components of the file named by the string PATHNAME. For any component that is not contained in PATHNAME, #f is returned.

make-pathname

make-absolute-pathname

[procedure] (make-pathname DIRECTORY FILENAME [EXTENSION [SEPARATOR]])
[procedure] (make-absolute-pathname DIRECTORY FILENAME [EXTENSION [SEPARATOR]])

Returns a string that names the file with the components DIRECTORY, FILENAME and (optionally) EXTENSION with SEPARATOR being the directory separation indicator (usually / on UNIX systems and \ on Windows, defaulting to whatever platform this is running on). DIRECTORY can be #f (meaning no directory component), a string or a list of strings. FILENAME and EXTENSION should be strings or #f. make-absolute-pathname returns always an absolute pathname.

pathname-directory

[procedure] (pathname-directory PATHNAME)

pathname-file

[procedure] (pathname-file PATHNAME)

pathname-extension

[procedure] (pathname-extension PATHNAME)

Accessors for the components of PATHNAME. If the pathname does not contain the accessed component, then #f is returned.

pathname-replace-directory

[procedure] (pathname-replace-directory PATHNAME DIRECTORY)

pathname-replace-file

[procedure] (pathname-replace-file PATHNAME FILENAME)

pathname-replace-extension

[procedure] (pathname-replace-extension PATHNAME EXTENSION)

Return a new pathname with the specified component of PATHNAME replaced by a new value.

pathname-strip-directory

[procedure] (pathname-strip-directory PATHNAME)

pathname-strip-extension

[procedure] (pathname-strip-extension PATHNAME)

Return a new pathname with the specified component of PATHNAME stripped.

directory-null?

[procedure] (directory-null? DIRECTORY)

Does the DIRECTORY consist only of path separators and the period?

DIRECTORY may be a string or a list of strings.

Temporary files

create-temporary-file

[procedure] (create-temporary-file [EXTENSION])

Creates an empty temporary file and returns its pathname. If EXTENSION is not given, then .tmp is used. If the environment variable TMPDIR, TEMP or TMP is set, then the pathname names a file in that directory.

Deleting a file without signalling an error

delete-file*

[procedure] (delete-file* FILENAME)

If the file FILENAME exists, it is deleted and #t is returned. If the file does not exist, nothing happens and #f is returned.

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 PORCEDURE 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)

port-for-each

[procedure] (port-for-each FN THUNK)

Apply FN to successive results of calling the zero argument procedure THUNK until it returns #!eof, discarding the results.

port-map

[procedure] (port-map FN THUNK)

Apply FN to successive results of calling the zero argument procedure THUNK until it returns #!eof, returning a list of the collected results.

port-fold

[procedure] (port-map FN ACC THUNK)

Apply FN to successive results of calling the zero argument procedure THUNK, passing the ACC value as the second argument. The FN result becomes the new ACC value. When THUNK returns #!eof, the last FN result is returned.

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.

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).

Funky ports

make-broadcast-port

[procedure] (make-broadcast-port PORT ...)

Returns a custom output port that emits everything written into it to the ports given as PORT .... Closing the broadcast port does not close any of the argument ports.

make-concatenated-port

[procedure] (make-concatenated-port PORT1 PORT2 ...)

Returns a custom input port that reads its input from PORT1, until it is empty, then from PORT2 and so on. Closing the concatenated port does not close any of the argument ports.

Miscellaneous handy things

shift!

[procedure] (shift! LIST [DEFAULT])

Returns the car of LIST (or DEFAULT if LIST is empty) and replaces the car of LIST with it's cadr and the cdr with the cddr. If DEFAULT is not given, and the list is empty, #f is returned. An example might be clearer, here:

(define lst '(1 2 3))
(shift! lst)             ==> 1, lst is now (2 3)

The list must contain at least 2 elements.

unshift!

[procedure] (unshift! X PAIR)

Sets the car of PAIR to X and the cdr to its cddr. Returns PAIR:

(define lst '(2))
(unshift! 99 lst)      ; lst is now (99 2)

Previous: Unit posix

Next: Unit tcp