REDUCE

10.3 Functions for Printing

10.3.1 Basic Printing

(prin1 ITM:any): ITM:any expr

(channelprin1 CHAN:io-channel ITM:any): ITM:any expr
Channelprin1 is the basic printing function. For well-formed, non-circular structures, the result can be parsed by the function read.

(prin2 ITM:any): ITM:any expr

(channelprin2 CHAN:io-channel ITM:any): ITM:any expr
Channelprin2 is similar to channelprin1, except that strings are printed without the surrounding double quotes, and delimiters within ids are not preceded by the escape character.

The following example illustrates the difference between prin1 and prin2.

ARGUMENT     PRIN1        PRIN2  
 
A!%WORD      A!%WORD      A%WORD  
"STRING"     "STRING"     STRING

(print U:any): U:any expr

(channelprint CHAN:io-channel U:any): U:any expr
Display U using channelprin1 and then terminate the line using channelterpri.

10.3.2 Whitespace Printing Functions

(terpri): nil expr

(channelterpri CHAN:io-channel): nil expr
Write an end of line character. The number of characters output on the current line (that which is referenced by channelposn), is defined to be zero and the number of lines output on the current page (that which is referenced by channelposn), is incremented.

(spaces N:integer): nil expr

(channelspaces CHAN:io-channel N:integer): nil expr
N spaces are written.

(tab N:integer): nil expr

(channeltab CHAN:io-channel N:integer): nil expr
Move to column N

(channelspaces ch (- N (channelposn ch)))

If the position on the current output line is past column N then channelterpri is called before moving to column N.

10.3.3 Formatted Printing

(printf FORMAT:string [ARGS:any]): nil expr

(channelprintf CHAN:io-channel FORMAT:string [ARGS:any]):nil expr
Channelprintf is a simple routine for formatted printing. The FORMAT is a string. The characters of this string are printed unless a a interpret and print the other arguments to channelprintf. The following format characters are currently supported.
%b

The next argument is assumed to be an integer, it is passed to spaces.

%c

The next argument should be a single character, it is printed by a call on writechar.

%d

Print the next argument as a decimal integer.

%e

The next argument is evaluated by a call on eval.

%f

Print an end-of-line character if not at the beginning of the output line (does not use a matching argument).

%l

Print the next argument using print2l, this is the same as %w except that lists are printed without the top level pair of parenthesis. The empty list is printed as a blank.

%n

Print end-of-line character (does not use a matching argument).

%o

Print the next argument as an octal integer.

%p

Print the next argument using prin1.

%p

Print the next argument using prin1.

%r

Print the next argument using errprin, the result is the same as %p except that a surrounding pair of quotes are also printed.

%s

The next argument is assumed to be a string, the surrounding double quotes are not printed.

%t

The next argument is assumed to be an integer, it is passed to tab.

%w

Print the next argument using prin2.

%x

Print the next argument as a hexadecimal integer.

If the character following % is not either one of the above or another %, it causes an error. Thus, to include a % in the format to be printed, use %.

There is no checking for correspondence between the number of arguments that FORMAT expects and the number given. If the number given is less than the number in the FORMAT string, garbage will be inserted for the missing arguments. If the number given is greater than the number in the FORMAT string, then the extra ones are ignored.

(prettyprint U:form): U:form expr
Prettyprints U.

10.3.4 The Fundamental Printing Function

(writechar CH:character): character expr
(channelwritechar CHANNEL:io-channel
CH:character): character expr
Write one character to the device specified by CHANNEL. All output is defined in terms of this function. The number of characters output on the current line (that which is referenced by channelposn), and the number of lines output on the current page (that which is referenced by channellposn), are updated. Each channel specifies an output function, it is this function that is applied to CHANNEL and CH to actually write the character.

10.3.5 Additional Printing Functions

(prin2l L:any): L:any, nil expr
Prin2, except that a list is printed without the top level parentheses. If L is a pair then the return value is nil, otherwise the return value will be L.

(prin2t X:any): any expr
(channelprin2t CHAN:io-channel X:any): any expr
Output X using channelprin2 and terminate line with channelterpri.
(princ ITM:any): ITM:any expr
(channelprinc CHAN:io-channel ITM:any): ITM:any expr
Same function as channelprin2.
(errprin U:any): None Returned expr
Prin1 with special quotes to highlight U.
(errorprintf FORMAT:string [ARGS:any]): nil expr
Errorprintf is similar to printf, except that errout* is used in place of the currently selected output channel. Channelterpri is called before and after printing if the line position is greater than zero.

(eject): nil expr
(channeleject CHAN:io-channel): nil expr
Skip to top of next output page.

10.3.6 Printing Status and Mode

For information on directing various kinds of output see the section on channels.

outputbase* = [Initially: 10] global
   
This fluid can be set to control the radix in which integers are printed out. If the radix is not 10, the radix is given before a sharp sign.
    1 lisp> 16  
    16  
    2 lisp> (setq outputbase⋆ 8)  
    8#10  
    3 lisp> 16  
    8#20

(posn): integer expr

(channelposn CHAN:io-channel): integer expr
Returns number of characters output on the current line of this channel.

(lposn): integer expr

(channellposn CHAN:io-channel): integer expr
Returns number of lines output on this page of this channel.

(linelength LEN:{integer, nil}): integer expr

(channellinelength CHAN:io-channel LEN: {integer, nil}): integer expr
For each channel there is a restriction on the length of output lines. If LEN is nil then the value returned will be the current maximum length. If LEN is an integer greater than zero then it will become the new maximum. However, if the argument is zero there will be no restrictions on the size of the output lines. The following example illustrates how this length is used. PSL uses a similar function to apply output functions like prin1.
    (de check-line-length (length ch fn token)  
      (when (and (> (+ (channelposn ch) length)  
                    (channellinelength ch nil))  
                 (> (channellinelength ch nil) 0))  
        (channelwritechar ch (char eol)))  
      (idapply fn (list ch token)))

The fluid variables PrinLevel and PrinLength allow the user to control how deep the printer will print and how many elements at a given level the printer will print. This is useful for objects which are very large or deep. These variables affect the functions prin1, prin2, princ, print, and printf (and the corresponding Channel functions).

prinlevel = [Initially: nil] global
   
Controls how many levels deep a nested data object will print. If PrinLevel is nil, then no control is exercised. Otherwise the value should be an integer. An object to be printed is at level 0.

prinlength = [Initially: nil] global
   
Controls how many elements at a given level are printed. A value of nil indicates that there be no limit to the number of components printed. Otherwise the value of PrinLength should be an integer.