[Indigo]<Mesa>Doc>System>Directory.bravo!1

Page Numbers: Yes First Page: 9 X: 527 Y: 10.5"
Margins: Binding: 13
Odd Heading: Not-on-first-page

The Mesa directory package provides a number of procedures to manipulate the standard Alto directory (SysDir) or any file which follows the format of the Alto directory (see DirectoryDefs). These routines also support sub-directories. This section depends heavily on the section on Files, and that section should be read before this. (See the Alto Operating System Reference Manual for file structure details.)

Most of the operations described below come in pairs. The operation containing the word Directory operates on the standard Alto directory (SysDir). The other operation of the pair operates on the directory specified by the disk stream handle dir. (Note that a NIL DiskHandle does not imply the system directory).

The simplest operation provided is to enumerate all of the file entries in the directory:

EnumerateDirectory: PROCEDURE [proc: PROCEDURE [POINTER TO FP, STRING]
RETURNS [BOOLEAN]];

Enumerate: PROCEDURE [
dir: DiskHandle, proc: PROCEDURE [POINTER TO FP, STRING] RETURNS [BOOLEAN]];

Calls proc once for each filename in the directory, passing it pointers to the file’s FP and name. Processing terminates when proc returns TRUE or the end of the directory is reached.

Fine point: these parameters are local to the enumeration procedure and must be copied if they are to be retained after the enumeration completes.

A faster way to read a directory is to use the StreamScan facilities described in the Streams section of this document.

EnumerateEntries: PROCEDURE [
dir: DiskHandle,
proc: PROCEDURE [CARDINAL, StreamScan.Handle, DEptr] RETURNS [BOOLEAN],
inspectFree: POINTER TO READONLY BOOLEAN,
lengthFilter: CARDINAL ← 0] RETURNS [index: CARDINAL];

The procedure proc is called for each directory entry; free entries are passed only if inspectFree↑ is TRUE. If the lengthFilter is non-zero, only entries with a filename length equal to lengthFilter characters will be passed to proc.

The following procedures may be of use to programmers implementing features beyond those provided by NewFile and DestroyFile.

DirectoryLookup: PROCEDURE [fp: POINTER TO FP, name: STRING, create: BOOLEAN]
RETURNS [old: BOOLEAN];

Lookup: PROCEDURE [
dir: DiskHandle, fp: POINTER TO FP, name: STRING, create: BOOLEAN]
RETURNS [old: BOOLEAN];

Looks up name in the directory. If an entry already exists, its file pointer is copied into fp and TRUE is returned, otherwise FALSE is returned. In addition, if create is TRUE, the file will be created (with one empty data page), and the new file pointer will be copied into fp.

Raised if one tries to insert a directory entry for name, using one of several procedures in the interface, and the name is too long or contains invalid characters.

DirectoryLookupFP: PROCEDURE [fp: POINTER TO FP, name: STRING]
RETURNS [old: BOOLEAN];

LookupFP: PROCEDURE [dir: DiskHandle, fp: POINTER TO FP, name: STRING]
RETURNS [old: BOOLEAN];

Similar to DirectoryLookup, except that the directory is searched for a matching FP. It returns TRUE if the file pointer was found. In addition it will supply the filename if name is not NIL.

DirectoryPurge: PROCEDURE [fp: POINTER TO FP, name: STRING]
RETURNS [found: BOOLEAN];

Purge: PROCEDURE [dir: DiskHandle, fp: POINTER TO FP, name: STRING]
RETURNS [found: BOOLEAN];

Removes the entry corresponding to name from the directory (it does not disturb the file pages pointed to by the FP, however). If the file is found, its file pointer is copied into fp and TRUE is returned, otherwise FALSE is returned.

Similar to DirectoryPurge, except that the directory is searched for a matching FP. It returns TRUE if the file pointer was found, deleting the entry in the process.

Insert: PROCEDURE [
dir: DiskHandle, fp: POINTER TO AltoFileDefs.FP, name: STRING]
RETURNS [old: BOOLEAN];

Inserts a directory entry with the specified name and fp; unlike Lookup, it does not create a file. If an entry with the same name is encounter it returns TRUE and the entry is unchanged, otherwise it returns FALSE.

ParseFileName: PROCEDURE [
name, filename: STRING, dirAccess: SegmentDefs.AccessOptions]
RETURNS [StreamDefs.DiskHandle];

Strips the leading directory information from name, puts the result in filename (appending a period if necessary), and returns a stream (with access dirAccess) open on the directory in which the file should be looked up.

The following procedures set and return the directory used for looking up files which do not specify a directory name (initially set to "<SysDir."). The error BadDirectory is raised if the file is not a valid directory.