Node: Ports, Next: , Previous: Input and Output, Up: Input and Output



Ports

call-with-input-file string proc R5RS
call-with-output-file string proc R5RS
String should be a string naming a file, and proc should be a procedure that accepts one argument. For call-with-input-file, the file should already exist. These procedures call proc with one argument: the port obtained by opening the named file for input or output. If the file cannot be opened, an error is signaled. If proc returns, then the port is closed automatically and the value(s) yielded by the proc is(are) returned. If proc does not return, then the port will not be closed automatically.

Rationale: Because Scheme's escape procedures have unlimited extent, it is possible to escape from the current continuation but later to escape back in. If implementations were permitted to close the port on any escape from the current continuation, then it would be impossible to write portable code using both call-with-current-continuation and call-with-input-file or call-with-output-file.

call-with-input-string string proc STKLOS Procedure
behaves as call-with-input-file except that the port passed to proc is the sting port obtained from port.
          (call-with-input-string "123 456"
            (lambda (x)
               (let* ((n1 (read x))
                      (n2 (read x)))
                  (cons n1 n2))))          => (123 . 456)
          

call-with-output-string proc STKLOS Procedure
Proc should be a procedure of one argument. Call-with-output-string calls proc with a freshly opened output string port. The result of this procedure is a string containing all the text that has been written on the string port.
          (call-with-output-string
            (lambda (x) (write 123 x) (display "Hello" x))) => "123Hello"
          

fine (call-with-output-string proc) let ((port (open-output-string))) (proc port) (close-port port) (get-output-string port)))

; ; String functions ;

c ext read-from-string (read-from-string str)

Performs a read from the given str. If str is the empty string, an end of file object is returned.

          (read-from-string "123 456") => 123
          (read-from-string "")        => an eof object
          

input-port? obj R5RS
output-port? obj R5RS
Returns #t if obj is an input port or output port respectively, otherwise returns #f.

input-string-port? obj STKLOS Procedure
output-string-port? obj STKLOS Procedure
Returns #t if obj is an input string port or output string port respectively, otherwise returns #f.

input-file-port? obj STKLOS Procedure
output-file-port? obj STKLOS Procedure
Returns #t if obj is a file input port or a file output port respectively, otherwise returns #f.

interactive-port? port STKLOS Procedure
Returns #t if port is connected to a terminal and #f otherwise.

current-input-port obj R5RS
current-output-port obj R5RS
Returns the current default input or output port.

current-error-port obj STKLOS Procedure
Returns the current default error port.

with-input-from-file string thunk R5RS
with-output-to-file string thunk R5RS
String should be a string naming a file, and proc should be a procedure of no arguments. For with-input-from-file, the file should already exist. The file is opened for input or output, an input or output port connected to it is made the default value returned by current-input-port or current-output-port (and is used by (read), (write obj), and so forth), and the thunk is called with no arguments. When the thunk returns, the port is closed and the previous default is restored. With-input-from-file and with-output-to-file return(s) the value(s) yielded by thunk.

The following example uses a pipe port opened for reading. It permits to read all the lines produced by an external ls command (i.e. the output of the ls command is redirected to the Scheme pipe port).

          (with-input-from-file "| ls -ls"
            (lambda ()
              (do ((l (read-line) (read-line)))
                  ((eof-object? l))
                (display l)
                (newline))))
          

Hereafter is another example of Unix command redirection. This time, it is the standard input of the Unix command which is redirected.

          (with-output-to-file "| mail root"
            (lambda ()
              (display "A simple mail from STklos")
              (newline)))
          

with-error-to-file string thunk STKLOS Procedure
This procedure is similar to with-output-to-file, excepted that it uses the current error port instead of the output port.

with-input-from-string string thunk STKLOS Procedure
A string port is opened for input from string. Current-input-port is set to the port and thunk is called. When thunk returns, the previous default input port is restored. With-input-from-string returns the value(s) computed by thunk.
          (with-input-from-string "123 456"
            (lambda () (read)))                       =>  123
          

with-output-to-string thunk STKLOS Procedure
A string port is opened for output. Current-output-port is set to it and thunk is called. When thunk returns, the previous default output port is restored. With-output-to-string returns the string containing the text written on the string port.
          (with-output-to-string
             (lambda () (write 123) (write "Hello"))) => "123\"Hello\""
          

open-input-file filename R5RS
Takes a string naming an existing file and returns an input port capable of delivering characters from the file. If the file cannot be opened, an error is signalled.

Note: if filename starts with the string "| ", this procedure returns a pipe port. Consequently, it is not possible to open a file whose name starts with those two characters.

open-input-string str STKLOS Procedure
Returns an input string port capable of delivering characters from str.

open-output-file filename R5RS
Takes a string naming an output file to be created and returns an output port capable of writing characters to a new file by that name. If the file cannot be opened, an error is signalled. If a file with the given name already exists, it is rewritten.

Note: if filename starts with the string "| ", this procedure returns a pipe port. Consequently, it is not possible to open a file whose name starts with those two characters.

open-output-string STKLOS Procedure
Returns an output string port capable of receiving and collecting characters.

open-file filename mode STKLOS Procedure
Opens the file whose name is filename with the specified string mode which can be:
  • "r" to open file for reading. The stream is positioned at the beginning of the file.
  • "r+" to open file for reading and writing. The stream is positioned at the beginning of the file.
  • "w" to truncate file to zero length or create file for writing. The stream is positioned at the beginning of the file.
  • "w+" to open file for reading and writing. The file is created if it does not exist, otherwise it is truncated. The stream is positioned at the beginning of the file.
  • "a" to open for writing. The file is created if it does not exist. The stream is positioned at the end of the file.
  • "a+" to open file for reading and writing. The file is created if it does not exist. The stream is positioned at the end of the file.
If the file can be opened, open-file returns the port associated with the given file, otherwise it returns #f. Here again, the "magic" string "| " permits to open a pipe port (in this case mode can only be "r" or "w").

get-output-string port STKLOS Procedure
Returns a string containing all the text that has been written on the output string port.
           (let ((p (open-output-string)))
              (display "Hello, world" p)
              (get-output-string p))         => "Hello, world"
          

close-input-port port R5RS
close-output-port port R5RS
Closes the port associated with port, rendering the port incapable of delivering or accepting characters. These routines have no effect if the port has already been closed. The value returned is void.

close-port port STKLOS Procedure
Closes the port associated with port.

rewind-file-port port STKLOS Procedure
Sets the port position to the beginning of port. The value returned by rewind-port is void.

port-current-line R5RS
port-current-line port R5RS
Returns the current line number associated to the given input port as an integer. The port argument may be omitted, in which case it defaults to the value returned by current-input-port.

port-file-name port STKLOS Procedure
Returns the file name used to open port; port must be a file port.

port-idle-register! port thunk STKLOS Procedure
port-idle-unregister! port thunk STKLOS Procedure
port-idle-reset! port STKLOS Procedure
port-idle-register! allows to register thunk as an idle handler when reading on port. That means that thunk will be called continuously while waiting an input on port (and only while using a reading primitive on this port). port-idle-unregister! can be used to unregister a handler previously set by port-idle-register!. The primitive port-idle-reset! unregisters all the handlers set on port.

Hereafter is a (not too realistic) example: a message will be displayed repeatedly until a character is read on the current input port.

          (let ((idle (lambda () (display "Nothing to read!\n"))))
            (port-idle-register! (current-input-port) idle)
            (let ((result (read)))
              (port-idle-unregister! (current-input-port) idle)
              result))