A file array, or file object, is a special kind of array which can be created by an OPEN call, and which may be passed to most I/O functions to indicate a stream to which or from which I/O is to be done.

[PDP-10 Only] An sfa is a “software file array” --- and generalizes the notion of a file. An sfa is created with SFA-CREATE, has local storage accessible through SFA-STORE and SFA-GET and is accepted in most places that a file object is desired.

Many I/O functions which allow the specification of an explicit file argument will accept NIL to mean “use the file that would have been used by default if no explicit argument had been specified.” It is not a file itself; it is specially understood by these functions. For example, because of the ordering of arguments, it may be desirable to supply only a second argument to READ, but not a first. In such a case, (READ NIL eofval) will have a functionally equivalent effect.

Because NIL is not a real file, it is not a wise idea to pass it to an arbitrary user function which accepts a file argument since that user function may call some I/O function (e.g., FORMAT) which does not treat NIL in this way.

The symbol T is generally accepted by all primitive I/O functions to mean “use the current value of TYI/TYO as appropriate.” Like NIL, T is not a true file.

The intended use of T was for rare cases where a list of files (e.g., OUTFILES, MSGFILES, or ECHOFILES) might be consed which should include TYO or TYI, but which, if a new value for TYO or TYI became available, would want to acquire that value. If T is used in such lists, Lisp will use the binding of TYI or TYO which is available at the time the I/O request is done.

Some functions (e.g., LISTEN) may treat T slightly differently than they would the value of TYO or TYI.

The effect of the variable ^W upon tty output affects output only to T and not output to the file object held by TYO.

In New-I/O, files are specified by means of namestrings and namelists as documented in this manual.

There is furthermore a compatibility feature which allows Old-I/O 4-lists to be used interchangeably with New-I/O namelists. If the car of a putative namelist is atomic, then it is assumed to be an Old-I/O 4-list.

Finally, New-I/O on the PDP-10 knows most standard device names; if it sees a name where a device belongs, and it is not one of the standard device names, and no directory name was supplied, then the name in the device position is taken to be a directory. For example, ((FOO) BAR BAZ) means the same as ((* FOO) BAR BAZ), while ((DSK) BAR BAZ) means the same as ((DSK *) BAR BAZ).

File naming is necessarily operating system dependent, and as such some variation exists between installations. Some of the forms which this section claims are valid may not work for all implementations.

The following are equivalent file names:

A readtable is a special array which can be manipulated using the operators STATUS, SSTATUS, and SETSYNTAX. Multiple readtable-arrays may be constructed as copies of the original readtable (see *ARRAY, ARRAY) and modified via these functions.

The symbol READTABLE has an initial ARRAY property which is the value of the default readtable. The object on this property is not used by Lisp directly -- rather, the current binding of the symbol is used. This ARRAY property is primarily useful if the value of READTABLE has become messed up so that one can do

(SETQ READTABLE (GET 'READTABLE 'ARRAY))

The position within the file of the character currently being accessed. (Not necessarily meaningful for all kinds of files.)

Calls to the input functions READ, READCH, READLINE, and TYI specify an argument called the “eofval.” If this argument is omitted NIL is assumed. If the end of the input file is reached during the execution of the function, the eofval argument is used by the following procedure:

If an attempt is made to read characters from a file which has no more characters, an end of file condition is signalled. On a tty file object, end of file is defined by an overrubout and can occur only during READ or READLINE. An attempt to TYI a rubout will simply return #\RUBOUT.

If an end of file condition is signalled in the middle of an object, a FAIL-ACT error occurs to prevent half of an object being read from one file and the other half being looked for in some other file. The argument passed to the FAIL-ACT handler is the list (READ-EOF). If the handler returns an atom (such as NIL), the READ or READLINE errs out; but if it returns a list (such as its argument), reading of the object continues from the new default input source as if the FAIL-ACT had not occurred.

Each file object can have an end-of-file function, called an eoffn, which is responsible for handling the end of file condition. (See EOFFN.)

When an end of file occurs while input is being taken from this file, the eoffn (if not NIL) is called to handle the condition, receiving the input file and eofval as arguments. If there is no associated eoffn, then the following default action is taken:

If an eofval was supplied on the call to the input function, it is immediately returned. The input file is not closed.

If eofval on the call to READ or READLINE was not supplied, then the input file is closed and read continues taking characters from a new input file popped off the input stack. If the input stack (see INPUSH and INSTACK) is empty, (SETQ ^Q NIL) is done and reading continues from the terminal.

A function associated with a file and intended to be called when an attempt is made to read past the end of an input file.

The eoffn should be a function of two arguments. The first argument, file, is the input file object upon which the end of file condition was seen. The second argument, eofval, is the end of file value specified by the user; this argument defaults to NIL if no explicit value was given.

When the eoffn is run, the offending file will still be open. The eoffn may choose to close it explicitly, reposition the file pointer (see FILEPOS), tell Lisp what to do with the file by its return value, or even throw out of the condition to some catch which will deal with the error.

Certain return values of an eoffn are treated specially. If the eoffn returns NIL, the file is closed and reading continues from the input source popped off the input stack. If the eoffn returns T, reading continues from whatever input source was made the current default one by the eoffn. If the eoffn returns something other than T or NIL, then read immediately returns whatever the eoffn returned, and the file is not closed unless the eoffn closes it.

If the eoffn for a file is NIL, the file may be said not to have an eoffn (see EOFFN).

Contains the default file object to be used by input functions when no file object is specified, or when the file object given is T.

The value of INFILE is a file object which is the default input source if ^Q is not NIL.

If infile is T or if ^Q is NIL, the value of TYI is the default input file.

The value of INSTACK is a list of pushed-down values of INFILE. It is managed by the function INPUSH.

If the value of ^Q is not NIL, the default input source is the value of the symbol INFILE. If ^Q is NIL, the default input source is T, i.e. the value of the variable TYI.

The default for the Control-Q read character splicing macro is to set this variable to T.

The input radix to be used by the lisp reader for reading numbers.

Interestingly enough, 1 is a valid input base.

IBASE may also be the symbol ROMAN, meaning to use roman numeral input.

See also: BASE, *NOPOINT

