(lispkit port)
Ports represent abstractions for handling input and output. They are used to access files, devices, and similar things on the host system on which LispKit is running.
An input port is a LispKit object that can deliver data upon command, while an output port is an object that can accept data. In LispKit, input and output port types are disjoint, i.e. a port is either an input or an output port.
Different port types operate on different data. LispKit provides two differnt types of ports: textual ports and binary ports. Textual ports and binary ports are disjoint, i.e. a port is either textual or binary.
A textual port supports reading or writing of individual characters from or to a backing store containing characters using
read-char
and write-char
, and it supports operations defined in terms of characters, such as read
and write
.A binary port supports reading or writing of individual bytes from or to a backing store containing bytes using
read-u8
and write-u8
below, as well as operations defined in terms of bytes.current-output-port
current-input-port
current-error-port

These parameter objects represent the current default input port, output port, or error port (an output port), respectively. These parameter objects can be overridden with
parameterize
.default-output-port
default-input-port

These two ports are the initial values of
current-output-port
and current-input-port
when LispKit gets initialized. They are typically referring to the default output and input device of the system on which LispKit is running.(port? obj)

Returns
#t
if obj is a port object; otherwise #f
is returned.(input-port? obj)
(output-port? obj)

These predicates return
#t
if obj is an input port or output port; otherwise they return #f
.(textual-port? obj)
(binary-port? obj)

These predicates return
#t
if obj is a textual or a binary port; otherwise they return #f
.(input-port-open? port)
(output-port-open? port)

Returns
#t
if port is still open and capable of performing input or output, respectively, and #f
otherwise.(eof-object? obj)

Returns
#t
if obj is an end-of-file object, otherwise returns #f
.(close-port port)
(close-input-port port)
(close-output-port port)

Closes the resource associated with port, rendering the port incapable of delivering or accepting data. It is an error to apply
close-input-port
and close-output-port
to a port which is not an input or output port, respectively. All procedures for closing ports have no effect if the provided port has already been closed.(with-input-from-port port thunk)
(with-output-to-port port thunk)

The given port is made to be the value returned by
current-input-port
or current-output-port
(as used by (read)
, (write obj)
, and so forth). The thunk is then called with no arguments. When the thunk returns, the port is closed and the previous default is restored. It is an error if thunk does not accept zero arguments. Both procedures return the values yielded by thunk. If an escape procedure is used to escape from the continuation of these procedures, they behave exactly as if the current input or output port had been bound dynamically with parameterize
.(call-with-port port proc)

The
call-with-port
procedure calls proc with port as an argument. It is an error if proc does not accept one argument.If proc returns, then the port is closed automatically and the values yielded by proc are returned. If proc does not return, then the port will not be closed automatically unless it is possible to prove that the port will never again be used for a read or write operation.
This is necessary, because LispKit’s escape procedures have unlimited extent and thus it is possible to escape from the current continuation but later to resume it. If LispKit would be 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-port
.(open-input-file filepath)
(open-input-file filepath fail)

Takes a filepath referring to an existing file and returns a textual input port that is capable of delivering data from the file. If the file does not exist or cannot be opened, an error that satisfies
file-error?
is signaled if argument fail is not provided. If fail is provided, it is returned in case an error occured.(open-binary-input-file filepath)
(open-binary-input-file filepath fail)

Takes a filepath referring to an existing file and returns a binary input port that is capable of delivering data from the file. If the file does not exist or cannot be opened, an error that satisfies
file-error?
is signaled if argument fail is not provided. If fail is provided, it is returned in case an error occured.(open-output-file filepath)
(open-output-file filepath fail)

Takes a filepath referring to an output file to be created and returns a textual output port that is capable of writing data to the new file. If a file with the given name exists already, the effect is unspecified. If the file cannot be opened, an error that satisfies
file-error?
is signaled if argument fail is not provided. If fail is provided, it is returned in case an error occured.(open-binary-output-file filepath)
(open-binary-output-file filepath fail)

Takes a filepath referring to an output file to be created and returns a binary output port that is capable of writing data to the new file. If a file with the given name exists already, the effect is unspecified. If the file cannot be opened, an error that satisfies
file-error?
is signaled if argument fail is not provided. If fail is provided, it is returned in case an error occured.(with-input-from-file filepath thunk)
(with-output-to-file filepath thunk)

The file determined by filepath is opened for input or output as if by
open-input-file
or open-output-file
, and the new port is made to be the value returned by current-input-port
or current-output-port
(as used by (read)
, (write obj)
, and so forth). The thunk is then called with no arguments. When the thunk returns, the port is closed and the previous default is restored. It is an error if thunk does not accept zero arguments. Both procedures return the values yielded by thunk. If an escape procedure is used to escape from the continuation of these procedures, they behave exactly as if the current input or output port had been bound dynamically with parameterize
.(call-with-input-file filepath proc)
(call-with-output-file filepath proc)

These procedures create a textual port obtained by opening the file referred to by filepath (a string) for input or output as if by
open-input-file
or open-output-file
. This port and proc are then passed to a procedure equivalent to call-with-port
. It is an error if proc does not accept one argument.(open-input-string str)

Takes a string and returns a textual input port that delivers characters from the string. If the string is modified, the effect is unspecified.
(open-output-string)

Returns a textual output port that will accumulate characters for retrieval by
get-output-string
.(parameterize ((current-output-port (open-output-string)))
(display "piece")
(display " by piece ")
(display "by piece.")
(get-output-string (current-output-port)))
⇒ "piece by piece by piece."
(get-output-string port)

It is an error if port was not created with
open-output-string
.Returns a string consisting of the characters that have been output to port so far in the order they were output.
(parameterize ((current-output-port (open-output-string)))
(display "piece")
(display " by piece ")
(display "by piece.")
(newline)
(get-output-string (current-output-port)))
⇒ "piece by piece by piece.\n"
(with-input-from-string str thunk) 
