[eris]<Lisp>Carol>LIBRARY>SINGLEFILEINDEX.DOC!1

Stored on: {Phylum}<Lisp>Library>SINGLEFILEINDEX.DOC
Program: {Phylum}<Lisp>Library>SINGLEFILEINDEX.DCOM
Documentation last revised: February 27, 1984

SINGLEFILEINDEX

Christopher Tong and Jon L. White

SINGLEFILEINDEX is a Lisp Library package for generating indexed listings for files. Its features include:

1. items that are indexed by type (e.g. FNS, VARS, etc.) and the page number on which their definitions appear in the listing;

2. the ability to define the types to be indexed, as well as the means for locating definitions of a particular type;

3. in INTERLISP-D, the listing is created in a background process;

4. the creation of an multi-type index for multiple files.

1. Creating indexed file listings.

SINGLEFILEINDEX lists a file, and producing indices for different types of items that appear on that file. These types are usually file package types, but they needn’t be.1 A default set of types is provided by the value of the variable, DEFAULTINDEXEDTYPESLST:

((BITMAP RPAQ TestForBitmap)
(CLASS DEFCLASS)
(INSTANCE DEFINST TestForInstance)
(MACRO PUTPROPS TestForMacro)
(METHOD METH TestForMethod)
(RECORD(RECORD TYPERECORD ASSOCRECORD PROPRECORD ARRAYRECORD
ATOMRECORD HASHLINK ARRAYBLOCK ACCESSFNS DATATYPE
BLOCKRECORD))
(VAR (RPAQ ADDTOVAR)))

The user can specify the types he wants to index with the variable, INDEXEDTYPESLIST (initially NIL). If the value of this variable is NIL, DEFAULINDEXEDTTYPESLST is used instead. Functions are always indexed, and should not be included in INDEXEDTYPESLIST. See section 2 for more on specifying types.

The two functions responsible for creating indexed listings are SINGLEFILEINDEX and MERGEDFILEINDEX.

(SINGLEFILEINDEX FILE OUTPUTFILE MERGEDINDEXFLG)[Function]

FILE is the lisp source file. OUTPUTFILE is the destination file. If OUTPUTFILE=NIL, then the value of PRINTER (initially LPT:) is used. MERGEDINDEXFLG=T means a single, alpabetically sorted index will be created for all the types (instead of a several type-specific indices). The value of FILELINELENGTH determines the position of the index numbers, as well as the placement of the columns. The value of LINESPERPAGE (initially 65 on D machines, 58 otherwise) determines the number of lines per page.

SINGLEFILEINDEX first prints the file, with the filename and page number at the top of every page, as well as the name of any definition whose listing has been interrupted by the page break. After the file has been printed, the subsequent pages list the index or indices (depending on the value of MERGEDINDEXFLG). The first page provides the filename, time of creation, and time of listing. If MERGEDINDEXFLG=T, the order in which the indices appear is determined by the order of the types in INDEXEDTYPESLIST. If there are no items of a particular type on the file, no index is generated.1 The index for items of a particular type provides the names of those items, as well as the page number on which their definition begins. The index is sorted by item name.

When the SINGLEFILEINDEX package is first loaded, it redefines LISTFILES1 (see the INTERLISP manual) so that all files listed by LISTFILES will be listed using the function SINGLEFILEINDEX.2 The file being indexed needn’t be loaded, or even noticed (in the file package sense).

(MERGEDFILEINDEX FILES)[Function]

MERGEDFILEINDEX creates a single index for a set of files, FILES. The index contains the name of a file item, its type, and the file on which it appears. The index is alphabetically sorted by item name. If the same item of a particular type appears on several files, a separate index entry will be generated for each occurence.

2. Specifying types

For the purpose of this package, a type is defined as a triple containing:

the name of the type (e.g. BITMAP);
a candidate-generating atom or atoms (e.g. RPAQ);
a function for testing whether a candidate is really an item of this type.

The type name must be recognizable by the file package if it is a file package type. The candidate-generating atom must follow a "(" or "[" at the beginning of a line on the file. If a list of atoms is provided (e.g. for RECORDs), a match against any one of them will produce a candidate line. (Note: the candidate-generating atom will be used for partial matching; thus RPAQ will match RPAQ, RPAQQ, and RPAQ?.) The test function has arguments: (string typeName), and returns either NIL (i.e. the candidate is not legitimate) or the name of the item. SINGLEFILEINDEX reads the file, one line at a time, and compares each line against the candidate-generating atom for each type; if a candidate line is found, the test function is applied with arguments: (string typeName), where string is the substring of the current line that begins with the candidate-generating atom.
For example, given the file line:
(RPAQ Foo NIL)
the RPAQ following an initial "(" makes this line a candidate for the beginning of a bitmap definition. However, when TestForBitmap is applied to "RPAQ Foo NIL)<CR>" it rejects this candidate because the second expression after the RPAQ is not (READBITMAP).
If no test function is provided, the function TestForType is used, which simply checks for a litatom after the candidate-generating atom; if it finds a litatom, it assumes it is the name of the item and returns it.
Note: When the type is a legitimate file package type, it is often useful to screen candidates of a particular type against the list of all items of that type as determined by scanning the FILECOMS list. For this purpose, the variable, typeNames, is computed, so that it can be used freely by a test function. typeNames is a list whose members have the form:
(typeName itemList)
itemList is computed using the FILECOMS list.

Note 1: Both SINGLEFILEINDEX and MERGEDFILEINDEX run as background processes in INTERLISP-D.

Note 2: The files being indexed and/or listed needn’t be loaded.

Note 3: The current version of the SINGLEFILEINDEX package replaces an older version which only indexed functions, used relative labels instead of absolute page numbers, and printed the function index before listing the file. Setting RELATIVEINDEXFLG to T will restore this behavior, if so desired (e.g. if you are printing on fanfold paper rather than cut sheets, you may want the index to appear before the file listing). If RELATIVEINDEXFLG is NIL (the current default), indexing will be as described above, and the indices will be printed after the file is listed. If, for some reason, both kinds of indexing are desired, give RELATIVEINDEXFLG the value (QUOTE BOTH).

Note 4: The SINGLEFILEINDEX package uses the following variables:

FILELINELENGTH to do the right-justification and columnating;
PRINTER (default value is LPT:) as the file to open to print the indexed version of the file;
LINESPERPAGE (initially 65 on D machines, 58 otherwise) as the number of lines on the printer.

The default values are only used if the variables were not bound at the time SINGLEFILEINDEX was loaded.

1If the type is a file package type, and there are no items of that type on the file (according to the FILECOMS list), then the file is never searched for items of that type.

2with OUTPUTFILE and MERGEDINDEXFLG set to NIL.