Given that one often has to establish the input base by typing a number, there's somewhat of a chicken/egg problem about getting a known base to type the input in. For example, since Lisp starts in octal, doing:

doesn't change the input base. That's an octal ten you've typed in that case. The normal recommendation is to use a trailing decimal point, which forces decimal treatment of the number you type:

Others avoid double digits in an uncertain input base, while getting a foothold from an uncertain state, by using this idiom:

The value of the symbol READTABLE at any given time is the readtable which will be used by reader related operations such as READ, READLIST, STATUS, etc.

[PDP-10 Only] The value of this variable is an alist used by the tty prescan. It must be of the form

((chara1 . chara2) (charb1 . charb2) ...)

where the car of each form in the list is a fixnum which is a char which is stringlike in nature (reads all characters up to the next occurance of some other chars regardless of the chars in between). Initially, |...|, "..." and ;...<return> are defined in this way.

Contains the default file object to be used by output functions when no file object is specified, or when the file object given is T.

The value of outfiles is a list of file objects which are output destinations if ^R is not NIL. Elements of the list OUTFILES may be either file objects, created by OPEN, or NIL meaning output to the terminal. Note that output goes to the terminal anyway if ^W is NIL, so it is possible to get double characters this way.

[PDP-10 Only] While most default output goes to the files specified in OUTFILES, system-generated messages like GC messages, error messages, “;BKPT ...”, “;Loading ...”, etc. go to MSGFILES instead.

While OUTFILES is controlled by the switch ^R, there is no switch equivalent to ^R for MSGFILES. MSGFILES must always contain a valid list of files for these messages to be displayed to.

If MSGFILES is ever found to have a bad value, Lisp should generate an IO-LOSSAGE error, but may end up just dying horribly to the monitor. Bad values for MSGFILES are to be avoided at all costs.

On Multics, these messages always go to the terminal.

[PDP-10 Only] A variable which, if not NIL, should be a list of output files. These output files receive every character seen as input by TYI (and functions which use TYI, such as READ). If a file is a member of all of the lists held by ECHOFILES, OUTFILES and MSGFILES, with appropriate settings of the ^R and ^W variables (which affect output to OUTFILES and to the terminal, but not to ECHOFILES and MSGFILES), it will be a “dribble file”, recording both input and output. Note that the function which pre-scans tty input and performs rubout processing lambda-binds echofiles to NIL, so you won't see rubbed-out characters.

If the value of ^W is not NIL, the default output destinations do not include the terminal unless ^R is on and NIL is a member of the OUTFILES list.

Specifically, this means that while ^W is set to a value other than NIL, output by Lisp functions which would have gone to T is not displayed. By implication, this affects calls to TERPRI, TYO, PRINC, PRIN1, etc. which specify no file object (as long as T is a member of outfiles). It also affects error message typeout if T is a member of MSGFILES.

If, instead of T, the actual value of TYO is being output to, the ^W flag has no effect.

The default handler for the Control-W tty interrupt will set variable to T.

The default handler for the Control-V tty interrupt will set variable to NIL.

If the value of ^R is not NIL, the default output destinations include the files in the list which is the value of the symbol OUTFILES.

If the value of ^R is NIL, the default output destination is T, i.e. the current value of TYO.

The default handler for the Control-R tty interrupt will set variable to T.

The default handler for the Control-T tty interrupt will set variable to NIL.

This variable controls the output radix of fixnums and bignums by the default printer. 1 is not a valid output base. BASE may also be the symbol ROMAN, meaning to use roman numeral output where possible.

The setting of BASE does not affect the output of flonums, which are always output in base-10 with a decimal point between the integer and fraction fields.

See also: IBASE, *NOPOINT

If you're trying to check the output base to make sure it's right, don't just type the variable BASE. Even when *NOPOINT is set to T, a trailing dot will appear only in base 10. In all other bases (except ROMAN), the number 10 will appear because every base is base 10 it its own mind's eye. It's often much better to ask what one less than the base is.

If this variable is set to NIL, a decimal point is printed after fixed point numbers (fixnums and bignums) that are output when BASE is set to 10 (decimal). If *NOPOINT is T or BASE is not 10 (decimal), then no decimal point is printed after such numbers on output.

However, in bases above 10, *NOPOINT also controls whether the printer shows a leading + when showing numbers.

The setting of *NOPOINT does not affect the output of flonums, which are always output in base-10 with a decimal point between the integer and fraction fields.

See also: BASE, IBASE

If NIL, Lisp attempts to print all levels of lists, hunks, and other structures whose elements would normally be printed in nested fashion. If not NIL, it should be a fixnum which is the maximum length of a list to print. “...” is printed if more elements have been omitted.

PRINLEVEL is like PRINLENGTH but controls depth of display. “#” is displayed if something would have been printed that involves increasing the depth of printer recursion.

If TERPRI is NIL, Maclisp will automatically type a carriage return in the middle of an output line at a point where output would otherwise run past the end of the line.

When using Lisp READ on files created while TERPRI was NIL, the READTABLE should be adjusted so that carriage return is treated as a throwaway character, rather than as a break character. Otherwise, symbols, numbers, etc. which were broken by a carriage return will not be read back in correctly.

This used to default to NIL, but a number of cases exist in common practice where the autoterpri was a problem. Additionally, most users seemed to feel that carriage return should be a token break, so the default was changed to its current setting.

Predicate returns T if q is a file object, and NIL otherwise.

Examples:

Archaic. The value of the symbol TTY is initially set to the result of a (STATUS TTYTYP T), which returns a number describing the type of terminal being used.

Reads or sets the line length of file. With one argument, reads the line length. With two arguments, sets the line length to val, returning the old line length.

This variable is obsolete. In Old-I/O Lisp, it contained the number of characters per line on an output file. It is initially unbound in New-I/O Lisp, although GRINDEF and related functions will use its value if it is bound. The proper way to get this information is by calling the LINEL function.

Reads or sets the page length of file.

Reads or sets the line number of file.

Reads or sets the page number of file.

[PDP-10 Only] If val is true, sets the variable *NOPOINT to T; otherwise, sets it to NIL.

