make-synonym-stream

make-synonym-stream Function

Syntax:

make-synonym-stream symbol → synonym-stream

Arguments and Values:

symbol—a symbol that names a dynamic variable.

synonym-stream—a synonym stream.

Description:

Returns a synonym stream whose synonym stream symbol is symbol.

Examples:

(setq a-stream (make-string-input-stream "a-stream") 
      b-stream (make-string-input-stream "b-stream")) 
→ #<String Input Stream> 
(setq s-stream (make-synonym-stream ’c-stream)) 
→ #<SYNONYM-STREAM for C-STREAM> 
(setq c-stream a-stream) 
→ #<String Input Stream> 
(read s-stream) → A-STREAM 
(setq c-stream b-stream) 
→ #<String Input Stream> 
(read s-stream) → B-STREAM 

Exceptional Situations:

Should signal type-error if its argument is not a symbol.

See Also:

Section 21.1 (Stream Concepts)

Expanded Reference: make-synonym-stream

Basic Usage

make-synonym-stream creates a stream that delegates all operations to whatever stream is currently the value of a given dynamic variable.

(defvar *my-stream* (make-string-input-stream "first"))

(let ((syn (make-synonym-stream '*my-stream*)))
  (read syn))
=> FIRST

Dynamic Rebinding

Changing the value of the symbol redirects the synonym stream to a different target.

(defvar *target* nil)

(let ((syn (make-synonym-stream '*target*)))
  (setq *target* (make-string-input-stream "a-stream"))
  (let ((r1 (read syn)))
    (setq *target* (make-string-input-stream "b-stream"))
    (let ((r2 (read syn)))
      (list r1 r2))))
=> (A-STREAM B-STREAM)

Output Through a Synonym Stream

Synonym streams work for output as well.

(defvar *out-target* nil)

(let ((syn (make-synonym-stream '*out-target*))
      (actual (make-string-output-stream)))
  (setq *out-target* actual)
  (write-string "routed output" syn)
  (get-output-stream-string actual))
=> "routed output"

Retrieving the Symbol

Use synonym-stream-symbol to find out which symbol the stream is bound to.

(let ((syn (make-synonym-stream '*standard-input*)))
  (synonym-stream-symbol syn))
=> *STANDARD-INPUT*