Common Lisp the Language, 2nd Edition

Next: Examples of the Up: Logical Pathnames Previous: Parsing of Logical

### 23.1.5.3. Using Logical Pathnames

Some real file systems do not have versions. Logical pathname translation to such a file system ignores the version. This implies that a portable program cannot rely on being able to store in a file system more than one version of a file named by a logical pathname.

The type of a logical pathname for a Common Lisp source file is `LISP`. This should be translated into whatever implementation-defined type is appropriate in a physical pathname.

The logical pathname host name `SYS` is reserved for the implementation. The existence and meaning of logical pathnames for logical host `SYS` is implementation-defined.

File manipulation functions must operate with logical pathnames according to the following requirements:

- The following accept logical pathnames and translate them into physical pathnames as if by calling the function `translate-logical-pathname`:

      compile-file           ed               probe-file
      compile-file-pathname  file-author      rename-file
      delete-file            file-write-date  truename
      directory              load             with-open-file
      dribble                open

- Applying the function `pathname` to a stream created by the function `open` or the macro `with-open-file` using a logical pathname produces a logical pathname.

- The functions `truename`, `probe-file`, and `directory` never return logical pathnames.

- Calling `rename-file` with a logical pathname as the second argument returns a logical pathname as the first value.

- `make-pathname` returns a logical pathname if and only if the host is logical. If the `:host` argument to `make-pathname` is supplied, the host is logical if it came from the `pathname-host` of a logical pathname. Whether a `:host` argument is logical if it is a string equal to a logical pathname host name is implementation-defined.

[Function]
`logical-pathname pathname`

Converts the argument to a logical pathname and returns it. The argument can be a logical pathname, a logical pathname namestring containing a host component, or a stream for which the `pathname` function returns a logical pathname. For any other argument, `logical-pathname` signals an error of type `type-error`.

[Function]
`translate-logical-pathname pathname &key`

Translates a logical pathname to the corresponding physical pathname. The pathname argument is first coerced to a pathname. If it is not a pathname, string, or file stream, an error of type `type-error` is signaled.

If the coerced argument is a physical pathname, it is returned.

If the coerced argument is a logical pathname, the first matching translation (according to `pathname-match-p`) of the logical pathname host is applied, as if by calling `translate-pathname`. If the result is a logical pathname, this process is repeated. When the result is finally a physical pathname, it is returned.

If no translation matches a logical pathname, an error of type `file-error` is signaled.

`translate-logical-pathname` may perform additional translations, typically to provide translation of file types to local naming conventions, to accommodate physical file systems with names of limited length, or to deal with special character requirements such as translating hyphens to underscores or uppercase letters to lowercase. Any such additional translations are implementation-defined. Some implementations do no additional translations.

There are no specified keyword arguments for `translate-logical-pathname` but implementations are permitted to extend it by adding keyword arguments. There is one specified return value from `translate-logical-pathname`; implementations are permitted to extend it by returning additional values.

[Function]
`logical-pathname-translations host`

If the specified host is not the host component of a logical pathname and is not a string that has been defined as a logical pathname host name by `setf` of `logical-pathname-translations`, this function signals an error of type `type-error`; otherwise, it returns the list of translations for the specified host. Each translation is a list of at least two elements, from-wildname and to-wildname. Any additional elements are implementation-defined. A from-wildname is a logical pathname whose host is the specified host. A to-wildname is any pathname. Translations are searched in the order listed, so more specific from-wildnames must precede more general ones.

`(setf (logical-pathname-translations host) translations)` sets the list of translations for the logical pathname host to translations. If host is a string that has not previously been used as logical pathname host, a new logical pathname host is defined; otherwise an existing host's translations are replaced. Logical pathname host names are compared with `string-equal`.

When setting the translations list, each from-wildname can be a logical pathname whose host is host or a logical pathname namestring s parseable by `(parse-namestring s host-object)`, where host-object is an appropriate object for representing the specified host to `parse-namestring`. (This circuitous specification dodges the fact that `parse-namestring` does not necessarily accept as its second argument any old string that names a logical host.) Each to-wildname can be anything coercible to a pathname by application of the function `pathname`. If to-wildname coerces to a logical pathname, `translate-logical-pathname` will retranslate the result, repeatedly if necessary.

Implementations may define additional functions that operate on logical pathname hosts (for example, to specify additional translation rules or options).

[Function]
`load-logical-pathname-translations host`

If a logical pathname host named host (a string) is already defined, this function returns `nil`. Otherwise, it searches for a logical pathname host definition in an implementation-defined manner. If none is found, it signals an error. If a definition is found, it installs the definition and returns `t`.

The search used by `load-logical-pathname-translations` should be documented, as logical pathname definitions will be created by users as well as by Lisp implementors. A typical search technique is to look in an implementation-defined directory for a file whose name is derived from the host name in an implementation-defined fashion.

[Function]
`compile-file-pathname pathname &key :output-file`

Returns the pathname that `compile-file` would write into, if given the same arguments. If the pathname argument is a logical pathname and the `:output-file` argument is unspecified, the result is a logical pathname. If an implementation supports additional keyword arguments to `compile-file`, `compile-file-pathname` must accept the same arguments.

Next: Examples of the Up: Logical Pathnames Previous: Parsing of Logical