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-pathnamepathname

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-pathnamepathname&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-translationshost

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-translationshost)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-namestringshost-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-translationshost

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-pathnamepathname&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

AI.Repository@cs.cmu.edu