fileobject is a file object open for input, returns the current character position within the file as a fixnum. The beginning of the file is 0. If where is supplied and is a non-negative fixnum, it resets the character position of the file to position specified by n. It is an error if this position does not lie within the file or if the file is not randomly accessible. The new position is returned.

Reads the horizontal character position on the current line in fileobj, which must be a file object, sfa, or T.

If supplied, the character position counter is updated to be value. This will not move the cursor or file pointer in any way, in spite of what it sounds like. Lisp keeps its own counter of where on the line in each output stream it is, blindly incrementing what is there as it reads characters, or resetting it to 0 on a newline. Giving CHARPOS a second argument will update this counter used by Lisp so that future calls to (CHARPOS fileobj) can be affected.

The two-arg version is useful when output has occurred which Lisp hasn't kept track of (e.g., calls to +TYO) so that its sense of when carriage returns and/or other display features would be appropriate can be put back into perspective.

The cursorpos function is used to read and manipulate cursor on a display terminal.

If q₁ and q₂ are absent, a dotted pair of the form (line . column) is returned, where line is the line number (0-indexed from the top) and column is the column position (0-indexed from the left).

If q₁ is NIL or a fixnum, then q₂ must also be supplied. These two arguments will specify new coordinates to which the cursor should be moved. If either of these coordinates is NIL, the position along that axis will not be changed. Hence, (CURSORPOS NIL i) will change the horizontal position only and (CURSORPOS i NIL) will change the vertical position only. (The effect of (CURSORPOS NIL NIL) is, as might be suspected, not very spectacular.)

If q₁ is a symbol other than T or NIL, it is assumed to be one of a set of codes for common screen operations (see table below). Some symbols (H, I, and V) will require a q₂ argument to be supplied.

The last argument to CURSORPOS may be a tty file object upon which the positioning is to be done. Since (CURSORPOS T) might mean either go to the top of the default tty or return the cursor position on T, the following convention is used: “If the last argument can be taken to be a file, it will be.” Hence, (CURSORPOS T) means get the coordinates of T; to go to the top of the screen, use (CURSORPOS 'TOP) or (CURSORPOS 'T T).

If the terminal being used does not have full display terminal support, NIL is returned from cursor movement requests which cannot be simulated. Simple CURSORPOS commands, such as (CURSORPOS 'A) may still be possible when others like (CURSORPOS 'U) are not.

CURSORPOS works only under operating systems which offer display terminal support (e.g., ITS or Tops-20 with VTS). On other systems, it simply returns NIL.

The following symbolic arguments to CURSORPOS are allowed:

Opens the file specified by filespec, which may be a namelist, namestring, sfa, or a file object. The open is done with the given modes and a file object is returned. If the open fails, an IO-LOSSAGE error will result.

If filespec is a file object or sfa, it will be re-opened and the same object returned. If it is just a filename, a new file array will be created and an open done on that file array. Initial creation of an sfa is done by SFA-CREATE, not by OPEN.

