;;; -*- Mode:gate; Fonts:(HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I ) -*- =Node: 4Expression Output Functions* =Text: 3EXPRESSION OUTPUT FUNCTIONS* These functions all take an optional argument called 1stream*, which is where to send the output. If unsupplied 1stream* defaults to the value of 2*standard-output**. If 1stream* is 2nil*, the value of 2*standard-output** (i.e. the default) is used. If it is 2t*, the value of 2*terminal-io** is used (i.e. the interactive terminal). This is all more-or-less compatible with Maclisp, except that instead of the variable 2*standard-output** Maclisp has several variables and complicated rules. For detailed documentation of streams, refer to 4(IOSYSTEM-2)I/O Streams*. 3prin1* 1object* &optional 1stream* Outputs the printed representation of 1object* to 1stream*, with escaping (see 4(READPRINT-1)What the Printer Produces*). 1object* is returned. 3prin1-then-space* 1object* &optional 1stream* Like 2prin1* except that output is followed by a space. 3print* 1object* &optional 1stream* Like 2prin1* except that output is preceded by a carriage return and followed by a space. 1object* is returned. 3princ* 1object* &optional 1stream* Like 2prin1* except that the output is not escaped. 1object* is returned. 3write* 1object* &key 1stream* 1escape* 1radix* 1base* 1circle* 1pretty* 1level* 1length* 1case* 1gensym* 1array* Prints 1object* on 1stream*, having bound all the printing flags according to the keyword arguments if specified. For example, the keyword argument 1array* specifies how to bind 2*print-array**; if 1array* is omitted, the ambient value of 2*print-array** is used. This function is sometimes cleaner than binding a printing control variable explicitly. The value is 1object*. =Node: 4Pretty-Printing Output Functions* =Text: 3PRETTY-PRINTING OUTPUT FUNCTIONS pprint* 1object* &optional 1stream* 2pprint* is like 2prin1* except that 2*print-pretty** is bound to 2t* so that the grinder is used. 2pprint* returns zero values, just as the form 2(values)* does. 3grindef* 1function-spec...* 1Macro* Prints the definitions of one or more functions, with indentation to make the code readable. Certain other ``pretty-printing'' transformations are performed: The 2quote* special form is represented with the 2'* character. Displacing macros are printed as the original code rather than the result of macro expansion. The code resulting from the backquote (2`*) reader macro is represented in terms of 2`*. The subforms to 2grindef* are the function specs whose definitions are to be printed; the usual way 2grindef* is used is with a form like 2(grindef foo)* to print the definition of 2foo*. When one of these subforms is a symbol, if the symbol has a value its value is prettily printed also. Definitions are printed as 2defun* special forms, and values are printed as 2setq* special forms. If a function is compiled, 2grindef* says so and tries to find its previous interpreted definition by looking on an associated property list (see 2uncompile* (4(COMPILER-1)How to Invoke the Compiler*). This works only if the function's interpreted definition was once in force; if the definition of the function was simply loaded from a QFASL file, 2grindef* cannot not find the interpreted definition. With no subforms, 2grindef* assumes the same arguments as when it was last called. 3grind-top-level* 1obj* &optional 1width* 1(stream* 3*standard-output*1)** 1(untyo-p* 3nil1)** 1(displaced* 3'si:displaced1)** 1(terpri-p* 3t1)** 1notify-fun* 1loc* Pretty-prints 1obj* on 1stream*, putting up to 1width* characters per line. This is the primitive interface to the pretty-printer. Note that it does not support variable-width fonts. If the 1width* argument is supplied, it is how many characters wide the output is to be. If 1width* is unsupplied or 2nil*, 2grind-top-level* tries to figure out the natural width of the stream, by sending a 2:size-in-characters* message to the stream and using the first returned value. If the stream doesn't handle that message, a width of 295.* characters is used instead. The remaining optional arguments activate various strange features and usually should not be supplied. These options are for internal use by the system and are documented here for only completeness. If 1untyo-p* is 2t*, the 2:untyo* and 2:untyo-mark* operations are be used on 1stream*, speeding up the algorithm somewhat. 1displaced* controls the checking for displacing macros; it is the symbol which flags a place that has been displaced, or 2nil* to disable the feature. If 1terpri-p* is 2nil*, 2grind-top-level* does not advance to a fresh line before printing. If 1notify-fun* is non-2nil*, it should be a function that to be called with three arguments for each ``token'' in the pretty-printed output. Tokens are atoms, open and close parentheses, and reader macro characters such as 3'*. The arguments given to 1notify-fun* are the token, its ``location'' (see next paragraph), and 2t* if it is an atom or 2nil* if it is a character. 1loc* is the ``location'' (typically a cons) whose car is 1obj*. As the grinder recursively descends through the structure being printed, it keeps track of the location where each thing came from, for the benefit of the 1notify-fun*. This makes it possible for a program to correlate the printed output with the list structure. The ``location'' of a close parenthesis is 2t*, because close parentheses have no associated location. =Node: 4Non-Stream Printing Functions* =Text: 3NON-STREAM PRINTING FUNCTIONS write-to-string* 1object* &key 1escape* 1radix* 1base* 1circle* 1pretty* 1level* 1length* 1case* 1gensym* 1array* 3prin1-to-string* 1object* 3princ-to-string* 1object* Like 2write*, 2prin1* and 2princ*, respectively, but put the output in a string and return the string (see 4(READPRINT-3)Expression Output Functions*). See also the 2with-output-to-string* special form (4(IOSYSTEM-2)String I/O Streams*). The following obsolete functions are for Maclisp compatibility only. The examples use traditional syntax. 3exploden* 1object* Returns a list of characters (represented as fixnums) that are the characters that would be typed out by 2(princ 1object*)* (i.e. the unescaped printed representation of 1object*). Example: 3(exploden '(+ /12 3)) => #o(50 53 40 61 62 40 63 51) explodec* 1object* Returns a list of characters represented by symbols, interned in the current package, whose names are the characters that would be typed out by 2(princ 1object*)* (i.e. the unescaped printed representation of 1object*). Example: 3(explodec '(+ /12 3)) => (|(| + | | |1| |2| | | |3| |)|)* (Note that there are escaped spaces in the above list.) 3explode* 1object* Like 2explodec* but uses the escaped printed representation. Example: 3(explode '(+ /12 3)) => (|(| + | | // |1| |2| | | |3| |)|)* (Note that there are escaped spaces in the above list.) 3flatsize* 1object* Returns the number of characters in the escaped printed representation of 1object*. 3flatc* 1object* Returns the number of characters in the unescaped printed representation of 1object*. =Node: 4Expression Input Functions* =Text: 3EXPRESSION INPUT FUNCTIONS* Most expression input functions read characters from an input stream. This argument is called 1stream*. If unsupplied it defaults to the value of 2*standard-input**. All of these functions echo their input and permit editing if used on an interactive stream (one which supports the 2:rubout-handler* operation; see below.) The functions accept an argument 1eof-option* or two arguments 1eof-error* and 1eof-value* to tell them what to do if end of file is encountered instead of an object's p.r. The functions that take two 1eof-* arguments are the Common Lisp ones. In functions that accept the 1eof-option* argument, if no argument is supplied, an error is signaled at eof. If the argument is supplied, end of file causes the function to return that argument. Note that an 1eof-option* of 2nil* means to return 2nil* if the end of the file is reached; it is 1not* equivalent to supplying no 1eof-option*. In functions that accept two arguments 1eof-error* and 1eof-value*, end of file is an error if 1eof-error* is non-2nil* or if it is unsupplied. If 1eof-error* is 2nil*, then the function returns 1eof-value* at end of file. An error is always signaled if end of file is encountered in the middle of an object; for example, if a file does not contain enough right parentheses to balance the left parentheses in it. Mere whitespace does not count as starting an object. If a file contains a symbol or a number immediately followed by end-of-file, it can be read normally without error; if an attempt is made to read further, end of file is encountered immediately and the 1eof-* argument(s) obeyed. These end-of-file conventions are not completely compatible with Maclisp. Maclisp's deviations from this are generally considered to be bugs rather than features. For Maclisp compatibility, 2nil* as the 1stream* argument also means to use the value of 2*standard-input**, and 2t* as the 1stream* argument means to use the value of 2*terminal-io**. This is only advertised to work in functions that Maclisp has, and should not be written in new programs. Instead of the variable 2*standard-input** Maclisp has several variables and complicated rules. For detailed documentation of streams, refer to 4(IOSYSTEM-2)I/O Streams*. The functions below that take 1stream* and 1eof-option* arguments can also be called with the stream and eof-option in the other order. This functionality is only for compatibility with old Maclisp programs, and should never be used in new programs. The functions attempt to figure out which way they were called by seeing whether each argument is a plausible stream. Unfortunately, there is an ambiguity with symbols: a symbol might be a stream and it might be an eof-option. If there are two arguments, one being a symbol and the other being something that is a valid stream, or only one argument, which is a symbol, then these functions interpret the symbol as an eof-option instead of as a stream. To force them to interpret a symbol as a stream, give the symbol an 2si:io-stream-p* property whose value is 2t*. 3read* &optional 1stream* 1eof-option* 1rubout-handler-options* Reads the printed representation of a Lisp object from 1stream*, builds a corresponding Lisp object, and returns the object. 1rubout-handler-options* are used as options for the rubout handler, if 1stream* supports one; see 4(IOSYSTEM-4)Rubout Handling* for more information on this. 3cli:read* &optional 1stream* 1(eof-errorp* 3t1)** 1eof-value* 1recursive-p* The Common Lisp version of 2read* differs only in how its arguments are passed. 1recursive-p* should be non-2nil* when calling from the reader or from the defining function of a read-macro character; that is, when reading a subexpression as part of the task of reading a larger expression. This has two effects: the subexpression is allowed to share 3#1n*#* labels with the containing expression, and whitespace which terminates the subexpression (if it is a symbol or number) is not discarded. 3read-or-end* &optional 1stream* 1eof-option* 1rubout-handler-options* Like 2read*, but on an interactive stream if the input is just the character 2End* it returns the two values 2nil* and 2:end*. 3read-preserve-delimiters* 1Variable* Certain printed representations given to 2read*, notably those of symbols and numbers, require a delimiting character after them. (Lists do not, because the matching close-parenthesis serves to mark the end of the list.) Normally 2read* throws away the delimiting character if it is whitespace, but preserves it (using the 2:untyi* stream operation) if the character is syntactically meaningful, since it may be the start of the next expression. If 2read-preserve-delimiters* is bound to 2t* around a call to 2read*, the delimiting character is never thrown away, even if it is whitespace. This may be useful for certain reader macros or special syntaxes. 3read-preserving-whitespace* &optional 1stream* 1(eof-errorp* 3t1)** 1eof-value* 1recursive-p* Like 2cli:read* but binds 2read-preserve-delimiters* to 2t*. This is the Common Lisp way of requesting the 2read-preserve-delimiters* feature. 3read-delimited-list* 1char* &optional 1stream* 1recursive-p* Reads expressions from 1stream* until the character 1char* is seen at top level when an expression is expected; then returns a list of the objects read. 1char* may be a fixnum or a character object. For example, if 1char* is 3#/]*, and the text to be read from 1stream* is 2a (b* 2c)]* ... then the objects 2a* and 2(b c)* are read, the 2]* is seen as a terminator and discarded, and the value returned is 2(a (b c))*. 1recursive-p* is as for 2cli:read*. End of file within this function is always an error since it is always ``within an object''--the object whose textual representation is terminated by 1char*. Note that use of this function does not cause 1char* to terminate tokens. Usually you want that to happen, but it is purely under the control of the readtable. So you must modify the readtable to make this so. The usual way is to define 1char* as a macro character whose defining function just signals an error. The defining function is not called when 1char* is encountered in the expected context by 2read-delimited-list*; if 1char* is encountered anywhere else, it is an unbalanced bracket and an error is appropriate. 3read-for-top-level* &optional 1stream* 1eof-option* This is a slightly different version of 2read*. It differs from 2read* only in that it ignores close-parentheses seen at top level, and it returns the symbol 2si:eof* if the stream reaches end-of-file if you have not supplied an 1eof-option* (instead of signalling an error as 2read* would). This version of 2read* is used in the system's ``read-eval-print'' loops. 3read-check-indentation* &optional 1stream* 1eof-option* This is like 2read*, but validates the input based on indentation. It assumes that the input data is formatted to follow the usual convention for source files, that an open-parenthesis in column zero indicates a top-level list (with certain specific exceptions). An open-parenthesis in column zero encountered in the middle of a list is more likely to result from close-parentheses missing before it than from a mistake in indentation. If 2read-check-indentation* finds an open-parenthesis following a return character in the middle of a list, it invents enough close-parentheses to close off all pending lists, and returns. The offending open-parenthesis is 2:untyi*'d so it can begin the next list, as it probably should. End of file in the middle of a list is handled likewise. 2read-check-indentation* notifies the caller of the incorrect formatting by signaling the condition 2sys:missing-closeparen*. This is how the compiler is able to record a warning about the missing parentheses. If a condition handler proceeds, 2read* goes ahead and invents close-parentheses. There are a few special forms that are customarily used around function definitions--for example, 2eval-when*, 2local-declare*, and 2comment*. Since it is desirable to begin the function definitions in column zero anyway, 2read-check-indentation* allows a list to begin in column zero within one of these special forms. A non-2nil* 2si:may-surround-defun* property identifies the symbols for which this is allowed. 3read-check-indentation* 1Variable* This variable is non-2nil* during a read in which indentation is being checked. =Node: 4Non-Stream Parsing Functions* =Text: 3NON-STREAM PARSING FUNCTIONS* The following functions do expression input but get the characters from a string or a list instead of a stream. 3read-from-string* 1string* &optional 1eof-option* 1(start* 301)** 1end* The characters of 1string* are given successively to the reader, and the Lisp object built by the reader is returned. Macro characters and so on all take effect. If 1string* has a fill-pointer it controls how much can be read. 1eof-option* is what to return if the end of the string is reached, as in 2read*. 1start* is the index in the string of the first character to be read. 1end* is the index at which to stop reading; that point is treated as end of file. 2read-from-string* returns two values; the first is the object read and the second is the index of the first character in the string not read. If the entire string was read, this is the length of the string. Example: 3(read-from-string "(a b c)") => (a b c) 2and* 7 cli:read-from-string* 1string* &optional 1(eof-errorp* 3t1)** 1eof-value* &key 1(start* 301)** 1end* 1preserve-whitespace* The Common Lisp version of 2read-from-string* uses a different calling convention. The arguments mean the same thing but are arranged differently. There are three arguments with no counterparts: 1eof-errorp* and 1eof-value*, which are simply passed on to 2cli:read*, and 1preserve-whitespace*, which if non-2nil* means that the reading is done with 2read-preserve-delimiters* bound to 2t*. See also the 2with-input-from-string* special form (4(IOSYSTEM-2)String I/O Streams*). 3parse-integer* 1string* &key 1(start* 301)** 1end* 1(radix* 310.1)** 1junk-allowed* Parses the contents of 1string* (or the portion from 1start* to 1end*) as a numeral for an integer using the specified radix, and returns the integer. Radices larger than ten are allowed, and they use letters as digits beyond 9. Leading whitespace is always allowed and ignored. A leading sign is also allowed and considered part of the number. When 1junk-allowed* is 2nil*, the entire specified portion of string must consist of an integer and leading and trailing whitespace. Otherwise, an error happens. If 1junk-allowed* is non-2nil*, parsing just stops when a non-digit is encountered. The number parsed so far is returned as the first value, and the index in 1string* at which parsing stopped is returned as the second value. This number equals 1end* (or the length of 1string*) if there is nothing but a number. If non-digits are found without finding a number first, the first value is 2nil*. Examples: 3(parse-integer " 1A " :radix 16.) => 26.* 3(parse-integer " 15X " :end 3) => 15.* 3(parse-integer " -15X " :junk-allowed t) => -15. 3* 3(parse-integer " 15X ") => error! readlist* 1char-list* This function is provided mainly for Maclisp compatibility. 1char-list* is a list of characters. The characters may be represented by anything that the function 2character* accepts: character objects, fixnums, strings, or symbols. The characters are given successively to the reader, and the Lisp object built by the reader is returned. Macro characters and so on all take effect. If there are more characters in 1char-list* beyond those needed to define an object, the extra characters are ignored. If there are not enough characters, some kind of 2sys:read-end-of-file* error is signaled. =Node: 4Input Error Conditions* =Text: 3INPUT ERROR CONDITIONS sys:read-error* (3sys:parse-error* 3error*) 1Condition* This condition name classifies all errors detected by the reader per se. Since 2sys:parse-error* is implied, all 2sys:read-error* errors must provide the proceed type 2:no-action* so that automatic proceed is possible if the error happens during compilation. See 4(IOSYSTEM-4)Rubout Handling*. Since this condition name implies 2sys:parse-error* and 2error*, those two are not mentioned as implications below when 2sys:read-error* is. 3sys:read-end-of-file* (3sys:read-error* 3sys:end-of-file*) 1Condition* Whenever the reader signals an error for end of file, the condition object possesses this condition name. Since 2sys:end-of-file* is implied, the 2:stream* operation on the condition instance returns the stream on which end of file was reached. 3sys:read-list-end-of-file* (3sys:read-end-of-file* 3sys:read-error* 3sys:end-of-file*)1Condition* This condition is signaled when 2read* detects end of file in the middle of a list. In addition to the 2:stream* operation provided because 2sys:end-of-file* is one of the proceed types, the condition instance supports the 2:list* operation, which returns the list read so far. Proceed type 2:no-action* is provided. If it is used, the reader invents a close-parenthesis to close off the list. Within 2read-check-indentation*, the reader signals the error only once, no matter how many levels of list are unterminated. 3sys:read-string-end-of-file* 1Condition* (3sys:read-end-of-file* 3sys:read-error* 3sys:end-of-file*) This is signaled when 2read* detects end of file in the middle of a string delimited by double-quotes. The 2:string* operation on the condition instance returns the string read so far. Proceed type 2:no-action* terminates the string and returns. If the string is within other constructs that are unterminated, another end of file error is will be signaled later. 3sys:read-symbol-end-of-file* 1Condition* (3sys:read-end-of-file* 3sys:read-error* 3sys:end-of-file*) This is signaled when 2read* detects end of file within a multiple escape construct. The 2:string* operation on the condition instance returns the print name read so far. Proceed type 2:no-action* terminates the symbol and returns. If the symbol is within other constructs that are unterminated, another end of file error is will be signaled later. 3sys:missing-closeparen* (3condition*) 1Condition* This condition, which is not an error, is signaled when 2read-check-indentation* finds an open-parenthesis in column zero within a list. Proceed type 2:no-action* is provided. On proceeding, the reader invents enough close-parentheses to close off all the lists that are pending.