Common Lisp the Language, 2nd Edition
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:
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
[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.
