Chicken » Unit files

## Unit files

This unit contains file- and pathname-oriented procedures. It uses the `regex` unit.

### Pathname operations

#### absolute-pathname?

`(absolute-pathname? PATHNAME)` procedure

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

#### decompose-pathname

`(decompose-pathname PATHNAME)` procedure

  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

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

  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

#### pathname-file

#### pathname-extension

`(pathname-directory PATHNAME)` procedure
`(pathname-file PATHNAME)` procedure
`(pathname-extension PATHNAME)` procedure

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

#### pathname-replace-directory

#### pathname-replace-file

#### pathname-replace-extension

`(pathname-replace-directory PATHNAME DIRECTORY)` procedure
`(pathname-replace-file PATHNAME FILENAME)` procedure
`(pathname-replace-extension PATHNAME EXTENSION)` procedure

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

#### pathname-strip-directory

#### pathname-strip-extension

`(pathname-strip-directory PATHNAME)` procedure
`(pathname-strip-extension PATHNAME)` procedure

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

#### normalize-pathname

`(normalize-pathname PATHNAME [PLATFORM])` procedure

  Performs a simple "normalization" on the `PATHNAME`, suitably for `PLATFORM`, which should be one of the symbols `windows` or `unix` and defaults to on whatever platform is currently in use. All relative path elements and duplicate separators are processed and removed. If `NAME` ends with a `/` or is empty, the appropriate slash is appended to the tail. Tilde `~` and variable `$<name>/...` expansion is also done.

  No directories or files are actually tested for existence; this procedure only canonicalises path syntax.

#### directory-null?

`(directory-null? DIRECTORY)` procedure

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

  `DIRECTORY` may be a string or a list of strings.

#### decompose-directory

`(decompose-directory DIRECTORY)` procedure

  Returns 3 values: the `base-origin`, `base-directory`, and the `directory-elements` for the `DIRECTORY`.

  `base-origin`
    a `string` or `#f`. The drive, if any.
  `base-directory`
    a `string` or `#f`. A directory-separator when `DIRECTORY` is an `absolute-pathname`.
  `directory-elements`
    a `list-of string` or `#f`. The non-directory-separator bits.

  `DIRECTORY` is a `string`.

  - On Windows `(decompose-directory "c:foo/bar")` => `"c:" #f ("foo" "bar")`

### Temporary files and directories

#### create-temporary-file

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

  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. If none of the environment variables is given the location of the temporary file defaults to `/tmp` if it exists or the current-directory

#### create-temporary-directory

`(create-temporary-directory)` procedure

  Creates an empty temporary directory and returns its pathname. If the environment variable `TMPDIR, TEMP` or `TMP` is set, then the temporary directory is created at that location.

### Deleting a file without signalling an error

#### delete-file*

`(delete-file* FILENAME)` procedure

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

### File move/copy

#### file-copy

`(file-copy ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)` procedure

  Copies `ORIGFILE` (a string denoting some filename) to `NEWFILE`, `BLOCKSIZE` bytes at a time. `BLOCKSIZE` defaults to 1024, and must be a positive integer. Returns the number of bytes copied on success, or errors on failure. `CLOBBER` determines the behaviour of `file-copy` when `NEWFILE` is already extant. When set to `#f` (default), an error is signalled. When set to any other value, `NEWFILE` is overwritten. `file-copy` will work across filesystems and devices and is not platform-dependent.

#### file-move

`(file-move ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)` procedure

  Moves `ORIGFILE` (a string denoting some filename) to `NEWFILE`, with the same semantics as `file-copy`, above. `file-move` is safe across filesystems and devices (unlike `rename-file`). It is possible for an error to be signalled despite partial success if `NEWFILE` could be created and fully written but removing `ORIGFILE` fails.

Previous: Unit ports

Next: Unit extras