If filespec is omitted or incompletely specified (contains *'d or omitted fields), it is merged with the Lisp default filenames (see DEFAULTF) to fill in the missing fields.

For newly created files, modes defaults to NIL while for old files, the modes used in the previous open are re-used. A symbol may be used in place of a 1-length list containing just that symbol (e.g., 'OUT instead of '(OUT)). These specifications determine a large number of attributes for opening the file. For each attribute, there are two or more mutually exclusive values which may be specified as shown below.

Direction. IN or READ means open for input, the default. OUT or PRINT means open for output. APPEND is like OUT, but opens an existing file to append to it (rather than clobber it, as OUT would do). It is an error to open a non-existent file in APPEND mode.

Data Mode. ASCII mode, the default, specifies that the file is to be read as a stream of ascii characters. System-dependent transformations may occur, such as supplying a linefeed after cr or being careful with output of Control-P or use of Multics escape conventions. FIXNUM mode specifies that the file is to be read as a stream of machine words (fixnums). This is for dealing with files thought of as “binary” rather than “character.” You'll need the functions IN and OUT to do I/O to such a file. IMAGE mode specifies that the file is a stream of ascii characters but that Lisp should do `raw' I/O rather than doing any system dependent transformations as it would for ASCII mode. Normal I/O operations work on these files; IN and OUT aren't used here.

Device Type. DSK, the default, specifies the normal kind of file --- a standard disk file. TTY specifies a console file. Only files with this option set have interrupt character handling associated with them, for example. Buffering Mode. BLOCK specifies buffered output. SINGLE specifies unbuffered. Files with the TTY option default to SINGLE on ITS; other files default to BLOCK. Echo Mode. The ECHO option is optional and used only in the rare event that the file object is to be opened in the tty echo area, rather than the main area. Additional support is required to make this option useful.

CLA Mode. The CLA option is an optional ITS-Only option which must be used when opening the CLA: device.

If the options list is invalid in any way, OPEN may either give a WRNG-TYPE-ARG error, or blithely assume a corrected value for an attribute. In general, errors should occur only for truly conflicting specifications, such as IN and OUT. On the other hand, specifying BLOCK mode for a device that the system wants to handle only in character mode may just go ahead and use SINGLE mode.

The argument, fileobj, must a file object or SFA. Closes it and returns T. If it is already closed nothing happens, and NIL is returned. An SFA is closed by asking its handler to do a CLOSE operation. A real file is closed by asking the operating system to close the related I/O channel.

[PDP-10 Only] fileobject must be a closed file object. Changes the filename field in the object so that it may be later re-opened via (OPEN fileobject [modes]) and have it specify the new file since there is no provision in the OPEN command for re-using a file array for a different use.

Causes any input that has been received from file but has not yet been read to be thrown away, if that makes sense for the particular device involved. (Meaningful only on tty input files, but harmless on other kinds of files.)

[PDP-10 Only] Flushes any pending but uncompleted output to file. (Meaningful only on tty output files, but harmless on other kinds of files.)

Causes any buffered output to file to be immediately sent to the actual output device.

An endpagefn is a function which is applied when the end of a page is reached (on an output file). This function reads or, if fun is supplied, sets the handler associated with the given file.

For tty output files on ITS, the ENDPAGEFN is not tripped when the LINENUM exceeds PAGEL. Rather, the operating system **MORE** interrupt is used, which is more accurate for detecting the bottom of the screen. When the tty reaches the bottom of the screen, the endpagefn for the tty is invoked; it receives as argument the file on which the interrupt occurred.

Re-opening a file will reset its associated endpagefn to the default.

(ENDPAGEFN NIL [fn]) reads or sets the default endpagefn for newly created files.

An eoffn is a function which is called when the end of an file is reached. This function reads or, if fn is supplied, sets the handler associated with the given file.

On the terminal, over-rubout on certain input routines may run the eoffn.

Re-opening a file will reset its associated endpagefn to the default.

(EOFFN NIL [fn]) reads or sets the default eoffn for newly created files.

FORMAT is used to produce formatted output. It outputs the characters of formatstring literally, except that a tilde (“~”) introduces a formatting directive. The character after a tilde, possibly preceded by prefix parameters and/or modifiers, specifies what kind of formatting is desired. Most directives use one or more elements of args to create their output; the typical directive puts the next element of args into the output, formatted in some special way.

The formatstring can also be a list of strings and lists, which is processed from left to right. Strings are interpreted as in the simple case. Lists are taken as extended directives; the first element is the directive letter, and the remaining elements are the numeric parameters to the directive. If the car of a list is not a recognized directive, the list is simply evaluated as a form; anything it prints to the default output streams will appear in the result of format.

If stream is a file object or sfa, output will be directed there. The symbol T is accepted to mean output to TYO; NIL means output to a string which is to be returned by FORMAT, rather than printed.

A directive consists of a tilde, optional prefix parameters separated by commas, optional colon (“:”) and atsign (“@”) modifiers, and a single character indicating the particular operation to be performed. Upper and lowercase dispatch characters are treated identically. Typical directives may look like:

Sometimes a prefix parameter is used to specify a character code, usually for padding. The notation "'char" will substitute for a character's ASCII code in a parameter specification. For example, "~5,'0d" is equivalent to "~5,48d".

It may also be useful to use an element of args as a parameter. In such a case, the letter “V” means to do just that. Note that this means there is no ~V format operation. Also, a sharpsign (“#”) may be used in place of a parameter to signify the number of args remaining to be processed.

To see a list of possible FORMAT operations, see the Format Op Index.

Examples:

~A outputs its arg, any Lisp object, without slashification, a la PRINC.

~:A outputs "()" if arg is null, else does the same as ~A would do. This is useful in Lisps where NIL prints as "NIL" for printing something which is always supposed to be a list.

~nA inserts spaces on the right, if necessary, to make the column width at least n.

~n@A is like ~nA execpt that the spaces are inserted on the left rather than the right.

~mincol,colinc,minpad,padcharA is the full form of ~A, which allows elaborate control of the padding. The string is padded on the right with at least minpad copies of padchar; padding characters are then inserted colinc characters at a time until the total width is at least mincol. The defaults are 0 for mincol and minpad, 1 for colinc, and space for padchar.

This is just like ~A, but arg is printed with slashification, a la PRIN1 instead of PRINC.

~P outputs "s" if arg is not 1 (i.e., if arg represents a plural number of something). If arg is 1, outputs nothing.

A ":" modifier says to use the previous arg instead of the current one (i.e., it's like "~:*~P").

A "@" modifier says to print "y" if the arg is 1, and "ies" if the arg is not 1.

~D outputs its arg, which should be a fixed point number (fixnum or bignum) as a decimal integer. If arg is not a number, it is printed in ~A format and decimal base.

~nD uses a column width of n; spaces are inserted on the left if the number requires less than n columns for its digits and sign. If the number doesn't fit in n columns, additional columns are used as needed.

~n,mD uses m as the pad character instead of space.

The "@" modifier causes the number's sign to be printed always; the default is only to print it if the number is negative.

The ":" modifier causes commas to be printed between groups of three digits; the third numeric parameter may be used to change the character used as the comma.

Thus the most general form of ~D is ~mincol,padchar,commacharD.

This is just like ~D but outputs its arg in octal instead of decimal.

~F outputs its arg, which should be a flonum, in floating point. If arg is not a flonum, it is printed in ~A format. If the magnitude of arg is too large or too small, it is printed in exponential notation.

~nF rounds arg to a width of n digits. The minimum value of n is 2, since a decimal point is always printed.

~E outputs its arg in exponential notation. This is identical to ~F, including the use of a numeric parameter (i.e., ~nE) to specify the number of digits, except that the number is always printed with a trailing exponent, even if it is within a reasonable range.

~rdig,ldig,field,padchar$ prints arg, a flonum, with exactly rdig (default 2) digits after the decimal point, at least ldig (default 1) digits preceding the decimal point, right justified in a field field columns long, padded out with padchar.

The ":" modifier says that we should cause the sign character to be left justified in the field.

The "@" modifier says that we should always output the sign character.

The ldig allows one to specify a portion of the number which does not get zero suppressed; if necessary, more than ldig digits will be used.

With no numeric parameter, ~R behaves as follows: ~R outputs its arg as a cardinal English number (e.g., “four”). ~:R outputs its arg as an ordinal English number (e.g., “fourth”). ~@R outputs its arg as a Roman numeral (e.g., “IV”). ~:@R outputs its arg as an old Roman numeral (e.g., “IIII”).

If there is a numeric parameter, then it is the radix in which to print the number. The modifiers and any remaining parameters are used as for the ~D directive. Indeed, "~D" is the same as "~10R".

The full form here is therefore ~radix,mincol,padchar,commacharR.

~C outputs its argument, which should be a fixnum, string, or symbolic representation of a character.

~:C outputs the name of the character instead of the character itself if the character is a non-printing character. For example, #\ALT is output by ~:C as “Altmode.”

~@C prints out the character in a way that the Lisp reader can understand it using “#/” or “#\” notation.

~:@C just does what ~:C does in Maclisp, but on the Lisp Machine it does something slightly different and for compatibility reasons, you may sometimes prefer one and sometimes the other. In Lisp Machine lisp, it outputs additional information after characters that require “Top,” “Front,” or “Greek” shift key(s) to type saying how the character can be typed in.

~~ outputs a tilde.

~n~ outputs n tildes.

No argument is used.

Tilde immediately followed by a carriage return ignores the carriage return and any whitespace at the beginning of the next line.

With a ":", the return is ignored but the whitespace is left in place.

With an "@", the return is left in place, but the whitespace is ignored.

This directive is typically used when a format control string is too long to fit nicely into one line of the program.

No argument is used.

~% outputs a carriage return a la TERPRI.

~n% outputs n carriage returns.

No argument is used. Simply putting a carriage return in the control string would work, but ~% is usually used because it makes the control string look nicer in the Lisp source program.

~& causes a freshline operation to be done. This means that if the output stream thinks it is already in column 0, nothing happens; otherwise, a TERPRI is output.

~n& does a freshline operation and then outputs n-1 carriage returns.

No argument is used.

~| Outputs a formfeed.

~n| does this n times.

No argument is used.

~X outputs a space.

~nX outputs n spaces.

No argument is used.

~nT spaces over to column n.

~n,mT will output sufficient spaces to move the cursor to column n. If the cursor is already past column n, it will output spaces to move it to column n+m*k, for the smallest integer value k possible. n and m default to 1.

The ":" modifier is not implemented. On the Lisp Machine, this causes m and n to be in units of pixels instead of characters.

When format is creating a string, ~T will assume that the first character in the string is at the left margin.

No argument is used.

~[str0~;str1~;...~;strn~] is a set of alternative control strings. The alternatives (called clauses) are separated by ~; and the construct is terminated by ~].

The argth alternative (0-indexed) is selected.

~n[ uses n instead of an argument. (this is useful only if n is "#").

If arg is out of range no alternative is selected unless ~:; is used to specify a default.

After the selected alternative has been processed, the control string continues after the ~].

~:[ takes two clauses, selecting the first alternative if the arg is NIL, and selects the second alternative otherwise.

~@[ takes exactly one clause. If the argument is NIL, the clause is not processed and the argument is ignored. If however, the argument is not NIL, the clause will be processed without the ~@[ using up the argument; hence, the argument will be available to the first control sequence in the clause.

~:;, if no numeric parameters accompany it, specifies a default case. If the the last ~; used to separate clauses is instead ~:;, then it is performed if no other clause is selected.

~tag0,tag1,tag2,...;clause, where ~; has one or more numeric parameters, specifies tags for the clause which follows the ~;. That clause is processed which has a tag matching the argument.

If numeric parameters are given to a ~:;, they specify a range of tags. For example,

"~a1,a2,b1,b2,...:;"

is tagged not by single values but by ranges of values a1 through a2 (inclusive), b1 through b2 (inclusive), etc. In this case, ~:; with no parameters is still used at the end to denote a default clause.

Examples:

This is an iteration construct.

If the form is ~{str~}, the argument should be a list, which is used as a set of arguments as if for a recursive call to format. The string str is used repeatedly as the control string. Each iteration can absorb as many elements of the list as it likes. If before any iteration step the list is empty, then the iteration is terminated.

A numeric parameter, as in ~n{str~}, specifies that there will be at most n repetitions of processing of str.

A ":" modifier, as in ~:{str~}, specifies that the argument should be a list of sublists. At each repetition step one sublist is used as the set of arguments for processing str; on the next repetition a new sublist is used, whether or not all of the last sublist had been processed.

An "@" modifier, as in ~@{str~} is similar to ~{str~}, but instead of using one argument which is a list, all the remaining arguments are used as the list of arguments for the iteration.

The combined effect of the ":" and "@" modifiers on ~{ is what might be expected: All the remaining arguments are used, and each one must be a list. On each iteration one argument is used as a list of arguments.

If str is null, then an argument is used as str. It must be a symbol or string, and precedes any arguments processed by the iteration. As an example, the following are equivalent:

(LEXPR-FUNCALL #'FORMAT STREAM STRING ARGS)

(FORMAT STREAM "~1{~:}" STRING ARGS)

Terminating the repetition construct with ~:} instead of ~} forces str to be processed at least once even if the initial list of arguments is null (however, it will not override an explicit numeric parameter of zero).

~mincol,colinc,minpad,padchar<text~> justifies text within a field mincol wide. Text may be divided up into segments with ~; --- the spacing is evenly divided between the text segments.

With no modifiers, the leftmost text segment is left justified in the field, and the rightmost text segment right justified; if there is only one, as a special case, it is right justified.

A ":" modifier causes spacing to be introduced before the first text segment.

An "@" modifier causes spacing to be added after the last text segment.

The parameter minpad (default 0) is the minimum number of padchar (default space) padding characters to be output between each segment. If the total width needed to satisfy these constraints is greater than mincol, then mincol is adjusted upwards in increments of colinc (default 1).

If ~^ is used within a ~< construct, then only the clauses which were completely processed are used.

If the first clause of a ~< is terminated with ~:; instead of ~;, then it is used in a special way. All of the clauses are processed (subject to ~^, of course), but the first one is omitted in performing the spacing and padding. When the padded result has been determined, then if it will fit on the current line of output, it is output, and the text for the first clause is discarded. If, however, the padded text will not fit on the current line, then the text for the first clause is output before the padded text. The first clause ought to contain a carriage return. The first clause is always processed, and so any arguments it refers to will be used; the decision is whether to use the resulting piece of text, not whether to process the first clause.

If the ~:; has a numeric parameter n (i.e., ~:n;) then the padded text must fit on the current line with n character positions to spare to avoid outputting the first clause's text. For example, the expression

(FORMAT stream "~%;; ~{~<;; ~1:; ~S~>~^,~}.~%" l)

can be used to print a list l to stream, separated by commas, without breaking items over line boundaries, and beginning each line with ";; ". The argument 1 in ~1:; accounts for the width of the comma which will follow the justified item if it is not the last element in the list, or the period if it is.

If ~:; has a second numeric parameter (i.e., ~m,n:;), then it is used as the width of the line, thus overriding the natural line width of the output stream. To make the preceding example use a line width of 50, one would write

(FORMAT stream "~%;; ~{~<;; ~1,50:; ~S~>~^,~}.~%" l).

Examples:

~; separates clauses in a ~[...~] sequence or ~<...~> sequence.

Terminates a ~[...~] sequence.

Terminates a ~{...~} iteration sequence.

Terminates a ~<...~> sequence.

This is an escape construct.

If there are no more arguments remaining to be processed, then the immediately enclosing ~{ or ~< construct is terminated. In a ~< case, the ~< formatting is performed, but no more segments are processed before doing the justification. The ~^ should appear only at the beginning of a ~< clause, because it aborts the entire clause. It may appear anywhere in a ~{ construct. If there is no such enclosing construct, then the entire formatting operation is terminated.

If a numeric parameter is given, as in ~n^ then termination occurs if the parameter is zero. (Hence ~^ is the same as ~#^.)

If two parameters are given (i.e., ~n1,n2^), termination occurs if n1 and n2 are equal.

If three parameters are given (i.e., ~n1,n2,n3), termination occurs if the second is between the other two in ascending order.

If ~^ is used within a ~:{ construct, then it merely terminates the current iteration step (because in the standard case it tests for remaining arguments of the current step only); the next iteration step commences immediately. To terminate the entire iteration process, use ~:^.

~G goes to the 0th argument. Directives after a ~G will take sequential arguments after the one gone to.

~nG goes to the nth argument (0-indexed).

When within a ~{ construct, the “goto” is relative to the list of arguments being processed by the iteration.

~* ignores and moves past its arg.

~n* ignores the next n arguments.

~:* “un-ignores”; that is, it backs up in the list of arguments so that the argument last processed will be processed again.

~n:* backs up n arguments.

When within a ~{ construct (see below), the ignoring (in either direction) is relative to the list of arguments being processed by the iteration.

An escape to arbitrary user-supplied code. arg is called as a function; its arguments are the numeric-arguments to ~Q, if any. Args can be passed to the function through the ~V construct.

The user function may do output to the file or sfa which is the value of the special variable STANDARD-OUTPUT, a symbol which is bound appropriately by FORMAT prior to the the user function invocation.

The variables COLON-FLAG and ATSIGN-FLAG will be bound to truth values indicating whether the ":" or "@" modifiers, respectively, were supplied.

(FORMAT T "~VQ" FOO BAR) is a contorted way of saying (PROGN (FUNCALL BAR FOO) NIL).

Note the reversal of order, the V is processed before the Q.

~\op\ is reserved for the user to define his own op. op can be any string and is bounded by the backslashes. The user just sets up a property on the symbol op and FORMAT will find and use it.

For information on how to define these, see the next page.

This is like (FORMAT file string . args) except that the file is treated like it would be for normal Maclisp functions like PRIN1. NIL means “the default output destinations,” T means “the terminal,” etc.

This is used to define new FORMAT ops. The name may be a symbol or a fixnum code. If a symbol, it should be in upper case and if multiple obarrays are in use, it should be on the obarray that FORMAT was loaded into. The shape of the varlist determines the type of the operator:

If varlist has the form (paramsvar), then paramsvar will be bound to a list of the parameters while form is executed.

If varlist has the form (paramsvar argvar), then this is an operator of exactly one argument. The paramsvar will be bound to the list of parameters and argvar to the argument.

If varlist has the form (paramsvar . argsvar), then this is an operator of a variable number of arguments. The paramsvar will be bound to the list of parameters and argsvar will be bound to a list of all remaining arguments (or the recursive ~{ arguments). The definition should return the tail of argsvar containing the remaining args so that FORMAT will know how many were used.

All output done by FORMAT ops should be done to the stream which is the value of the variable STANDARD-OUTPUT. Recursive invocations of FORMAT will not work on STANDARD-OUTPUT, however; in that case, use the ?FORMAT function or invoke FORMAT on the stream held by the variable FORMAT instead.

The function may read the variables FORMAT:COLON-FLAG and FORMAT:ATSIGN-FLAG to determine if they received colon or atsign modifiers (NIL means “no”; T means “yes”).

The parameters list is intended for temporary use by the handler only; the list is recycled later. If you need to save the parameters, you should save a copy instead.

If q is a file object open for input or NIL to specify the terminal, pushes the current input source onto the input stack (maintained in the variable INSTACK) and selects q as the default input source in INFILE.

Due to a Lisp bug, SFA arguments to INPUSH aren't currently allowed, but will eventually do the same as file objects.

(INPUSH -i) pops the input stack i times, leaving the last popped file in INFILE.

(INPUSH +i) pushes INFILE onto the input stack i times. The value of inpush is the newly selected input source.

If INPUSH causes INFILE to be set to T, ^Q is set to NIL since the terminal has become the input source.

Reads an S-expression from file in normal Lisp expression format.

During the read INFILE and ^Q are bound to the input file and T, respectively, so that calls to READ, TYI, etc. within a macro-character function execution need not specify an input source to read from.

If only one argument is given, it may be either stream or eofval. If it is a file, an sfa, or NIL, it will be assumed to be stream; otherwise, it will be taken as eofval.

If file is not supplied or is NIL, the default input stream as controlled by the variables ^Q, INFILE, and TYI will be used.

For information on how an end of file condition is handled, see documentation on the EOF and EOFFN concepts.

Reads in a line of text, terminated by the return character, returning an uninterned symbol whose printname is made up of the characters read.

The argument conventions are the same as for READ.

In fact, READLINE will skip past leading linefeeds, so successive calls to READLINE in a file system which terminates lines with both return (octal 15) and linefeed (octal 12) need not worry about dealing with the linefeed. However, if the user plans to intermix READLINE and other types of I/O operations on a given stream, he should be aware that READLINE stops after the return, but before the linefeed if any.

If file is not supplied or is NIL, the default input stream as controlled by the variables ^Q, INFILE, and TYI will be used.

For information on how an end of file condition is handled, see documentation on the EOF and EOFFN concepts.

Inputs one character and returns a fixnum which is the ASCII code for that character. The arguments are the same as for READ, except that eofval is constrained to be a fixnum.

If file is not supplied or is NIL, the default input stream as controlled by the variables ^Q, INFILE, and TYI will be used.

For information on how an end of file condition is handled, see documentation on EOF and EOFFN concepts.

The argument to readlist is a list of characters. The characters may be represented either as numbers (ASCII codes) or as single-character symbols. The characters in the list are assembled into an S-expression as if they had been seen by READ on an input stream. As one might expect, if readmacro characters are used, any calls to READ, READCH, TYI, or TYIPEEK in the readmacro character functions take their input from READLIST's argument rather than from an I/O device or a file. See READ or (STATUS MACRO ...).

Examples:

[PDP-10 Only] Asks the user to type a Y or an N on file, which must be a bidirectional stream and which defaults to QUERY-IO, which if unbound at the time the YESNOP library is loaded will become defined by loading the QUERIO system library. If formatstring (and, optionally, any args) are given, FORMAT is called on these args before prompting for the “(Y or N)” response.

[PDP-10 Only] Asks the user to type “yes” or “no” followed by a carriage return on file. The response is read with READLINE; leading and trailing spaces are stripped before interpreting the response. The file, if supplied, must be a bidirectional stream; it defaults to QUERY-IO, which if unbound at the time the YESNOP library is loaded will become defined by loading the QUERIO system library. If formatstring (and, optionally, any args) are given, FORMAT is called on these args before prompting for the “(Yes or No)” response.

Reads a character from file, returning it as an interned symbol.

If file is not supplied or is NIL, the default input stream as controlled by the variables ^Q, INFILE, and TYI will be used.

For information on how an end of file condition is handled, see documentation on the EOF and EOFFN concepts.

Like TYI except that the character is not removed from the input stream and will be read again the next time Lisp tries to TYI or TYIPEEK from the given fileobj. Thus (= (TYIPEEK) (TYI)) is T.

If the first argument, bits, is NIL, this is the same as not having supplied that argument; TYIPEEK just peeks at the very next character on the input file. NIL is occasionally needed as a placeholder so that the second or third arguments can be supplied.

If file is not supplied or is NIL, the default input stream as controlled by the variables ^Q, INFILE, and TYI will be used.

If the end of the file is reached, tyipeek returns -1, (the pseudo-ascii code for “end of file”). The end of file function is not called.

If the bits argument is supplied, it will have one of several different effects depending on its range.

If bits is a fixnum < 200 octal, TYIPEEK skips over characters of input until one is reached with an ascii code of that fixnum. That character is left on the input stream.

If bits is a fixnum > 1000 octal, TYIPEEK skips over characters of input until one is reached whose syntax bits from the readtable, logically anded with (LSH bits -9.), are nonzero.

If bits is just T, TYIPEEK will skip over characters of input until the beginning of an S-expression is reached. Splicing macro characters, such as “;” comments, are not considered to begin an object. If one is encountered, its associated function is called as usual (so that the text of the comment can be gobbled up or whatever) and TYIPEEK continues scanning characters.

For TTY files, it is sometimes desirable to first ask the terminal if input is available before hanging in TYIPEEK waiting for a character. To do this, see LISTEN.

[PDP-10 Only] Puts a character, char, back on an input stream, file, which must be a real file object. Thus, the result of

is the same as that of (TYIPEEK () TYI).

Repeated calls to UNTYI are allowed. Characters are pushed onto the stream backwards.

Outputs object to file in a form suitable for reading back in with the Lisp READ function, but, unlike PRINT, does not output any whitespace separator characters before or after the form.

If file is not supplied or is given as NIL, the default output stream as controlled by the variables ^R, ^W, OUTFILES, and TYO will be used.

Note: The function PRIN1 is not affected by the value of the variable PRIN1. Only the toplevel Read-Eval-Print loop looks at this value. If you would like to write a package which lets users over-ride the system printer with their own printer, you might consider writing:

PRINC is like PRIN1 except that special characters are not slashified or wrapped in vertical bars, and strings are not wrapped in quotes.

If file is not supplied or is given as NIL, the default output stream as controlled by the variables ^R, ^W, OUTFILES, and TYO will be used.

Like PRIN1, PRINT outputs object to file in a form that can be understood by READ. However, object is output preceded by newline and followed by a space so that repeated calls to PRINT can be done without having the end of one object run into the begining of the next.

If file is not supplied or is given as NIL, the default output stream as controlled by the variables ^R, ^W, OUTFILES, and TYO will be used.

Types a newline in file.

If file is not supplied or is given as NIL, the default output stream as controlled by the variables ^R, ^W, OUTFILES, and TYO will be used.

fileobj must be a file-object open in FIXNUM mode (see OPEN), or an sfa which supports the IN operation. The return value of IN will be a full-word integer representing the value of a word read in fixnum mode from the file. If an end-of-file is encountered, the end-of-file handler is expected to throw out of the read-attempt. Otherwise, IN will signal an EOF error.

file must be a file object open in FIXNUM mode or an sfa which supports the OUT operation. A good mnemonic for the ordering of args is that they are backwards from the intuitive way of doing things and sideways from IN.

Outputs the character whose ascii code is i to file.

If file is not supplied or is given as NIL, the default output stream as controlled by the variables ^R, ^W, OUTFILES, and TYO will be used.

[PDP-10 Only] This is a fast version of TYO. It expects character to be a fixnum representing a character to be output. stream should be a real file object -- may not be a list of files nor may it be NIL. It can, however, be a file array, a SFA, or the symbol T. The character will be output to that output stream.

No update of CHARPOS information or checking for auto-TERPRI is done. FILEPOS information is updated correctly, however.

If *RSET is NIL, no argument checking is done.

When called on an SFA, returns whatever the SFA returns (for efficiency). Makes no special effort to return T.

Returns a fixnum which is non-zero if there is any input that has been typed in on fileobj, which must be a tty-input file object or T.

The action of this operation is ill-defined in the case where (SSTATUS LINMODE T) has been done.

NIL is not a valid argument to LISTEN.

[PDP-10 Only] Attempts to rub out a character (which should be a fixnum in the ASCII range, 0-177 octal) from file (which defaults to T).

If it is not possible to rub out the character correctly, rubout will return NIL instead of T; it is up to the caller to do something about this case. Characters which cannot correctly be rubbed out include tab and carriage return.

If the output tty can do cursor positioning and selective erasure, then the character is rubbed out by erasing it from the screen and backing up the cursor; otherwise, the character is printed on the tty (rubout echo).

NIL is not a valid file argument to RUBOUT.

This function exists now only in the Multics implementation.

If sym has more than one char in its printname, this is the same as multiple calls to IOC with 1-character symbols for the characters making up the printname.

This was a way of doing what would happen if the user had typed the controlified ascii character(s) corresponding to the printname of sym.

The correct way to achieve this functionality is to look at (STATUS TTYINT char) to get the interrupt handler. If the handler is a symbol, do (FUNCALL handler stream char), where stream was the input file object that char was read from. If the handler is a fixnum, do one of the special operations shown below.

This function exists now only in the Multics implementation.

The values of the switch variables ^Q, ^R, and ^W are first bound to themselves, then ioc is called on sym, and finally form₁, form₂, ... are evaluated a la implicit-PROGN returning as the value of the IOG-form, the value returned by the last form.

To mechanically rewrite this form in modern code, use

(LET ((^Q NIL) (^R NIL) (^W NIL)) (IOC sym) form₁ form₂ ...)

and then follow the instructions given in the description of IOC for updating the call to IOC. Some optimization may be appropriate.

Returns the length of its argument in characters, if it was printed out without slashifying special characters.

Flatsize returns the length of its argument in characters, if it was printed out with special characters slashified.

Returns the number of character positions assumed between tab stops.

Returns the newline character for the current operating system. i.e., on Multics, this returns #\LINEFEED and on PDP-10's #\RETURN. In both implementations, #\NEWLINE is defined to read as the (STATUS NEWLINE) for the given site.

Returns the value of the LINMODE switch for a given fileobj, which must be a tty file array, and which defaults to T, the terminal. If the value returned is T, then only carriage returns cause the tty prescan function to return with its buffered list of characters. If it is NIL, then character at a time I/O is done to the terminal. On some operating systems, setting it to T may give better rubout handling on a given line, but will give poor system performance for multi-line input (e.g., the user won't be able to rub out into the previous line). Also, once this switch is set to T, various bugs make it unlikely that you will successfully be able to set it usefully back to NIL.

[PDP-10 Only] Sets the LINMODE switch to T or NIL, as given by val. On ITS, it also affects the activation bits in the TTYST1 and TTYST2 job variables -- see (STATUS TTY).

Returns the information about the tty file array, fileobj, which defaults to T, the terminal.

This is the extension in New-I/O to Old-I/O's setting of the variable TTY. For compatibility, when it starts up, New-I/O Lisp does

On ITS, the numbers are based on the result of looking at the Lisp user's “TCTYP” tty variable.

The values presently defined are:

On non-ITS sites, this returns some value which I have not found documentation about.

In general, it is better not to use this STATUS function, since it is so operating system dependent. Rather, one should say (STATUS FILEMODE fileobj) and look for flags such as RUBOUT and CURSORPOS.

Returns the output baud rate of fileobj, which must be a tty file array (*** or SFA? ***) and which defaults to T, the terminal.

Returns the dimensions of the terminal display area which is referred to by the tty file array, fileobj. The filearray defaults to T, meaning the terminal. The value is in the format (height . width).

Returns a list of information about the state of fileobj, which must be a tty file array (*** or SFA?? ***) and which if not supplied defaults to T, meaning the default terminal.

On ITS, this information is a list of three fixnums which are the values of the TTYST1, TTYST2 and TTYSTS variables for the given tty input file.

*** It would probably be helpful if we mentioned here what the meaning of those bits was for non-ITS. Maybe next draft... ***

Sets the bits that are read by (STATUS TTY).

Returns the value (T or NIL) of the TERPRI switch, which is kept in the readtable. This switch defaults to NIL. If it is T, the output functions such as PRINT and TYO will not output any extra newlines when lines longer than LINEL are typed out. If it is NIL, the variable TERPRI has control of whether extra newlines can be inserted.

Sets the TERPRI switch to T or NIL according to the given val.

Returns the value of the abbreviation control.

If q is a number, sets the abbreviation control to n. If q is NIL, turns off abbreviation. If q is T, turns on a maximal amount of abbreviation.

Returns the value (T or NIL) of the switch which is kept in the readtable. If this switch is NIL or if the output radix (see BASE) is not 8, then fixnums with many trailing zeroes display as just that. If the switch is T, the default, and if the output radix is 8, fixnums with many trailing zeroes display as n_m, meaning a value of (LSH n m).

Sets the _ switch to T or NIL, according to the given val.

Grinds (pretty prints) the definitions of fn₁, fn₂, ... to the default output stream. With no arguments, as in (GRINDEF), calls GRINDEF using the last arguments.

To grind something which is not a definition, you probably want to use SPRINTER or SPRIN1.

Outputs to the default output stream a pretty-printed display of form, beginning on a fresh line.

[PDP-10 Only] Takes args like PRIN1, but pretty-prints its result (a la SPRINTER).

Note: Actually, defaulting of the fileobj may be slightly different than for PRIN1. When in doubt, give an explicit file argument.

[PDP-10 Only] If NIL, the original form of a MACROEXPANDED object will be printed by the grinder. Otherwise, the expanded form will be printed.

Holds the arglist from the last time GRINDEF was called (with an arglist other than NIL). This is so that when GRINDEF is called with no args, it can remember what it did before and repeat that behavior.

GRIND grinds (pretty prints) the file given by namelist. The ground file is written back to the same filename. For example, to grind the file ((DSK MYDIR) MY FILE), say:

*** Author's note: I wouldn't trust any program to write back over its input file. I'd suggest either copying out an extra copy of the file in case something goes wrong or using GRIND0.

This is like GRIND but does not close the output file. Since it was written for Old-I/O, the file can be closed by the UFILE command. For example, to grind the file ((DSK MYDIR) MY FILE) into ((DSK MYDIR) MY OUTPUT), you would say:

[PDP-10 Only] Invokes the CGOL Read-Eval-Print loop.

[PDP-10 Only] Like READ, but reads an expression in CGOL syntax.