3. Input and Output

3.1 Read macros
3.2 Input and Output Functions
3.3 Network Streams
3.4 CLOS Streams

3.1 Read macros

#P"

#"string" reads a pathname. #"string" is equivalent to (pathname "string").

#$

#$integer reads a random state. #$integer is equivalent to (make-random-state integer).

The # macro '#,' works as described in [see section Steele:84], only if it is included in a constant object. The forms immediately after `#,' below will be evaluated when the compiled code is loaded.

'#,x '(a b c (d #,e f) g) #(1 2 3 #,(+ a b c) 5 6) #C(0.0 #,(exp 1))

Otherwise, the effect of using '#,' is unpredictable. Note that, when interpreted code is loaded, '#,' has the same effect as the # macro '#.'.

3.2 Input and Output Functions

The input and output functions of ECL almost follow the definitions in Chapter 22 of [see section Steele:84]. Most of the differences come from the fact that, in ECL, input from the terminal is always in line mode and binary I/O is not supported.

In ECL, *terminal-io* is a two-way stream from the standard input and to the standard output. The echoing to the terminal is performed by the underlying operating system. In particular, when a disk file is assigned to the standard output, nothing will be echoed at the terminal.

Those functions that deviate from the definitions in [see section Steele:84] are listed below.

Function: load {pathname &key

If pathname does not specify the filetype of the input file, then load uses the association list si::*load-search-list* to find out a suitable filetype and the function to load it. Typically, this search list is made of the elements .fas, .lsp and .lisp, in this order. If everything fails, a file without filetype will be loaded.

Function: open {}

Streams can only have element type base-char, (signed-byte 8) and (unsigned-byte 8). The :external-format is always :default.

Function: close {}

The keyword variable :abort is always ignored.

Function: listen {}

This routine requires some low level functions which are not available on all platforms (For instance on Windows). When ECL is not able to determine whether a stream is interactive, listen returns true unless an end of file has been previously detected.

Function: clear-input {}

The functions clear-input and clear-output do nothing.

Function: read-char-no-hang {}

read-char-no-hang is equivalent to read-char.

The functions princ, write-char and write-byte do not always flush the stream. The stream is flushed when

1. a newline character is written, or

2. the input from the terminal is requested in the case that these functions operate on *terminal-io*

3.3 Network Streams

With a configuration option, the following function is available which opens streams across network connections.

Function: open-client-stream {host port}

The string host indicates the name of the host, while port is an integer which identifies the port number to which to connect. This function returns a two-way stream which can be used in any of the stream operations.

Function: open-server-stream {host port}

A stream connected to port number port is created to which clients can connect. This function returns a two-way stream which can be used in any of the stream operations.

3.4 CLOS Streams

When the optional CLOS subsystem is available, an interface is provided by ECL for using CLOS objects as Common-Lisp Such support can be used for instance to build interactive character streams, which may be used by applications as the stream argument for Common-Lisp functions such as read, listen, prin1, etc. The fundamental interface to clos-stream objects consists of (generic) functions which implement the basic Common-Lisp operations (see Common-Lisp@c, Chapter 22) but whose details are implementation dependent.

The following functions are automatically invoked by ECL when a stream operation involves a CLOS object as a stream parameter. The programmer should define these methods for any class of objects which are to be used for character input/output.

3.4.1 CLOS Stream Input
3.4.2 CLOS Stream Output
3.4.3 CLOS Stream common

3.4.1 CLOS Stream Input

Character input from an clos-stream is implemented by the following methods.

Method: stream-read-char (object clos-stream)

Returns the next character object read from the CLOS stream object.

Method: stream-unread-char (object clos-stream) character

Unreads the character object character from the CLOS stream object. character will be the next character read by stream-read-char.

Method: stream-listen (object clos-stream)

Returns () object. Otherwise, the next character is returned, as if stream-peek-char had been called.

Method: stream-clear-input object

Clears any buffered characters on the CLOS stream object. Returns ()@c.

3.4.2 CLOS Stream Output

Character output from an clos-stream is implemented by the following methods.

Method: stream-write-char (object clos-stream) character

Outputs the character character to the CLOS stream object and returns it.

Method: stream-clear-output (object clos-stream)

Aborts any outstanding output operation on the CLOS stream object and returns ()@c.

Method: stream-force-output (object clos-stream)

Initiates the emptying of the internal buffers on the CLOS stream object and returns ()@c.

3.4.3 CLOS Stream common

The following functions should be available for all CLOS streams.

Method: stream-interactive-p (object clos-stream)

Method: stream-close (object clos-stream)

Closes the stream for any further input or output.