1
@node Streams and Reading, Special Forms and Functions, Lists, Top
2
@chapter Streams and Reading
4
@defun MAKE-ECHO-STREAM (input-stream output-stream)
7
Returns a bidirectional stream which gets its input from INPUT-STREAM and
8
sends its output to OUTPUT-STREAM. In addition, all input is echoed to
16
The current readtable.
21
@defun LOAD (filename &key (verbose *load-verbose*) (print nil) (if-does-not-exist :error))
24
Loads the file named by FILENAME into GCL.
29
@defun OPEN (filename &key (direction :input) (element-type 'string-char) (if-exists :error) (if-does-not-exist :error))
32
Opens the file specified by FILENAME, which may be a string, a pathname,
33
or a stream. Returns a stream for the open file.
34
DIRECTION is :INPUT, :OUTPUT, :IO or :PROBE.
35
ELEMENT-TYPE is STRING-CHAR, (UNSIGNED-BYTE n),
36
UNSIGNED-BYTE, (SIGNED-BYTE n), SIGNED-BYTE, CHARACTER, BIT, (MOD n), or
38
IF-EXISTS is :ERROR, :NEW-VERSION, :RENAME,
39
:RENAME-AND-DELETE, :OVERWRITE, :APPEND, :SUPERSEDE, or NIL.
40
IF-DOES-NOT-EXIST is :ERROR, :CREATE, or NIL.
42
If FILENAME begins with a vertical pipe sign: '|' then the resulting
43
stream is actually a one way pipe. It will be open for reading
44
or writing depending on the direction given. The rest
45
of FILENAME in this case is passed to the /bin/sh command. See
46
the posix description of popen for more details.
48
(setq pipe (open "| wc < /tmp/jim"))
49
(format t "File has ~%d lines" (read pipe))
57
The radix in which the GCL printer prints integers and rationals.
58
The value must be an integer from 2 to 36, inclusive.
63
@defun MAKE-STRING-INPUT-STREAM (string &optional (start 0) (end (length string)))
66
Returns an input stream which will supply the characters of String between
67
Start and End in order.
72
@defun PPRINT (object &optional (stream *standard-output*))
75
Pretty-prints OBJECT. Returns OBJECT. Equivalent to
76
(WRITE :STREAM STREAM :PRETTY T)
77
The SI:PRETTY-PRINT-FORMAT property N (which must be a non-negative integer)
78
of a symbol SYMBOL controls the pretty-printing of form
79
(SYMBOL f1 ... fN fN+1 ... fM)
80
in such a way that the subforms fN+1, ..., fM are regarded as the 'body' of
81
the entire form. For instance, the property value of 2 is initially given
87
@defvar *READ-DEFAULT-FLOAT-FORMAT*
89
The floating-point format the GCL reader uses when reading floating-point
90
numbers that have no exponent marker or have e or E for an exponent marker.
91
Must be one of SHORT-FLOAT, SINGLE-FLOAT, DOUBLE-FLOAT, and LONG-FLOAT.
96
@defun READ-PRESERVING-WHITESPACE (&optional (stream *standard-input*) (eof-error-p t) (eof-value nil) (recursive-p nil))
99
Reads an object from STREAM, preserving the whitespace that followed the
108
Returns T if X is a stream object; NIL otherwise.
114
@defun SET-DISPATCH-MACRO-CHARACTER (disp-char sub-char function &optional (readtable *readtable*))
117
Causes FUNCTION to be called when the DISP-CHAR followed by SUB-CHAR is
123
@deffn {Macro} WITH-OUTPUT-TO-STRING
128
(with-output-to-string (var [string]) @{decl@}* @{form@}*)
131
Binds VAR to a string output stream that puts characters into STRING, which
132
defaults to a new string. The stream is automatically closed on exit and
133
the string is returned.
138
@defun FILE-LENGTH (file-stream)
141
Returns the length of the specified file stream.
148
The case in which the GCL printer should print ordinary symbols.
149
The value must be one of the keywords :UPCASE, :DOWNCASE, and :CAPITALIZE.
154
@defun PRINT (object &optional (stream *standard-output*))
157
Outputs a newline character, and then prints OBJECT in the mostly readable
158
representation. Returns OBJECT. Equivalent to
159
(PROGN (TERPRI STREAM) (WRITE OBJECT :STREAM STREAM :ESCAPE T)).
164
@defun SET-MACRO-CHARACTER (char function &optional (non-terminating-p nil) (readtable *readtable*))
167
Causes CHAR to be a macro character that, when seen by READ, causes FUNCTION
173
@defun FORCE-OUTPUT (&optional (stream *standard-output*))
176
Attempts to force any buffered output to be sent.
181
@defvar *PRINT-ARRAY*
183
Whether the GCL printer should print array elements.
188
@defun STREAM-ELEMENT-TYPE (stream)
191
Returns a type specifier for the kind of object returned by STREAM.
196
@defun WRITE-BYTE (integer stream)
199
Outputs INTEGER to the binary stream STREAM. Returns INTEGER.
204
@defun MAKE-CONCATENATED-STREAM (&rest streams)
207
Returns a stream which takes its input from each of the STREAMs in turn,
208
going on to the next at end of stream.
213
@defun PRIN1 (object &optional (stream *standard-output*))
216
Prints OBJECT in the mostly readable representation. Returns OBJECT.
217
Equivalent to (WRITE OBJECT :STREAM STREAM :ESCAPE T).
222
@defun PRINC (object &optional (stream *standard-output*))
225
Prints OBJECT without escape characters. Returns OBJECT. Equivalent to
226
(WRITE OBJECT :STREAM STREAM :ESCAPE NIL).
231
@defun CLEAR-OUTPUT (&optional (stream *standard-output*))
234
Clears the output stream STREAM.
239
@defun TERPRI (&optional (stream *standard-output*))
242
Outputs a newline character.
247
@defun FINISH-OUTPUT (&optional (stream *standard-output*))
250
Attempts to ensure that all output sent to STREAM has reached its destination,
251
and only then returns.
256
@deffn {Macro} WITH-OPEN-FILE
261
(with-open-file (stream filename @{options@}*) @{decl@}* @{form@}*)
264
Opens the file whose name is FILENAME, using OPTIONs, and binds the variable
265
STREAM to a stream to/from the file. Then evaluates FORMs as a PROGN.
266
The file is automatically closed on exit.
271
@deffn {Special Form} DO
276
(do (@{(var [init [step]])@}*) (endtest @{result@}*)
277
@{decl@}* @{tag | statement@}*)
280
Creates a NIL block, binds each VAR to the value of the corresponding INIT,
281
and then executes STATEMENTs repeatedly until ENDTEST is satisfied. After
282
each iteration, assigns to each VAR the value of the corresponding STEP. When
283
ENDTEST is satisfied, evaluates RESULTs as a PROGN and returns the value(s) of
284
the last RESULT (or NIL if no RESULTs are supplied). Performs variable
285
bindings and assignments all at once, just like LET and PSETQ do.
290
@defun READ-FROM-STRING (string &optional (eof-error-p t) (eof-value nil) &key (start 0) (end (length string)) (preserve-whitespace nil))
293
Reads an object from STRING.
298
@defun WRITE-STRING (string &optional (stream *standard-output*) &key (start 0) (end (length string)))
301
Outputs STRING and returns it.
306
@defvar *PRINT-LEVEL*
308
How many levels deep the GCL printer should print. Unlimited if NIL.
313
@defvar *PRINT-RADIX*
315
Whether the GCL printer should print the radix indicator when printing
316
integers and rationals.
321
@defun Y-OR-N-P (&optional (format-string nil) &rest args)
324
Asks the user a question whose answer is either 'Y' or 'N'. If FORMAT-STRING
325
is non-NIL, then FRESH-LINE operation is performed, a message is printed as
326
if FORMAT-STRING and ARGs were given to FORMAT, and then a prompt
327
"(Y or N)" is printed. Otherwise, no prompt will appear.
332
@defun MAKE-BROADCAST-STREAM (&rest streams)
335
Returns an output stream which sends its output to all of the given streams.
340
@defun READ-CHAR (&optional (stream *standard-input*) (eof-error-p t) (eof-value nil) (recursive-p nil))
343
Reads a character from STREAM.
348
@defun PEEK-CHAR (&optional (peek-type nil) (stream *standard-input*) (eof-error-p t) (eof-value nil) (recursive-p nil))
351
Peeks at the next character in the input stream STREAM.
356
@defun OUTPUT-STREAM-P (stream)
359
Returns non-nil if STREAM can handle output operations; NIL otherwise.
366
The query I/O stream.
373
The radix that the GCL reader reads numbers in.
378
@deffn {Macro} WITH-OPEN-STREAM
383
(with-open-stream (var stream) @{decl@}* @{form@}*)
386
Evaluates FORMs as a PROGN with VAR bound to the value of STREAM. The stream
387
is automatically closed on exit.
392
@deffn {Macro} WITH-INPUT-FROM-STRING
397
(with-input-from-string (var string @{keyword value@}*) @{decl@}*
401
Binds VAR to an input stream that returns characters from STRING and evaluates
402
the FORMs. The stream is automatically closed on exit. Allowed keywords are
403
:INDEX, :START, and :END.
408
@defun CLEAR-INPUT (&optional (stream *standard-input*))
416
@defvar *TERMINAL-IO*
418
The terminal I/O stream.
423
@defun LISTEN (&optional (stream *standard-input*))
426
Returns T if a character is available on STREAM; NIL otherwise. This function
427
does not correctly work in some versions of GCL because of the lack of such
428
mechanism in the underlying operating system.
433
@defun MAKE-PATHNAME (&key (defaults (parse-namestring "" (pathname-host *default-pathname-defaults*))) (host (pathname-host defaults)) (device (pathname-device defaults)) (directory (pathname-directory defaults)) (name (pathname-name defaults)) (type (pathname-type defaults)) (version (pathname-version defaults)))
436
Create a pathname from HOST, DEVICE, DIRECTORY, NAME, TYPE and VERSION.
441
@defun PATHNAME-TYPE (pathname)
444
Returns the type slot of PATHNAME.
449
@defvar *PRINT-GENSYM*
451
Whether the GCL printer should prefix symbols with no home package
457
@defun READ-LINE (&optional (stream *standard-input*) (eof-error-p t) (eof-value nil) (recursive-p nil))
460
Returns a line of text read from STREAM as a string, discarding the newline
463
Note that when using line at a time input under unix,
464
input forms will always be followed by a #\newline. Thus if you
471
the empty string will be returned. After lisp reads the (read-line)
472
it then invokes (read-line). This happens before it does anything
473
else and so happens before the newline character immediately following
474
(read-line) has been read. Thus read-line immediately encounters a
475
#\newline and so returns the empty string. If there had been other
476
characters before the #\newline it would have been different:
478
>(read-line) how are you
482
If you want to throw away "" input, you can do that with
485
(sloop::sloop while (equal (setq input (read-line)) ""))
487
You may also want to use character at a time input, but that
488
makes input editing harder.
491
GCL (GNU Common Lisp) Version(1.1.2) Mon Jan 9 12:58:22 MET 1995
492
Licensed under GNU Public Library License
493
Contains Enhancements by W. Schelter
495
>(let ((ifilename nil))
496
(format t "~%Input file name: ")
497
(setq ifilename (read-line)))
498
Input file name: /tmp/myfile
508
@defun WRITE-TO-STRING (object &key (escape *print-escape*) (radix *print-radix*) (base *print-base*) (circle *print-circle*) (pretty *print-pretty*) (level *print-level*) (length *print-length*) (case *print-case*) (array *print-array*) (gensym *print-gensym*))
511
Returns as a string the printed representation of OBJECT in the specified
512
mode. See the variable docs of *PRINT-...* for the mode.
520
Returns T if X is a pathname object; NIL otherwise.
525
@defun READTABLEP (x)
528
Returns T if X is a readtable object; NIL otherwise.
533
@defun READ (&optional (stream *standard-input*) (eof-error-p t) (eof-value nil) (recursivep nil))
536
Reads in the next object from STREAM.
541
@defun NAMESTRING (pathname)
544
Returns the full form of PATHNAME as a string.
549
@defun UNREAD-CHAR (character &optional (stream *standard-input*))
552
Puts CHARACTER back on the front of the input stream STREAM.
557
@defun CLOSE (stream &key (abort nil))
560
Closes STREAM. A non-NIL value of :ABORT indicates an abnormal termination.
565
@defvar *PRINT-LENGTH*
567
How many elements the GCL printer should print at each level of nested data
568
object. Unlimited if NIL.
573
@defun SET-SYNTAX-FROM-CHAR (to-char from-char &optional (to-readtable *readtable*) (from-readtable nil))
576
Makes the syntax of TO-CHAR in TO-READTABLE be the same as the syntax of
577
FROM-CHAR in FROM-READTABLE.
582
@defun INPUT-STREAM-P (stream)
585
Returns non-NIL if STREAM can handle input operations; NIL otherwise.
593
Turns X into a pathname. X may be a string, symbol, stream, or pathname.
598
@defun FILE-NAMESTRING (pathname)
601
Returns the written representation of PATHNAME as a string.
606
@defun MAKE-DISPATCH-MACRO-CHARACTER (char &optional (non-terminating-p nil) (readtable *readtable*))
609
Causes the character CHAR to be a dispatching macro character in READTABLE.
614
@defvar *STANDARD-OUTPUT*
616
The default output stream used by the GCL printer.
621
@defun MAKE-TWO-WAY-STREAM (input-stream output-stream)
624
Returns a bidirectional stream which gets its input from INPUT-STREAM and
625
sends its output to OUTPUT-STREAM.
630
@defvar *PRINT-ESCAPE*
632
Whether the GCL printer should put escape characters whenever appropriate.
637
@defun COPY-READTABLE (&optional (from-readtable *readtable*) (to-readtable nil))
640
Returns a copy of the readtable FROM-READTABLE. If TO-READTABLE is non-NIL,
641
then copies into TO-READTABLE. Otherwise, creates a new readtable.
646
@defun DIRECTORY-NAMESTRING (pathname)
649
Returns the directory part of PATHNAME as a string.
654
@defun TRUENAME (pathname)
657
Returns the pathname for the actual file described by PATHNAME.
662
@defvar *READ-SUPPRESS*
664
When the value of this variable is NIL, the GCL reader operates normally.
665
When it is non-NIL, then the reader parses input characters but much of what
666
is read is not interpreted.
671
@defun GET-DISPATCH-MACRO-CHARACTER (disp-char sub-char &optional (readtable *readtable*))
674
Returns the macro-character function for SUB-CHAR under DISP-CHAR.
679
@defun PATHNAME-DEVICE (pathname)
682
Returns the device slot of PATHNAME.
687
@defun READ-CHAR-NO-HANG (&optional (stream *standard-input*) (eof-error-p t) (eof-value nil) (recursive-p nil))
690
Returns the next character from STREAM if one is available; NIL otherwise.
695
@defun FRESH-LINE (&optional (stream *standard-output*))
698
Outputs a newline if it is not positioned at the beginning of a line. Returns
699
T if it output a newline; NIL otherwise.
704
@defun WRITE-CHAR (char &optional (stream *standard-output*))
707
Outputs CHAR and returns it.
712
@defun PARSE-NAMESTRING (thing &optional host (defaults *default-pathname-defaults*) &key (start 0) (end (length thing)) (junk-allowed nil))
715
Parses a string representation of a pathname into a pathname. HOST
721
@defun PATHNAME-DIRECTORY (pathname)
724
Returns the directory slot of PATHNAME.
729
@defun GET-MACRO-CHARACTER (char &optional (readtable *readtable*))
732
Returns the function associated with CHAR and, as a second value, returns
733
the non-terminating-p flag.
738
@defun FORMAT (destination control-string &rest arguments)
741
Provides various facilities for formatting output.
742
DESTINATION controls where the result will go. If DESTINATION is T, then
743
the output is sent to the standard output stream. If it is NIL, then the
744
output is returned in a string as the value of the call. Otherwise,
745
DESTINATION must be a stream to which the output will be sent.
747
CONTROL-STRING is a string to be output, possibly with embedded
748
formatting directives, which are flagged with the escape character
749
"~". Directives generally expand into additional text to be output,
750
usually consuming one or more of ARGUMENTs in the process.
754
A few useful directives are:
757
~A, ~nA, ~n@@A Prints one argument as if by PRINC
758
~S, ~nS, ~n@@S Prints one argument as if by PRIN1
759
~D, ~B, ~O, ~X Prints one integer in decimal, binary, octal, and hexa
764
where n is the minimal width of the field in which the object is printed.
765
~nA and ~nS put padding spaces on the right; ~n@@A and ~n@@S put on the left.
768
~R is for printing numbers in various formats.
770
~nR prints arg in radix n.
771
~R prints arg as a cardinal english number: two
772
~:R prints arg as an ordinal english number: third
773
~@@R prints arg as an a Roman Numeral: VII
774
~:@@R prints arg as an old Roman Numeral: IIII
776
~C prints a character.
777
~:C represents non printing characters by their pretty names,eg Space
778
~@@C uses the #\ syntax to allow the reader to read it.
780
~F prints a floating point number arg.
781
The full form is ~w,d,k,overflowchar,padcharF
782
w represents the total width of the printed representation (variable if
784
d the number of fractional digits to display
785
(format nil "~,2f" 10010.0314) --> "10010.03"
786
k arg is multiplied by 10^k before printing it as a decimal number.
787
overflowchar width w characters copies of the overflow character will
788
be printed. eg(format t "X>~5,2,,'?F<X" 100.034) --> X>?????<X
789
padchar is the character to pad with
790
(format t "X>~10,2,1,'?,'bF<X" 100.03417) -->X>bbb1000.34<X
791
@@ makes + sign print if the arg is positive
795
if arg is not nil, then it is retained as an arg for further printing,
796
otherwise it is used up
799
(format nil "~@@[x = ~d~]~a" nil 'bil) --> "BIL"
800
(format nil "~@@[x = ~d ~]~a" 8) --> "x = 8 BIL"
806
@defun PATHNAME-NAME (pathname)
809
Returns the name slot of PATHNAME.
814
@defun MAKE-STRING-OUTPUT-STREAM ()
817
Returns an output stream which will accumulate all output given it for
818
the benefit of the function GET-OUTPUT-STREAM-STRING.
823
@defun MAKE-SYNONYM-STREAM (symbol)
826
Returns a stream which performs its operations on the stream which is the
827
value of the dynamic variable named by SYMBOL.
832
@defvar *LOAD-VERBOSE*
834
The default for the VERBOSE argument to LOAD.
839
@defvar *PRINT-CIRCLE*
841
Whether the GCL printer should take care of circular lists.
846
@defvar *PRINT-PRETTY*
848
Whether the GCL printer should pretty-print. See the function doc of PPRINT
849
for more information about pretty-printing.
854
@defun FILE-WRITE-DATE (file)
857
Returns the time at which the specified file is written, as an integer in
858
universal time format. FILE may be a string or a stream.
863
@defun PRIN1-TO-STRING (object)
866
Returns as a string the printed representation of OBJECT in the mostly
867
readable representation.
868
Equivalent to (WRITE-TO-STRING OBJECT :ESCAPE T).
873
@defun MERGE-PATHNAMES (pathname &optional (defaults *default-pathname-defaults*) default-version)
876
Fills in unspecified slots of PATHNAME from DEFAULTS. DEFAULT-VERSION
882
@defun READ-BYTE (stream &optional (eof-error-p t) (eof-value nil))
885
Reads the next byte from STREAM.
890
@defun PRINC-TO-STRING (object)
893
Returns as a string the printed representation of OBJECT without escape
894
characters. Equivalent to
895
(WRITE-TO-STRING OBJECT :ESCAPE NIL).
900
@defvar *STANDARD-INPUT*
902
The default input stream used by the GCL reader.
907
@defun PROBE-FILE (file)
910
Returns the truename of file if the file exists.
911
Returns NIL otherwise.
916
@defun PATHNAME-VERSION (pathname)
919
Returns the version slot of PATHNAME.
924
@defun WRITE-LINE (string &optional (stream *standard-output*) &key (start 0) (end (length string)))
927
Outputs STRING and then outputs a newline character. Returns STRING.
932
@defun WRITE (object &key (stream *standard-output*) (escape *print-escape*) (radix *print-radix*) (base *print-base*) (circle *print-circle*) (pretty *print-pretty*) (level *print-level*) (length *print-length*) (case *print-case*) (array *print-array*) (gensym *print-gensym*))
935
Prints OBJECT in the specified mode. See the variable docs of *PRINT-...*
941
@defun GET-OUTPUT-STREAM-STRING (stream)
944
Returns a string of all the characters sent to STREAM made by
945
MAKE-STRING-OUTPUT-STREAM since the last call to this function.
950
@defun READ-DELIMITED-LIST (char &optional (stream *standard-input*) (recursive-p nil))
953
Reads objects from STREAM until the next character after an object's
954
representation is CHAR. Returns a list of the objects read.
959
@defun READLINE-ON ()
962
Begins readline command editing mode when possible. In addition to
963
the basic readline editing features, command word completion is
964
implemented according to the following scheme:
968
pkg -- an optional package specifier. Defaults to the current
969
package. The symbols in this package and those in the packages in
970
this package's use list will be searched.
972
:[:] -- an optional internal/external specifier. Defaults to
973
external. The keyword package is denoted by a single colon at the
974
beginning of the token. Only symbols of this type will be searched
977
txt -- a string. Symbol names beginning with this string are
978
completed. The comparison is case insensitive.
983
@defun READLINE-OFF ()
986
Disables readline command editing mode.
990
@defvar *READLINE-PREFIX*
993
A string implicitly prepended to input text for use in readline
994
command completion. If this string contains one or more colons, it is
995
used to specify the default package and internal/external setting for
996
searched symbols in the case that the supplied text itself contains no
997
explicit package specification. If this string contains characters
998
after the colon(s), or contains no colons at all, it is treated as a
999
symbol name prefix. In this case, the prefix is matched first, then
1000
the supplied text, and the completion returned is relative to the
1001
supplied text itself, i.e. contains no prefix. For example, the
1002
setting ``maxima::$'' will complete input text ``int'' according to
1003
the internal symbols in the maxima package of the form
1004
``maxima::$int...'', and return suggestions to the user of the form
added
removed
info/io.texi
