| The class stream implements the support of the system streams that one can use for reading and writing to files, named pipes, and standard interprocess pipes. In case of error occuring during the execution of a stream class method, the thread local variable *laststreamerror* will be set to the corresponding system error message, and must be reset to nil after use. For performance reason, a C structure containing buffers and flags is also bound to the property lfile of each instance of the class. Stream and file functions not implemented in the present class can be called directly with the FFI (see library class) using the file descriptor which can be queried by calling the file-fileno function. see also the function select and the class file . |
| Function Type | subr |
| Arguments | a stream object, optional t or nil |
| Return Value | t or nil |
| Description | checks if a character has been unread on the stream object; the optional argument sets the charInBuffer state of the stream object to t or nil. |
| Example | (char-in-buffer stdin) => nil |
| Function Type | subr |
| Arguments | a stream object |
| Return Value | nil |
| Description | invalidates the stream object input buffer so that the next stream-read-char, stream-read-line or stream-fread operation must require a real read on the stream descriptor |
| Example | (clear-input mystream) |
| Function Type | subr |
| Arguments | the symbol stream, a mandatory string, a series of optional keywords some followed by values |
| Return Value | a stream object |
| Description | never call stream-constructor directly but always through make-instance ;
the first argument is mandatory and gives the filename of the stream; the rest of the arguments are optional keywords; the keyword 'read indicates that the file will be opened in read mode, which is the default mode if the mode is not specified; the keyword 'write specifies write mode and the keyword 'append specifies append mode; if more than one mode keyword is supplied, the last one is used; the keyword 'update allows updating the file; the keyword 'maxstring followed by an integer gives the size of the input buffer; the default length is the same as that defined by the -t parameter of the interpreter thread, or 4096; the keyword 'historysize followed by an integer indicates the length of the keyboard history to be used when the file is a terminal; all the keywords must evaluate to the expected symbols or be quoted to prevent evaluation |
| Example | (make-instance stream "myfile.txt" 'read 'update 'maxstring 2048) |
| Function Type | subr |
| Arguments | a stream object |
| Return Value | t |
| Description | never call stream-destructor directly but always through destroy-instance ; the destructor closes the stream and saves the file if it was created by the constructor |
| Example | (destroy-instance mystream) |
| Function Type | subr |
| Arguments | a stream object |
| Return Value | t or nil |
| Description | returns t if the stream has encountered an irrecuperable error or has been closed; returns nil is the stream is still operable |
| Example | (eof mystream) |
| Function Type | subr |
| Arguments | a stream object |
| Return Value | an unsigned integer |
| Description | returns the value of the FILE pointer to the stream as an unsigned integer |
| Example | (fileptr stdin) => 0xb7e87300 |
| Function Type | subr |
| Arguments | a stream object, a binary, an optional integer |
| Return Value | an integer or nil |
| Description | reads the stream given as first argument into the buffer given as second argument, up to the length of the buffer or the length given as third argument if it is smaller; if still unread data remain in the input buffer of the stream object, these data are returned first and no actual read occurs on the system file descriptor; the next stream-read-char , stream-read-line or stream-fread will get the rest of the input buffer if still any and the system file will be read only after input buffer exhaustion; use first stream-clear-input to invalidate the input buffer and force an actual read on the file; the function returns the actual length read, which might be smaller than the buffer or the requested length if either it is what remained in the input buffer or it is only what the system file could give at that moment |
| Example | (fread mystream buffer1) |
| Function Type | subr |
| Arguments | a stream object, an integer, an optional keyword |
| Return Value | t or nil |
| Description | positions the file pointer of the file corresponding to the stream object given as first argument to the position given as second argument; the optional third argument is a keyword: 'set indicates that the byte position is relative to the beginning of the file, 'cur indicates that the position is relative to the current or last IO, and 'end indicates that the position is relative to the end of the file; returns t if the positionning is successful |
| Example | (fseek mystream 1000 'set) |
| Function Type | subr |
| Arguments | none |
| Return Value | an integer |
| Description | returns an integer giving the current position of the file pointer for the stream object given as argument, relative to the beginning of the file |
| Example | (ftell mystream) |
| Function Type | subr |
| Arguments | a stream object, a binary, an optional integer |
| Return Value | an integer or nil |
| Description | write the buffer given as second argument on the stream given as first argument, up to the length of the buffer or the length given as third argument if shorter; returns the length actually written |
| Example | (fwrite mystream buffer1) |
| Function Type | subr |
| Arguments | a stream object |
| Return Value | an integer or nil |
| Description | reads a UTF-8 character on the input buffer of the stream object given as argument; if the input buffer is empty, a read() is initiated on the file eventually waiting data if from a terminal or a pipe; the UTF-8 sequences are interpreted by a finite state automaton until complete and returned as one Unicode integer; returns EOF if the input buffer is empty and the stream is at end; stream-read-char returns nil in case of stream error; an error or end of file reached while reconstituting a UTF-8 causes the loss of the sequence and a nil result |
| Example | (read-char mystream) |
| Function Type | subr |
| Arguments | a stream object |
| Return Value | an integer |
| Description | reads an UTF-8 character directly on a stream object bound to a terminal, without to use the input buffer; there is no echo on the terminal; escape sequences like movement keys are perceived as several separated characters which must be interpreted by the application; UTF-8 sequences are interpreted by a finite state automaton until complete and returned as one Unicode integer |
| Example | (read-char-direct stdin) |
| Function Type | subr |
| Arguments | a stream object |
| Return Value | a string |
| Description | reads a string from the input buffer of the stream object given as argument and returns it; if the input buffer is empty, a read() is initiated on the stream eventually waiting data if from a terminal or a pipe;if the input buffer is empty and the stream is at end, stream-read-string returns nil and sets EOF to true; the function also returns nil in case of stream error; the string read goes from the current position in the input buffer to just after the last character in the buffer; newline characters or CR-LF sequences can be embedded in the string and are not deleted |
| Example | (read-string mytream) |
| Function Type | subr |
| Arguments | a stream (or subclass) object, a binary block, an integer |
| Return Value | t or nil |
| Description | prints a formatted view of the C structure containing buffers and flags which is bound as a binary block to the property lfile of the object; this method is not intended to be used directly but it is called by the class-show method; a showbin method must return t to signal a successful print |
| Example | none |
| Function Type | subr |
| Arguments | a stream object |
| Return Value | nil |
| Description | sets the flag char-in-buffer of the stream object to t so that the last character read by stream-read-char again returned by the next call to stream-read-char or stream-read-string or stream-fread |
| Example | (unread-char mystream) |
| Function Type | subr |
| Arguments | a stream object, an integer |
| Return Value | an integer or nil |
| Description | writes a UTF-8 character on the stream object; if successful returns the second argument |
| Example | (write-char mystream 8364) |
| Function Type | subr |
| Arguments | a stream object, a string |
| Return Value | a string |
| Description | writes the string given as second argument on the stream object given as first argument; if successful returns the second argument; a UNIX newline, ie 0xa, is appended to the string |
| Example | (write-line mystream "this is a text line" ) |
| Function Type | subr |
| Arguments | a stream object, a string |
| Return Value | a string |
| Description | writes the string given as second argument on the stream object given as first argument; if successful returns the second argument; no UNIX newline, ie 0xa is appended to the string |
| Example | (write-string mystream "this is a text string" ) |