;;; -*- Mode:gate; Fonts:(HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I ) -*- =Node: 4Formatted Output* =Text: 3FORMATTED OUTPUT* There are two ways of doing general formatted output. One is the function 2format*. The other is the 2output* subsystem. 2format* uses a control string written in a special format specifier language to control the output format. 2format:output* provides Lisp functions to do output in particular formats. For simple tasks in which only the most basic format specifiers are needed, 2format* is easy to use and has the advantage of brevity. For more complicated tasks, the format specifier language becomes obscure and hard to read. Then 2format:output* becomes advantageous because it works with ordinary Lisp control constructs. =Node: 4The Format Function* =Text: 3THE FORMAT FUNCTION format* 1destination* 1control-string* &rest 1args* Produces formatted output. 2format* outputs the characters of 1control-string*, except that a tilde (`2~*') introduces a directive. The character after the tilde, possibly preceded by prefix parameters and modifiers, specifies what kind of formatting is desired. Most directives use one or more elements of 1args* to create their output; the typical directive puts the next element of 1args* into the output, formatted in some special way. The output is sent to 1destination*. If 1destination* is 2nil*, a string is created which contains the output; this string is returned as the value of the call to 2format*. In all other cases 2format* returns no interesting value (generally it returns 2nil*). If 1destination* is a stream, the output is sent to it. If 1destination* is 2t*, the output is sent to 2*standard-output**. If 1destination* is a string with an array-leader, such as would be acceptable to 2string-nconc* (see 4(CHARSTR-2)Basic String Operations*), the output is added to the end of that string. A directive consists of a tilde, optional prefix parameters separated by commas, optional colon (`2:*') and atsign (`2@*') modifiers, and a single character indicating what kind of directive this is. The alphabetic case of the character is ignored. The prefix parameters are generally decimal numbers. Examples of control strings: 3"~S" ; 2This is an S directive with no parameters.** 3"~3,4:@s" ; 2This is an S directive with two parameters, 3 and 4,** 3 ; 2 and both the colon and atsign flags.** 3"~,4S" ; 2The first prefix parameter is omitted and takes** 3 ; 2 on its default value, while the second is 4.** 2format* includes some extremely complicated and specialized features. It is not necessary to understand all or even most of its features to use 2format* efficiently. The beginner should skip over anything in the following documentation that is not immediately useful or clear. The more sophisticated features are there for the convenience of programs with complicated formatting requirements. Sometimes a prefix parameter is used to specify a character, for instance the padding character in a right- or left-justifying operation. In this case a single quote ("2'*") followed by the desired character may be used as a prefix parameter, so that you don't have to know the decimal numeric values of characters in the character set. For example, you can use 2"~5,'0d"* instead of 2"~5,48d"* to print a decimal number in five columns with leading zeros. In place of a prefix parameter to a directive, you can put the letter 2V*, which takes an argument from 1args* as a parameter to the directive. Normally this should be a number but it doesn't really have to be. This feature allows variable column-widths and the like. Also, you can use the character 2#* in place of a parameter; it represents the number of arguments remaining to be processed. Here are some relatively simple examples to give you the general flavor of how 2format* is used. 3(format nil "foo") => "foo"* 3(setq x 5)* 3(format nil "The answer is ~D." x) => "The answer is 5."* 3(format nil "The answer is ~3D." x) => "The answer is 5."* 3(setq y "elephant")* 3(format nil "Look at the ~A!" y) => "Look at the elephant!"* 3(format nil "The character ~:@C is strange." #\meta-beta)* 3 => "The character Meta- (Greek-b) is strange."* 3(setq n 3)* 3(format nil "~D item~:P found." n) => "3 items found."* 3(format nil "~R dog~:[s are~; is~] here." n (= n 1))* 3 => "three dogs are here."* 3(format nil "~R dog~:*~[~1; is~:;s are~] here." n)* 3 => "three dogs are here."* 3(format nil "Here ~[~1;is~:;are~] ~:*~R pupp~:@P." n)* 3 => "Here are three puppies."* The directives will now be described. 1arg* will be used to refer to the next argument from 1args*. 2~A* 1arg*, any Lisp object, is printed without escaping (as by 2princ*). 2~:A* prints 2()* if 1arg* is 2nil*; this is useful when printing something that is always supposed to be a list. 2~1n*A* inserts spaces on the right, if necessary, to make the column width at least 1n*. The 2@* modifier causes the spaces to be inserted on the left rather than the right. 2~1mincol,colinc,minpad,padchar*A* is the full form of 2~A*, which allows elaborate control of the padding. The string is padded on the right with at least 1minpad* copies of 1padchar*; padding characters are then inserted 1colinc* characters at a time until the total width is at least 1mincol*. The defaults are 0 for 1mincol* and 1minpad*, 1 for 1colinc*, and space for 1padchar*. 2~S* This is just like 2~A*, but 1arg* is printed 1with* escaping (as by 2prin1* rather than 2princ*). 2~D* 1arg*, a number, is printed in base ten. Unlike 2print*, 2~D* never puts a decimal point after the number. 2~1n*D* uses a column width of 1n*; spaces are inserted on the left if the number requires less than 1n* columns for its digits and sign. If the number doesn't fit in 1n* columns, additional columns are used as needed. 2~1n*,1m*D* uses 1m* as the pad character instead of space. If 1arg* is not a number, it is printed in 2~A* format and decimal base. The 2@* modifier causes the number's sign to be printed always; the default is only to print it if the number is negative. The 2:* modifier causes commas to be printed between groups of three digits; the third prefix parameter may be used to change the character used as the comma. Thus the most general form of 2~D* is 2~1mincol*,1padchar*,1commachar*D*. 2~O* This is just like 2~D* but prints in octal instead of decimal. 2~X* This is just like 2~D* but prints in hex instead of decimal. Note that 2~X* used to have a different meaning: print one or more spaces. Uses of 2~X* intended to have this meaning should be replaced with 2~@T*. 2~B* This is just like 2~D* but prints in binary instead of decimal. 2~1w*,1d*,1k*,1ovfl*,1pad*F* 1arg* is printed in nonexponential floating point format, as in `10.5'. (If the magnitude of 1arg* is very large or very small, it is printed in exponential notation.) The parameters control the details of the formatting. 1w* is the total field width desired. If omitted, this is not constrained. 1d* is the number of digits to print after the decimal point. If 1d* is omitted, it is chosen to do a good job based on 1w* (if specified) and the value of 1arg*. 1k* is a scale factor. 1arg* is multiplied by 2(exp 10. 1k*)* before it is printed. 1ovfl* is a character to use for overflow. If 1arg* is too big to print and fit the constraints of field width, etc., and 1ovfl* is specified then the whole field is filled with 1ovfl*. If 1ovfl* is not specified, 1arg* is printed using extra width as needed. 1pad* is a character to use for padding on the left, when the field width is specified and not that many characters are really needed. If the 2@* modifier is used, a sign is printed even if 1arg* is positive. Rational numbers are converted to floats and then printed. Anything else is printed with 2~1w*D* format. 2~1w*,1d*,1e*,1k*,1ovfl*,1pad*,1expt*E* 1arg* is printed in exponential notation, as in `.105e+2'. The parameters control the details of the formatting. 1w* is the total field width desired. If omitted, this is not constrained. 1d 2and* k* control the number of mantissa digits and their arrangement around the decimal point. 1d*+1 digits are printed. If 1k* is positive, all of them are significant digits, and the decimal point is printed after the first 1k* of them. If 1k* is zero or negative, the first |1k*|+1 of the 1d*+1 digits are leading zeros, and the decimal point follows the first zero. (This zero can be omitted if necessary to fit the number in 1w* characters.) So the number of significant figures is less than 1d* if 1k* is negative. The exponent printed always compensates for any powers of ten introduced according to 1k*, so 10.5 might be printed as 20.105e+2* or as 21050.0e-2*. If 1d* is omitted, the system chooses enough significant figures to represent the float accurately. If 1k* is omitted, the default is one. 1e* is the number of digits to use for the exponent. If it is not specified, however many digits are needed are used. 1ovfl* is the overflow character. If the exponent doesn't fit in 1e* digits or the entire number does not fit in 1w* characters, then if 1ovfl* is specified, the field of 1w* characters is filled with 1ovfl*. Otherwise more characters are used as needed. 1pad* is a character to use for padding on the left, when the field width is specified and not that many characters are really needed. 1expt* is a character to use to separate the mantissa from the exponent. The default is 2e* or 2s* or 2f*, whichever would be used in printing the number normally. If the 2@* modifier is used, a sign is printed even if 1arg* is positive. 2~1w*,1d*,1e*,1k*,1ovfl*,1pad*,1expt*G* Prints a floating point number 1arg* in either 2~F* or 2~E* format. Fixed format is used if the absolute value of 1arg* is less than 2(expt 10. 1d*)*, and exponential format otherwise. (If 1d* is not specified, it defaults based on the value of 1arg*.) If fixed format is used, 1e*+2 blanks are printed at the end (where the exponent and its separator and sign would go, in exponential format). These count against the width 1w* if that is specified. Four blanks are used if 1e* is omitted. The diminished width available, 1d*, 1ovfl* and 1pad* are used as specified. The scale factor used in fixed format is always zero, not 1k*. If exponential format needs to be used, all the parameters are passed to the 2~E* directive to print the number. Rational numbers are converted to floats and then printed. Anything else is printed with 2~1w*D* format. 2~$* 2~1rdig*,1ldig*,1field*,1padchar*$* prints 1arg*, a float, with exactly 1rdig* digits after the decimal point. The default for 1rdig* is 2, which is convenient for printing amounts of money. At least 1ldig* digits are printed preceding the decimal point; leading zeros are printed if there would be fewer than 1ldig*. The default for 1ldig* is 1. The number is right justified in a field 1field* columns long, padded out with 1padchar*. The colon modifier means that the sign character is to be at the beginning of the field, before the padding, rather than just to the left of the number. The atsign modifier says that the sign character should always be output. If 1arg* is not a number, or is unreasonably large, it is printed in 2~1field*,,,1padchar*@A* format; i.e. it is 2princ*'ed right-justified in the specified field width. 2~C* 2(character 1arg*)* is put in the output. 1arg* is treated as a keyboard character (see 4(CHARSTR-1)Components of a Character*), thus it may contain extra control-bits. These are printed first by representing them with abbreviated prefixes: `2C-*' for 2Control*, `2M-*' for 2Meta*, `2H-*' for 2Hyper*, and `2S-*' for 2Super*. With the colon flag (2~:C*), the names of the control bits are spelled out (e.g. `2Control-Meta-F*') and non-printing characters are represented by their names (e.g. `2Return*') rather than being output as themselves. The printing characters Space and Altmode are also represented as their names, but all others are printed directly. With both colon and atsign (2~:@C*), the colon-only format is printed, and then if the character requires the 2Top* or 2Greek* (2Front*) shift key(s) to type it, this fact is mentioned (e.g. `2 (Top-U)*'). This is the format used for telling the user about a key he is expected to type, for instance in prompt messages. For all three of these formats, if the character is a mouse character, it is printed as 2Mouse-*, the name of the button, `3-*', and the number of clicks. With just an atsign (2~@C*), the character is printed in such a way that the Lisp reader can understand it, using `2#\*' or `2#/*', depending on the escaping character of 2*readtable** (see 4(READPRINT-2)What The Reader Accepts*). 2~%* Outputs a carriage return. 2~1n*%* outputs 1n* carriage returns. No argument is used. Simply putting a carriage return in the control string would work, but 2~%* is usually used because it makes the control string look nicer in the Lisp source program. 2~&* The 2:fresh-line* operation is performed on the output stream. Unless the stream knows that it is already at the front of a line, this outputs a carriage return. 2~1n*&* does a 2:fresh-line* operation and then outputs 1n*-1 carriage returns. 2~|* Outputs a page separator character (2#\page*). 2~1n*|* does this 1n* times. With a 2:* modifier, if the output stream supports the 2:clear-screen* operation this directive clears the screen, otherwise it outputs page separator character(s) as if no 2:* modifier were present. 2|* is vertical bar, not capital I. 2~~* Outputs a tilde. 2~1n*~* outputs 1n* tildes. 2~ * Tilde immediately followed by a carriage return ignores the carriage return and any whitespace at the beginning of the next line. With a 2:*, the whitespace is left in place. With an 2@*, the carriage return is left in place. This directive is typically used when a format control string is too long to fit nicely into one line of the program. 2~** 1arg* is ignored. 2~1n*** ignores the next 1n* arguments. 2~:** ``ignores backwards''; that is, it backs up in the list of arguments so that the argument last processed will be processed again. 2~1n*:** backs up 1n* arguments. 2~1n*@** is absolute; it moves to argument 1n* (1n* = 0 specifies the first argument). When within a 2~{* construct (see below), the ignoring (in either direction) is relative to the list of arguments being processed by the iteration. 2~P* If 1arg* is not 21*, a lower-case `s' is printed. (`2P*' is for `plural'.) 2~:P* does the same thing, after doing a 2~:**; that is, it prints a lower-case s if the 1last* argument was not 1. 2~@P* prints `y' if the argument is 1, or `ies' if it is not. 2~:@P* does the same thing, but backs up first. 2~T* Spaces over to a given column. 2~1n*,1m*T* outputs sufficient spaces to move the cursor to column 1n*. If the cursor is already past column 1n*, it outputs spaces to move it to column 1n*+1mk*, for the smallest integer value 1k* possible. 1n* and 1m* default to 21*. Without the colon flag, 1n* and 1m* are in units of characters; with it, they are in units of pixels. Note: this operation works properly 1only* on streams that support the 2:read-cursorpos* and 2:increment-cursorpos* stream operations (see 4(IOSYSTEM-2)Cursor Positioning Stream Operations*). On other streams, any 2~T* operation simply outputs two spaces. When 2format* is creating a string, 2~T* works by assuming that the first character in the string is at the left margin. 2~@T* simply outputs a space. 2~1rel*T* simply outputs 1rel* spaces. 2~1rel*, 1period*T* outputs 1rel* spaces and then additional spaces until it reaches a column which is a multiple of 1period*. If the output stream does not support 2:read-cursorpos* then it simply outputs 1rel* spaces. 2~R* 2~R* prints 1arg* as a cardinal English number, e.g. four. 2~:R* prints 1arg* as an ordinal number, e.g. fourth. 2~@R* prints 1arg* as a Roman numeral, e.g. 2IV*. 2~:@R* prints 1arg* as an old Roman numeral, e.g. 2IIII*. 2~1n*R* prints 1arg* in radix 1n*. The flags and any remaining parameters are used as for the 2~D* directive. Indeed, 2~D* is the same as 2~10R*. The full form here is therefore 2~1radix*,1mincol*,1padchar*,1commachar*R*. 2~?* Uses up two arguments, and processes the first one as a format control string using the second one's elements as arguments. Thus, 3(format nil "~? ~D" "~O ~O" '(4 20.) 9)* returns 2"4 24 9"*. 2~@?* processes the following argument as a format control string, using all the remaining arguments. Any arguments it does not use are left to be processed by the format directives following the 2~@?* in the original control string. 3(format nil "~@? ~D" "~O ~O" 4 20. 9)* likewise returns 2"4 24 9"*. 2~1str*~* Performs the formatting specified by 1str*, with indentation on any new lines. Each time a 2Return* is printed during the processing of 1str*, it is followed by indentation sufficient to line up underneath the place where the cursor was at the beginning of 1str*. For example, 3(format t "Foo: ~8T~~A~" 1string*)* prints 1string* with each line starting at column 8. If 1string* is 2(string-append "This is"* 2#\return "the string")* then the output is 3Foo: This is* 3the string 2~(1str*~)** Performs output with case conversion. The formatting specified by 1str* is done, with all the letters in the resulting output being converted to upper or lower case according to the modifiers given to the 2~(* command: 2~( without modifiers* Converts all the letters to lower case. 2~:(* Converts the first letter of each word to upper case and the rest to lower case. 2~@(* Converts the first letter of the first word to upper case, and all other letters to lower case. 2~:@(* Converts all the letters to upper case. 2~1(* Converts the first letter of the first word to upper case and does not change anything else. If you arrange to generate all output in lower case except for letters that should be upper case regardless of context, you can use this directive when the output appears at the beginning of a sentence. Example: 3"~(FoO BaR~) ~:(FoO BaR~) ~@(FoO BaR~) ~:@(FoO BaR~)* 3~1(at the White Hart~)"* produces 3foo bar Foo Bar Foo bar FOO BAR* 3At the White Hart 2~[1str0*~;1str1*~;1...*~;1strn*~]** This is a set of alternative control strings. The alternatives (called 1clauses*) are separated by 2~;* and the construct is terminated by 2~]*. For example, 3"~[Siamese ~;Manx ~;Persian ~;Tortoise-Shell ~* 3 ~;Tiger ~;Yu-Shiang ~]kitty"* The 1arg*th alternative is selected; 20* selects the first. If a prefix parameter is given (i.e. 2~1n*[*), then the parameter is used instead of an argument (this is useful only if the parameter is `2#*'). If 1arg* is out of range no alternative is selected. After the selected alternative has been processed, the control string continues after the 2~]*. 2~[1str0*~;1str1*~;1...*~;1strn*~:;1default*~]* has a default case. If the 1last* 2~;* used to separate clauses is instead 2~:;*, then the last clause is an ``else'' clause, which is performed if no other clause is selected. For example, 3"~[Siamese ~;Manx ~;Persian ~;Tiger ~* 3 ~;Yu-Shiang ~:;Bad ~] kitty"* 2~[~1tag00*,1tag01*,1...*;1str0*~1tag10*,1tag11*,1...*;1str1...*~]* allows the clauses to have explicit tags. The parameters to each 2~;* are numeric tags for the clause which follows it. That clause is processed which has a tag matching the argument. If 2~1a1*,1a2*,1b1*,1b2*,1...*:;* (note the colon) is used, then the following clause is tagged not by single values but by ranges of values 1a1* through 1a2* (inclusive), 1b1* through 1b2*, etc. 2~:;* with no parameters may be used at the end to denote a default clause. For example, 3"~[~'+,'-,'*,'//;operator ~'A,'Z,'a,'z:;letter ~* 3 ~'0,'9:;digit ~:;other ~]"* 2~:[1false*~;1true*~]* selects the 1false* control string if 1arg* is 2nil*, and selects the 1true* control string otherwise. 2~@[1true*~]* tests the argument. If it is not 2nil*, then the argument is not used up, but is the next one to be processed, and the one clause is processed. If it is 2nil*, then the argument is used up, and the clause is not processed. For example, 3(setq *print-level* nil *print-length* 5)* 3(format nil* 3 "~@[ *PRINT-LEVEL*=~D~]~@[ *PRINT-LENGTH*=~D~]"* 3 prinlevel prinlength)* 3 => " *PRINT-LENGTH*=5"* The combination of 2~[* and 2#* is useful, for example, for dealing with English conventions for printing lists: 3(setq foo "Items:~#[ none~; ~S~; ~S and ~* 3 ~S~:;~@{~#[~1; and~] ~S~^,~}~].")* 3(format nil foo)* 3=> "Items: none."* 3(format nil foo 'foo)* 3=> "Items: FOO."* 3(format nil foo 'foo 'bar)* 3=> "Items: FOO and BAR."* 3(format nil foo 'foo 'bar 'baz)* 3=> "Items: FOO, BAR, and BAZ."* 3(format nil foo 'foo 'bar 'baz 'quux)* 3=> "Items: FOO, BAR, BAZ, and QUUX." 2~;** Separates clauses in 2~[* and 2~<* constructions. It is undefined elsewhere. 2~]* Terminates a 2~[*. It is undefined elsewhere. 2~{1str*~}* This is an iteration construct. The argument should be a list, which is used as a set of arguments as if for a recursive call to 2format*. The string 1str* is used repeatedly as the control string. Each iteration can absorb as many elements of the list as it likes; if 1str* uses up two arguments by itself, then two elements of the list get used up each time around the loop. If before any iteration step the list is empty, then the iteration is terminated. Also, if a prefix parameter 1n* is given, then there can be at most 1n* repetitions of processing of 1str*. Here are some simple examples: 3(format nil "Here it is:~{ ~S~}." '(a b c))* 3 => "Here it is: A B C."* 3(format nil "Pairs of things:~{ <~S,~S>~}." '(a 1 b 2 c 3))* 3 => "Pairs of things: ."* Using 2~^* as well, to terminate 1str* if no arguments remain, we can print a list with commas between the elements: 3(format nil "Elements: ~{~S~^, ~}." '(a b c))* 3 => "Elements: A, B, C."* 2~:{1str*~}* is similar, but the argument should be a list of sublists. At each repetition step one sublist is used as the set of arguments for processing 1str*; on the next repetition a new sublist is used, whether or not all of the last sublist had been processed. Example: 3(format nil "Pairs of things:~:{ <~S,~S>~}."* 3 '((a 1) (b 2) (c 3)))* 3 => "Pairs of things: ."* 2~@{1str*~}* is similar to 2~{1str*~}*, but instead of using one argument which is a list, all the remaining arguments are used as the list of arguments for the iteration. Example: 3(format nil "Pairs of things:~@{ <~S,~S>~}."* 3 'a 1 'b 2 'c 3)* 3 => "Pairs of things: ."* 2~:@{1str*~}* combines the features of 2~:{1str*~}* and 2~@{1str*~}*. All the remaining arguments are used, and each one must be a list. On each iteration the next argument is used as a list of arguments to 1str*. Example: 3(format nil "Pairs of things:~:@{ <~S,~S>~}."* 3 '(a 1) '(b 2) '(c 3))* 3 => "Pairs of things: ."* Terminating the repetition construct with 2~:}* instead of 2~}* forces 1str* to be processed at least once even if the initial list of arguments is null (however, it does not override an explicit prefix parameter of zero). If 1str* is empty, then an argument is used as 1str*. It must be a string, and precedes any arguments processed by the iteration. As an example, the following are equivalent: 3(apply #'format stream string args)* 3(format stream "~1{~:}" string args)* This uses 2string* as a formatting string. The 2~1{* says it must be processed at most once, and the 2~:}* says it must be processed at least once. Therefore it is processed exactly once, using 2args* as the arguments. As another example, the 2format* function itself uses 2format-error* (a routine internal to the 2format* package) to signal error messages, which in turn uses 2ferror*, which uses 2format* recursively. Now 2format-error* takes a string and arguments, just like 2format*, but also prints some additional information: if the control string in 2ctl-string* actually is a string (it might be a list--see below), then it prints the string and a little arrow showing where in the processing of the control string the error occurred. The variable 2ctl-index* points one character after the place of the error. 3(defun format-error (string &rest args)* 3 (if (stringp ctl-string)* 3 (ferror nil "~1{~:}~%~VT~%~3@T/"~A/"~%"* 3 string args (+ ctl-index 3) ctl-string)* 3 (ferror nil "~1{~:}" string args)))* This first processes the given string and arguments using 2~1{~:}*, then tabs a variable amount for printing the down-arrow, then prints the control string between double-quotes. The effect is something like this: 3(format t "The item is a ~[Foo~;Bar~;Loser~]." 'quux)* 3>>ERROR: The argument to the FORMAT "~[" command * 3 must be a number* 3 * 3 "The item is a ~[Foo~;Bar~;Loser~]."* 3... 2~}** Terminates a 2~{*. It is undefined elsewhere. 2~<* 2~1mincol*,1colinc*,1minpad*,1padchar*<1text*~>* justifies 1text* within a field at least 1mincol* wide. 1text* may be divided up into segments with 2~;*--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. The 2:* modifier causes spacing to be introduced before the first text segment; the 2@* modifier causes spacing to be added after the last. 1Minpad*, default 20*, is the minimum number of 1padchar* (default space) padding characters to be output between each segment. If the total width needed to satisfy these constraints is greater than 1mincol*, then 1mincol* is adjusted upwards in 1colinc* increments. 1colinc* defaults to 21*. 1mincol* defaults to 20*. For example, 3(format nil "~10") => "foo bar"* 3(format nil "~10:") => " foo bar"* 3(format nil "~10:@") => " foo bar "* 3(format nil "~10") => " foobar"* 3(format nil "~10:") => " foobar"* 3(format nil "~10@") => "foobar "* 3(format nil "~10:@") => " foobar "* 3(format nil "$~10,,,'*<~3f~>" 2.5902) => "$******2.59"* Note that 1text* may include format directives. The last example illustrates how the 2~<* directive can be combined with the 2~f* directive to provide more advanced control over the formatting of numbers. Here are some examples of the use of 2~^* within a 2~<* construct. 2~^* is explained in detail below, however the general idea is that it eliminates the segment in which it appears and all following segments if there are no more arguments. 3(format nil "~15<~S~;~^~S~;~^~S~>" 'foo)* 3=> " FOO"* 3(format nil "~15<~S~;~^~S~;~^~S~>" 'foo 'bar)* 3=> "FOO BAR"* 3(format nil "~15<~S~;~^~S~;~^~S~>" 'foo 'bar 'baz)* 3=> "FOO BAR BAZ"* The idea is that if a segment contains a 2~^*, and 2format* runs out of arguments, it just stops there instead of getting an error, and it as well as the rest of the segments are ignored. If the first clause of a 2~<* is terminated with 2~:;* instead of 2~;*, then it is used in a special way. All of the clauses are processed (subject to 2~^*, 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 segment for the first clause is output before the padded text. The first clause ought to contain a carriage return (2~%*). The first clause is always processed, and so any arguments it refers to will be used; the decision is whether to use the resulting segment of text, not whether to process the first clause. If the 2~:;* has a prefix parameter 1n*, then the padded text must fit on the current line with 1n* character positions to spare to avoid outputting the first clause's text. For example, the control string 3"~%;; ~{~<~%;; ~1:; ~S~>~^,~}.~%"* can be used to print a list of items separated by commas, without breaking items over line boundaries, and beginning each line with `2;; *'. The prefix parameter 21* in 2~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 2~:;* has a second prefix parameter, 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 3"~%;; ~{~<~%;; ~1,50:; ~S~>~^,~}.~%"* If the second argument is not specified, then 2format* sees whether the stream handles the 2:size-in-characters* message. If it does, then 2format* sends that message and uses the first returned value as the line length in characters. If it doesn't, 2format* uses 272.* as the line length. Rather than using this complicated syntax, one can often call the function 2format:print-list* (see 4(IOSYSTEM-3)The Format Function*). 2~>* Terminates a 2~<*. It is undefined elsewhere. 2~^* This is an escape construct. If there are no more arguments remaining to be processed, then the immediately enclosing 2~{* or 2~<* construct is terminated. If there is no such enclosing construct, then the entire formatting operation is terminated. In the 2~<* case, the formatting 1is* performed, but no more segments are processed before doing the justification. The 2~^* should appear only at the 1beginning* of a 2~<* clause, because it aborts the entire clause. 2~^* may appear anywhere in a 2~{* construct. If a prefix parameter is given, then termination occurs if the parameter is zero. (Hence 2~^* is the same as 2~#^*.) If two parameters are given, termination occurs if they are equal. If three are given, termination occurs if the second is between the other two in ascending order. Of course, this is useless if all the prefix parameters are constants; at least one of them should be a 2#* or a 2V* parameter. If 2~^* is used within a 2~:{* 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 2~:^*. 2~Q* An escape to arbitrary user-supplied code. 1arg* is called as a function; its arguments are the prefix parameters to 2~Q*, if any. 1args* can be passed to the function by using the 2V* prefix parameter. The function may output to 2*standard-output** and may look at the variables 2format:colon-flag* and 2format:atsign-flag*, which are 2t* or 2nil* to reflect the 2:* and 2@* modifiers on the 2~Q*. For example, 3(format t "~VQ" foo bar)* is a fancy way to say 3(funcall bar foo)* and discard the value. Note the reversal of order; the 2V* is processed before the 2Q*. 2~\* This begins a directive whose name is longer than one character. The name is terminated by another 2\* character. The following directives have names longer than one character and make use of the 2~\* mechanism as part of their operation. 2~\lozenged-string\* This is like 2~A* except when output is to a window, in which case the argument is printed in a small font inside a lozenge. 2~\lozenged-character\* This is like 2~C* except when output is to a window, in which case the argument is printed in a small font inside a lozenge if it has a character name, even if it is a formatting character or graphic character. 2~\date\* This expects an argument that is a universal time (see 4(DATETIME-0)Dates and Times*), and prints it as a date and time using 2time:print-universal-date*. Example: 3(format t "It is now ~\date\" (get-universal-time))* prints 3It is now Saturday the fourth of December, 1982; 4:00:32 am 2~\time\** This expects an argument that is a universal time (see 4(DATETIME-0)Dates and Times*), and prints it in a brief format using 2time:print-universal-time*. Example: 3(format t "It is now ~\time\" (get-universal-time))* prints 3It is now 12/04/82 04:01:38 2~\datime\** This prints the current time and date. It does not use an argument. It is equivalent to using the 2~\time\* directive with 2(time:get-universal-time)* as argument. 2~\time-interval\* This prints a time interval measured in seconds using the function 2time:print-interval-or-never*. Example: 3(format t "It took ~\time-interval\." 3601.)* prints 3It took 1 hour 1 second.* You can define your own directives. How to do this is not documented here; read the code. Names of user-defined directives longer than one character may be used if they are enclosed in backslashes (e.g. 2~4,3\GRAPH\*). (Note: 2format* also allows 1control-string* to be a list. If the list is a list of one element, which is a string, the string is simply printed. This is for the use of the 2format:outfmt* function below. The old feature wherein a more complex interpretation of this list was possible is now considered obsolete; use 2format:output* if you like using lists.) A condition instance can also be used as the 1control-string*. Then the 2:report* operation is used to print the condition instance; any other arguments are ignored. This way, you can pass a condition instance directly to any function that normally expects a format string and arguments. 3format:print-list* 1destination* 1element-format* 1list* &optional 1separator* 1start-line* 1tilde-brace-options* This function provides a simpler interface for the specific purpose of printing comma-separated lists with no list element split across two lines; see the description of the 2~:;* directive (4(IOSYSTEM-3)The Format Function*) to see the more complex way to do this within 2format*. 1destination* tells where to send the output; it can be 2t*, 2nil*, a 2string-nconc*'able string, or a stream, as with 2format*. 1element-format* is a 2format* control-string that tells how to print each element of 1list*; it is used as the body of a 2~{...~}* construct. 1separator*, which defaults to 2",* 2"* (comma, space) is a string which goes after each element except the last. 2format* control commands are not recommended in 1separator*. 1start-line*, which defaults to three spaces, is a 2format* control-string that is used as a prefix at the beginning of each line of output, except the first. 2format* control commands are allowed in 1separator*, but they should not swallow arguments from 1list*. 1tilde-brace-options* is a string inserted before the opening `2{*'; it defaults to the null string, but allows you to insert colon and/or atsign. The line-width of the stream is computed the same way that the 2~:;* command computes it; it is not possible to override the natural line-width of the stream. =Node: 4The Output Subsystem* =Text: 3THE OUTPUT SUBSYSTEM* The formatting functions associated with the 2format:output* subsystem allow you to do formatted output using Lisp-style control structure. Instead of a directive in a 2format* control string, there is one formatting function for each kind of formatted output. The calling conventions of most of the formatting functions are similar. The first argument is usually the datum to be output. The second argument is usually the minimum number of columns to use. The remaining arguments are keyword arguments. Most of the functions accept the keyword arguments 1padchar*, 1minpad* and 1tab-period*. 1padchar* is a character to use for padding. 1minpad* is a minimum number of padding characters to output after the data. 1tab-period* is the distance between allowable places to stop padding. To make the meaning of 1tab-period* clearer, if the value of 1tab-period* is 5, if the minimum size of the field is 10, and if the value of 1minpad* is 2, then a datum that takes 9 characters is padded out to 15 characters. The requirement to use at least two characters of padding means it can't fit into 10 characters, and the 1tab-period* of 5 means the next allowable stopping place is at 10+5 characters. The default values for 1minpad* and 1tab-period*, if they are not specified, are zero and one. The default value for 1padchar* is space. The formatting functions always output to 2*standard-output** and do not require an argument to specify the stream. The macro 2format:output* allows you to specify the stream or a string, just as 2format* does, and also makes it convenient to concatenate constant and variable output. 3format:output* 1stream* 1string-or-form...* 1Macro* Makes it convenient to intersperse arbitrary output operations with printing of constant strings. 2*standard-output** is bound to 1stream*, and each 1string-or-form* is processed in succession from left to right. If it is a string, it is printed; otherwise it is a form, which is evaluated for effect. Presumably the forms will send output to 2*standard-output**. If 1stream* is written as 2nil*, then the output is put into a string which is returned by 2format:output*. If 1stream* is written as 2t*, then the output goes to the prevailing value of 2*standard-output**. Otherwise 1stream* is a form, which must evaluate to a stream. Here is an example: 3(format:output t "FOO is " (prin1 foo) " now." (terpri))* Because 2format:output* is a macro, what matters about 1stream* is not whether it 1evaluates* to 2t* or 2nil*, but whether it is actually written as 2t* or 2nil*. 3format:outfmt* 1string-or-form...* 1Macro* Some system functions ask for a 2format* control string and arguments, to be printed later. If you wish to generate the output using the formatted output functions, you can use 2format:outfmt*, which produces a control argument that will eventually make 2format* print the desired output (this is a list whose one element is a string containing the output). A call to 2format:outfmt* can be used as the second argument to 2ferror*, for example: 3(ferror nil (format:outfmt "Foo is " (format:onum foo) * 3 " which is too large")) format:onum* 1number* &optional 1radix* 1minwidth* &key 1padchar* 1minpad* 1tab-period* 1signed* 1commas* Outputs 1number* in base 1radix*, padding to at least 1minwidth* columns and obeying the other padding options specified as described above. 1radix* can be a number, or it can be 2:roman*, 2:english*, or 2:ordinal*. The default 1radix* is 210.* (decimal). If 1signed* is non-2nil*, a 2+* sign is printed if the number is positive. If 1commas* is non-2nil*, a comma is printed every third digit in the customary way. These arguments are meaningful only with numeric radices. 3format:ofloat* 1number* &optional 1n-digits* 1force-exponential-notation* 1minwidth* &key 1padchar* 1minpad* 1tab-period* Outputs 1number* as a floating point number using 1n-digits* digits. If 1force-exponential-notation* is non-2nil*, then an exponent is always used. 1minwidth* and the padding options are interpreted as usual. 3format:ostring* 1string* &optional 1minwidth* &key 1padchar* 1minpad* 1tab-period* 1right-justify* Outputs 1string*, padding to at least 1minwidth* columns if 1minwidth* is not 2nil*, and obeying the other padding options specified as described above. Normally the data are left justified; any padding follows the data. If 1right-justify* is non-2nil*, the padding comes before the data. The amount of padding is not affected. The argument need not really be a string. Any Lisp object is allowed, and it is output with 2princ*. 3format:oprint* 1object* &optional 1minwidth* &key 1padchar* 1minpad* 1tab-period* 1right-justify* Prints 1object*, any Lisp object, padding to at least 1minwidth* columns if 1minwidth* is not 2nil*, and obeying the padding options specified as described above. Normally the data are left justified; any padding follows the data. If 1right-justify* is non-2nil*, the padding comes before the data. The amount of padding is not affected. The printing of the object is done with 2prin1*. 3format:ochar* 1character* &optional 1style* 1top-explain* 1minwidth* &key 1padchar* 1minpad* 1tab-period* Outputs 1character* in one of three styles, selected by the 1style* argument. 1minwidth* and the padding options control padding as usual. 2:read or nil* The character is printed using 2#\* or 2#/* so that it could be read back in. 2:editor* Output is in the style of `2Meta-Rubout*'. Non-printing characters, and the two printing characters Space and Altmode, are represented by their names. Other printing characters are printed directly. 2:brief* Brief prefixes such as `2C-*' and `2M-*' are used, rather than `2Control-*' or `2Meta-*'. Also, character names are used only if there are meta bits present. 2:lozenged* The output is the same as that of the 2:editor* style, but If the character is not a graphic character or if it has meta bits, and the stream supports the 2:display-lozenged-string* operation, that operation is used instead of 2:string-out* to print the text. On windows this operation puts the character name inside a lozenge. 2:sail* `3*', `3*', etc. are used to represent 2Control* and 2Meta*, and shorter names for characters are also used when possible. See 4(CHARSTR-1)Components of a Character*. 1top-explain* is useful with the 2:editor*, 2:brief* and 2:sail* styles. It says that any character that has to be typed using the Top or Greek keys should be followed by an explanation of how to type it. For example: `2 (Top-K)*' or `2 (Greek-a)*'. 3format:tab* 1mincol* &key 1padchar* 1minpad* 1tab-period* 1terpri* 1unit* Outputs padding at least until column 1mincol*. It is the only formatting function that bases its actions on the actual cursor position rather than the width of what is being output. The padding options 1padchar*, 1minpad*, and 1tab-period* are obeyed. Thus, at least the 1minpad* number of padding characters are output even if that goes past 1mincol*, and once past 1mincol*, padding can only stop at a multiple of 1tab-period* characters past 1mincol*. In addition, if the 1terpri* option is 2t*, then if column 1mincol* is passed, 2format:tab* starts a new line and indents it to 1mincol*. The 1unit* option specifies the units of horizontal position. The default is to count in units of characters. If 1unit* is specified as 2:pixel*, then the computation (and the argument 1mincol* and the 1minpad* and 1tab-period* options) are in units of pixels. 3format:pad* 1(minwidth* &key 1padchar* 1minpad* 1tab-period...)* 1body...* 1Macro* 2format:pad* is used for printing several items in a fixed amount of horizontal space, padding between them to use up any excess space. Each of the 1body* forms prints one item. The padding goes between items. The entire 2format:pad* always uses at least 1minwidth* columns; any columns that the items don't need are distributed as padding between the items. If that isn't enough space, then more space is allocated in units controlled by the 1tab-period* option until there is enough space. If it's more than enough, the excess is used as padding. If the 1minpad* option is specified, then at least that many pad characters must go between each pair of items. Padding goes only between items. If you want to treat several actual pieces of output as one item, put a 2progn* around them. If you want padding before the first item or after the last, as well as between the items, include a dummy item 2nil* at the beginning or the end. If there is only one item, it is right justified. One item followed by 2nil* is left-justified. One item preceded and followed by 2nil* is centered. Therefore, 2format:pad* can be used to provide the usual padding options for a function that does not provide them itself. 3format:plural* 1number* 1singular* &optional 1plural* Outputs either the singular or the plural form of a word depending on the value of 1number*. The singular is used if and only if 1number* is 1. 1singular* specifies the singular form of the word. 2string-pluralize* is used to compute the plural, unless 1plural* is explicitly specified. It is often useful for 1number* to be a value returned by 2format:onum*, which returns its argument. For example: 3(format:plural (format:onum n-frobs) " frob")* prints "1 frob" or "2 frobs". 3format:breakline* 1linel* 1print-if-terpri* 1print-always...* 1Macro* Goes to the next line if there is not enough room for something to be output on the current line. The 1print-always* forms print the text which is supposed to fit on the line. 1linel* is the column before which the text must end. If it doesn't end before that column, then 2format:breakline* moves to the next line and executes the 1print-if-terpri* form before doing the 1print-always* forms. Constant strings are allowed as well as forms for 1print-if-terpri* and 1print-always*. A constant string is just printed. To go to a new line unconditionally, simply call 2terpri*. Here is an example that prints the elements of a list, separated by commas, breaking lines between elements when necessary. 3(defun pcl (list linel)* 3 (do ((l list (cdr l))) ((null l))* 3 (format:breakline linel " "* 3 (princ (car l))* 3 (and (cdr l) (princ ", ")))))