The simplest kind of file specification is a plain textual description of the file desired. This can be in the form of either a symbol (or string in implementations with strings). It has no structure and its meaning or even validity as file name specifier varies from implementation to implementation. Typically, Maclisp programs try to carry around filenames internally as namelists and use the namestring format when displaying filenames to users, especially users who might not be familiar with Lisp's namelist format.

Namestrings may be fully qualified specifications (those with all the parts of the filename present):

They may also have parts omitted (which will be filled in by merging with other filenames later or which Lisp will fill in automatically with its default filenames if the parts are still unfilled when you try to actually reference such partially filled out filenames).

Users of Tops-20 should take note of the fact that "*" in Maclisp almost never means to quantify over all matching files, as it would for most other programs. Rather, it just means that this part of the name has been omitted. Maclisp handling of the Tops-20 file system leaves something to be desired, to say the least. It does fairly well considering it was not at all designed originally to handle this sort of file structure, but it has a lot of deficiencies. The "*" wildcard convention is not supported in any of the default primitives.

Using symbols instead of strings will also work. This is primarily useful in loading files interactively. Remember, of course, that odd symbols must be syntactically quoted with slash or vertical bars. e.g.,

An alternative to the somewhat `flat' representation of filenames as namestrings is the namelist format. Namelists, being lists, have some structure to them and even offer some illusion of file system independence if used correctly.

Simple namelist formats look like:

For example:

It is also possible to omit components from a namelist. This can be done by the user in either of two ways. Either he can place *'s in place of the omitted components or he can actually omit the relevant part of the list (if it is the tail of the list). If the system creates a partially specified namelist, it will never omit parts of the structure, but rather will always use the format with *'s in the omitted fields. Lisp tries to be smart about omitted directories and devices. Hence, if it sees only one item in the (dir dev) spec, it will assume it is a directory unless it knows it to be a device. If this ambiguity disturbs you, use a * in the field you wish to not specify. Here are some typical examples of partial filespecs and their meanings under common file systems. Note that the same filespec in namelist format can often have a useful meaning on either of the two systems:

There is also an old-style namelist format which is for compatibility with Old-I/O. Its use is not recommended. It has the form:

Opens filespec for input and causes its contents to be be executed.

If the file is an ASCII file, it reads and evaluates successive forms in the file (without printing their return values), returning T when done. If the file is a FASL file (compiled code), it is fasloaded and a fixnum is returned (see FASLOAD).

By convention, if (SSTATUS FEATURE NOLDMSG) has been done, files do not type out the normal “;Loading ...” message (see HERALD).

Note: In versions of lisp before 1914, if an error occurs during the load, the file object will not get closed until the garbage-collection which follows.

Loads a FASL file into the lisp environment. namelist is not evaluated.

The return value is a fixnum. It is poor style to rely on the meaning of the return value, though it happens to be the new value of the variable BPORG.

Note: FASLOAD'ing within a FASLOAD works pretty well. Naturally, you can only FASLOAD between functions; “Evaluated constants” (see SQUID) within a function may not do FASLOAD's. If you don't understand this last item, don't worry -- it's not the sort of thing you're likely to do by accident.

[PDP-10 Only] The variable FASLOAD is bound to a list of property names which fasload should warn about if something in the current fasl file is clobbering an already existing copy of. Setting (or binding) FASLOAD to NIL will muffle redefinition warnings. Alternatively, one can be more paranoid and set it to more conservative values, such as (EXPR SUBR LSUBR FEXPR FSUBR ARRAY MACRO), which will warn about redefining any of these properties on a symbol during a FASLOAD.

INCLUDE is a special form which takes a file name. If this form is evaluated in the course of UREAD'ing or LOAD'ing a file, the effect is to include the text of the inserted file in place of the include. The compiler will also respect INCLUDE's at toplevel.

This is just like INCLUDE, but it evaluates the filename first. This is so that site-dependent or filesystem-dependent tests can be placed in the argument (see (STATUS OPSYS), etc.)

Merges filespec with the current file defaults, changing the file defaults to the merged value, which is also returned.

Similar to (SETQ DEFAULTF (MERGEF filespec DEFAULTF)).

[PDP-10 Only] This variable contains the default filename to be used by Lisp file-I/O operations when an incomplete file descriptor is named in a primitive file-I/O interaction. It is usually not assigned directly; more commonly it is manipulated via the DEFAULTF function.

It is sometimes useful to bind DEFAULTF to itself to keep the file defaults from changing during the execution of some expression. For example, if it is known that F is a function that changes the file defaults (i.e., assigns DEFAULTF), such changes can be suppressed when undesirable by binding DEFAULTF around the call to F as in:

Returns the truename of the file (tracing any file links, converting > or .0 files to their actual version number, reading through any links and making any specified ITS file translations.) The result is in namelist format. (On ITS, it is the name returned by the .RCHST system call on the file's channel.)

MERGEF is used for applying defaults to file specifiers, which may be namelists or namestrings. Returns a namelist obtained by selecting components from filespec₁ and filespec₂, which are converted to namelists. If any component of filespec₁ is *, the corresponding component of filespec₂ is selected in its place. It is an error if filespec₂ is not that long (*** is it? ***). When a component of filespec₁ is not *, it is selected and the corresponding component of filespec₂ is skipped. If either filespec₁ or filespec₂ ends with a dotted atom other than a *, this atom is added to the end of the namelist if it's not already there. (*** What is this about? ***) If filespec₁ ends with a dotted *, the rest of filespec₂ is copied over.

(MERGEF x NIL) strips off the last component of x.

*** Note: This documentation is very old and I can't imagine that it's even remotely correct any more. Take it all with a grain of salt and we'll fix the description some day!

Example:

Namelist converts its argument to a namelist. Omitted or * components in the argument produce *'s in the result.

Examples:

Namestring converts its argument from a namelist to a namestring. It is the opposite of namelist.

Examples:

SHORTNAMESTRING is just like NAMESTRING except that there is no mention of directory or device in the resulting string.

Example:

[PDP-10 Only] Argument must be a (not-necessarily-open) SFA or file object. Returns the length of the file object -- if open in ASCII mode, then in characters; if open in FIXNUM mode, then in words.

[PDP-10 Only] Returns T if filename names a FASL file and NIL otherwise. This actually opens the file and checks its format.

[PDP-10 Only] Returns NIL if filename doesn't exist. Returns the truename of filename if it does exist.

[PDP-10 Only] Renames a file. If oldfilename is a file object, the file is closed in the process.

Where filespec specifies a file, deletes that file. The return value is the namelist of the file actually deleted, i.e. filespec MERGEF'd over the defaults.

Examples:

There are several functions which allow users to do actions (using a star convention) to all files which match a partially specified filename.

The namelists used by ALLFILES, MAPALLFILES, DIRECTORY, and MAPDIRECTORY may have omitted or starred components which have the following meaning:

As a safety feature, the namestring "*" is not permitted.

This is a powerful and necessary facility, but please use *extreme* care when mapping any kind of operation over files using a star convention. Tellers of Maclisp lore are quick to relate the tale of a poor Maclisp user who used an overly general pattern match on a system with very little built-in protection and deleted a major portion of the file system before he realized what was happening...

The argument, spec, is a list of partially specified namelists. The return value is a list of namelists which are precise (i.e. do not contain any stars or dotted parts) specifications of all files in the file system which match the given spec. Whatever search rules are customary in the particular operating system are used. There is no guarantee as to the order of the filenames returned. To obtain an ordering, use SORT or SORTCAR on the result.

ALLFILES with a precise namelist as an argument can be used as a predicate to determine whether or not a file exists (or you could use PROBEF).

[ITS and TOPS-10 Only] This just applies fn to each file matched by namelists as in

but it saves consing the intermediate list which would be the return value from ALLFILES.

[ITS and TOPS-10 Only] If props is not supplied, this is like (ALLFILES namelists) but instead of namelists, it returns a list of file descriptors where each descriptor has a namelist in the car and a property list in the cdr. Typical properties are:

If props is supplied, only those properties are mentioned in the property list. As a special case, if LINK does not appear in the properties, no info about files which are links will be supplied at all.

[ITS and TOPS-10 Only] This just like doing

but, as with MAPALLFILES, it saves consing the intermediate list which would be the return value from DIRECTORY.