commit ec957027fc89690a1589a1dbcd78fa2cd67fbb96
parent b3f057670aa104ab985e7c1a422e6cf83c9e3339
Author: Wolfgang Corcoran-Mathe <wcm@sigwinch.xyz>
Date: Mon, 5 Feb 2024 01:04:24 -0500
I & O: Texify, part 1.
Diffstat:
1 file changed, 194 insertions(+), 193 deletions(-)
diff --git a/doc/r7rs-small/procedures/input-and-output.texinfo b/doc/r7rs-small/procedures/input-and-output.texinfo
@@ -10,63 +10,64 @@
@node Ports
@subsection Ports
-Ports represent input and output devices. To Scheme, an input port is a Scheme object
-that can deliver data upon command, while an output port is a Scheme object that can
-accept data.Whether the input and output port types are disjoint is
+Ports represent input and output devices. To Scheme, an input port is
+a Scheme object that can deliver data upon command, while an output
+port is a Scheme object that can accept data.
+Whether the input and output port types are disjoint is
implementation-dependent.
-Different port types operate on different data. Scheme implementations are required to
-support textual ports and binary ports, but may also provide other port types.
+Different @dfn{port types} operate on different data. Scheme
+implementations are required to support @dfn{textual ports}
+and @dfn{binary ports}, but may also provide other port types.
-A textual port supports reading or writing of individual characters from or to a backing
-store containing characters using read-char and write-char below, and it supports
-operations defined in terms of characters, such as read and write.
+A textual port supports reading or writing of individual characters
+from or to a backing store containing characters
+using @code{read-char} and @code{write-char} below, and it supports operations
+defined in terms of characters, such as @code{read} and @code{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. Whether the textual and binary port types are disjoint is
+A binary port supports reading or writing of individual bytes from
+or to a backing store containing bytes using @code{read-u8} and
+@code{write-u8} below, as well as operations defined in terms of bytes.
+Whether the textual and binary port types are disjoint is
implementation-dependent.
-Ports can be used to access files, devices, and similar things on the host system on which
-the Scheme program is running.
+Ports can be used to access files, devices, and similar things on the host
+system on which the Scheme program is running.
@deffn procedure call-with-port port proc
-It is an error if
+It is an error if @var{proc} does not accept one argument.
-proc does not accept one argument.
+The @code{call-with-port}
+procedure calls @var{proc} with @var{port} as an argument.
+If @var{proc} returns,
+then the port is closed automatically and the values yielded by the
+@var{proc} are returned. If @var{proc} does not return, then
+the port must not be closed automatically unless it is possible to
+prove that the port will never again be used for a read or write
+operation.
-The call-with-port procedure calls
+@subheading Rationale:
-proc with
+Because Scheme's escape procedures have unlimited extent, it is
+possible to escape from the current continuation but later to resume it.
+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 @code{call-with-current-continuation} and @code{call-with-port}.
-port as an argument. If
-
-proc returns, then the port is closed automatically and the values yielded by the
-
-proc are returned. If
-
-proc does not return, then the port must not be closed automatically unless it is possible
-to prove that the port will never again be used for a read or write operation.
-
-Rationale: Because Scheme's escape procedures have unlimited extent, it is possible
-to escape from the current continuation but later to resume it. 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-port.
@end deffn
@deffn {file library procedure} call-with-input-file string proc
@deffnx {file library procedure} call-with-output-file string proc
-It is an error if
-
-proc does not accept one argument.
+It is an error if @var{proc} does not accept one argument.
-These procedures obtain a textual port obtained by opening the named file for input or
-output as if by open-input-file or open-output-file. The port and
+These procedures obtain a
+textual port obtained by opening the named file for input or output
+as if by @code{open-input-file} or @code{open-output-file}.
+The port and @var{proc} are then passed to a procedure equivalent
+to @code{call-with-port}.
-proc are then passed to a procedure equivalent to call-with-port.
@end deffn
@deffn procedure input-port? obj
@@ -75,19 +76,19 @@ proc are then passed to a procedure equivalent to call-with-port.
@deffnx procedure binary-port? obj
@deffnx procedure port? obj
-These procedures return #t if
+These procedures return @code{#t} if @var{obj} is an input port, output port,
+textual port, binary port, or any
+kind of port, respectively. Otherwise they return @code{#f}.
-obj is an input port, output port, textual port, binary port, or any kind of port,
-respectively. Otherwise they return #f.
@end deffn
@deffn procedure input-port-open? port
@deffnx procedure output-port-open? port
-Returns #t if
-
-port is still open and capable of performing input or output, respectively, and #f
+Returns @code{#t} if
+@var{port} is still open and capable of performing input or output, respectively, and @code{#f}
otherwise.
+
@end deffn
@deffn procedure current-input-port
@@ -96,88 +97,93 @@ otherwise.
Returns the current default input port, output port, or error port (an output port),
respectively. These procedures are parameter objects, which can be overridden with
-parameterize (see section 4.2.6). The initial bindings for these are
+parameterize (see @ref{Dynamic bindings}). The initial bindings for these are
implementation-defined textual ports.
+
@end deffn
@deffn {file library procedure} with-input-from-file string thunk
@deffnx {file library procedure} with-output-to-file string thunk
-The file 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
+The file is opened for input or output
+as if by @code{open-input-file} or @code{open-output-file},
+and the new port is made to be the value returned by
+@code{current-input-port} or @code{current-output-port}
+(as used by @code{(read)}, @code{(write }@var{obj}@code{)}, and so forth).
+The @var{thunk} is then called with no arguments. When the @var{thunk} returns,
+the port is closed and the previous default is restored.
+It is an error if @var{thunk} does not accept zero arguments.
+Both procedures return the values yielded by @var{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 @code{parameterize}.
-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.
@end deffn
@deffn {file library procedure} open-input-file string
@deffnx {file library procedure} open-binary-input-file string
-Takes a
+Takes a @var{string} for an existing file and returns a textual
+input port or 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 @code{file-error?} is signaled.
-string for an existing file and returns a textual input port or 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.
@end deffn
@deffn {file library procedure} open-output-file string
@deffnx {file library procedure} open-binary-output-file string
-Takes a
+Takes a @var{string} naming an output file to be created and returns a
+textual output port or binary output port that is capable of writing
+data to a new file by that name.
+If a file with the given name already exists,
+the effect is unspecified.
+If the file cannot be opened,
+an error that satisfies @code{file-error?} is signaled.
-string naming an output file to be created and returns a textual output port or binary
-output port that is capable of writing data to a new file by that name. If a file with the
-given name already exists, the effect is unspecified. If the file cannot be opened, an error
-that satisfies file-error? is signaled.
@end deffn
@deffn procedure close-port port
@deffnx procedure close-input-port port
@deffnx procedure close-output-port port
-Closes the resource associated with
+Closes the resource associated with @var{port}, rendering the @var{port}
+incapable of delivering or accepting data.
+It is an error
+to apply the last two procedures to a port which is not an input
+or output port, respectively.
+Scheme implementations may provide ports which are simultaneously
+input and output ports, such as sockets; the @code{close-input-port}
+and @code{close-output-port} procedures can then be used to close the
+input and output sides of the port independently.
-port, rendering the
+These routines have no effect if the @var{port} has already been closed.
-port incapable of delivering or accepting data. It is an error to apply the last two
-procedures to a port which is not an input or output port, respectively. Scheme
-implementations may provide ports which are simultaneously input and output ports,
-such as sockets; the close-input-port and close-output-port procedures can then be used
-to close the input and output sides of the port independently.
-
-These routines have no effect if the port has already been closed.
@end deffn
@deffn procedure open-input-string string
Takes a string and returns a textual input port that delivers characters from the string. If
-the string is modified, the effect is unspecified.
+the @var{string} is modified, the effect is unspecified.
+
@end deffn
@deffn procedure open-output-string
Returns a textual output port that will accumulate characters for retrieval by
-get-output-string.
+@code{get-output-string}.
+
@end deffn
@deffn procedure get-output-string port
-It is an error if
+It is an error if @var{port} was not created with
+@code{open-output-string}.
-port was not created with open-output-string.
-
-Returns a string consisting of the characters that have been output to the port so far in
-the order they were output. If the result string is modified, the effect is unspecified.
+Returns a string consisting of the
+characters that have been output to the port so far in the order they
+were output.
+If the result string is modified, the effect is unspecified.
@lisp
(parameterize
@@ -189,201 +195,201 @@ the order they were output. If the result string is modified, the effect is unsp
(newline)
(get-output-string (current-output-port)))
-@result{} "piece by piece by piece.\n"
+ @result{} "piece by piece by piece.\n"
@end lisp
@end deffn
@deffn procedure open-input-bytevector bytevector
-Takes a bytevector and returns a binary input port that delivers bytes from the
-bytevector.
+Takes a @var{bytevector} and returns a binary input port that delivers bytes from the
+@var{bytevector}.
+
@end deffn
@deffn procedure open-output-bytevector
Returns a binary output port that will accumulate bytes for retrieval by
-get-output-bytevector.
+@code{get-output-bytevector}.
+
@end deffn
@deffn procedure get-output-bytevector port
-It is an error if
+It is an error if @var{port} was not created with
+@code{open-output-bytevector}.
-port was not created with open-output-bytevector.
-
-Returns a bytevector consisting of the bytes that have been output to the port so far in
-the order they were output.
+Returns a bytevector consisting
+of the bytes that have been output to the @var{port} so far in the
+order they were output.
@end deffn
@node Input
@subsection Input
-If
-
-port is omitted from any input procedure, it defaults to the value returned by
-(current-input-port). It is an error to attempt an input operation on a closed port.
+If @var{port} is omitted from any input procedure, it defaults to the
+value returned by @code{(current-input-port)}.
+It is an error to attempt an input operation on a closed port.
@deffn {read library procedure} read
@deffnx {read library procedure} read port
-The read procedure converts external representations of Scheme objects into the
-objects themselves. That is, it is a parser for the non-terminal @svar{datum} (see sections
-7.1.2 and 6.4). It returns the next object parsable from the given textual input
+The @code{read} procedure converts external representations of Scheme objects into the
+objects themselves. That is, it is a parser for the non-terminal
+@svar{datum} (see @ref{External representations formal,, External representations} and
+@ref{Pairs and lists}). It returns the next
+object parsable from the given textual input @var{port}, updating
+@var{port} to point to
+the first character past the end of the external representation of the object.
-port, updating
+Implementations may support extended syntax to represent record types or
+other types that do not have datum representations.
-port to point to the first character past the end of the external representation of the
-object.
-
-Implementations may support extended syntax to represent record types or other types
-that do not have datum representations.
+If an end of file is encountered in the input before any
+characters are found that can begin an object, then an end-of-file
+object is returned. The port remains open, and further attempts
+to read will also return an end-of-file object. If an end of file is
+encountered after the beginning of an object's external representation,
+but the external representation is incomplete and therefore not parsable,
+an error that satisfies @code{read-error?} is signaled.
-If an end of file is encountered in the input before any characters are found that can
-begin an object, then an end-of-file object is returned. The port remains open, and
-further attempts to read will also return an end-of-file object. If an end of file is
-encountered after the beginning of an object's external representation, but the external
-representation is incomplete and therefore not parsable, an error that satisfies
-read-error? is signaled.
@end deffn
@deffn procedure read-char
@deffnx procedure read-char port
-Returns the next character available from the textual input
-
-port, updating the
+Returns the next character available from the textual input @var{port},
+updating
+the @var{port} to point to the following character. If no more characters
+are available, an end-of-file object is returned.
-port to point to the following character. If no more characters are available, an end-of-file
-object is returned.
@end deffn
@deffn procedure peek-char
@deffnx procedure peek-char port
Returns the next character available from the textual input
-
-port, but without updating the
-
-port to point to the following character. If no more characters are available, an end-of-file
+@var{port}, but without updating the
+@var{port} to point to the following character. If no more characters are available, an end-of-file
object is returned.
-Note: The value returned by a call to peek-char is the same as the value that would
-have been returned by a call to read-char with the same
-
-port. The only difference is that the very next call to read-char or peek-char on that
+Note:
+The value returned by a call to @code{peek-char} is the same as the
+value that would have been returned by a call to @code{read-char} with the
+same @var{port}. The only difference is that the very next call to
+@code{read-char} or @code{peek-char} on that @var{port} will return the
+value returned by the preceding call to @code{peek-char}. In particular, a call
+to @code{peek-char} on an interactive port will hang waiting for input
+whenever a call to @code{read-char} would have hung.
-port will return the value returned by the preceding call to peek-char. In particular, a
-call to peek-char on an interactive port will hang waiting for input whenever a call to
-read-char would have hung.
@end deffn
@deffn procedure read-line
@deffnx procedure read-line port
Returns the next line of text available from the textual input
+@var{port}, updating the @var{port} to point to the following character.
+If an end of line is read, a string containing all of the text up to
+(but not including) the end of line is returned, and the port is updated
+to point just past the end of line. If an end of file is encountered
+before any end of line is read, but some characters have been
+read, a string containing those characters is returned. If an end of
+file is encountered before any characters are read, an end-of-file
+object is returned. For the purpose of this procedure, an end of line
+consists of either a linefeed character, a carriage return character, or a
+sequence of a carriage return character followed by a linefeed character.
+Implementations may also recognize other end of line characters or sequences.
-port, updating the
-
-port to point to the following character. If an end of line is read, a string containing all of
-the text up to (but not including) the end of line is returned, and the port is updated to
-point just past the end of line. If an end of file is encountered before any end of line is
-read, but some characters have been read, a string containing those characters is
-returned. If an end of file is encountered before any characters are read, an end-of-file
-object is returned. For the purpose of this procedure, an end of line consists of either a
-linefeed character, a carriage return character, or a sequence of a carriage return
-character followed by a linefeed character. Implementations may also recognize other
-end of line characters or sequences.
@end deffn
@deffn procedure eof-object? obj
-Returns #t if
+Returns @code{#t} if @var{obj} is an end-of-file object, otherwise returns
+@code{#f}. The precise set of end-of-file objects will vary among
+implementations, but in any case no end-of-file object will ever be an object
+that can be read in using @code{read}.
-obj is an end-of-file object, otherwise returns #f. The precise set of end-of-file objects
-will vary among implementations, but in any case no end-of-file object will ever be an
-object that can be read in using read.
@end deffn
@deffn procedure eof-object
Returns an end-of-file object, not necessarily unique.
+
@end deffn
@deffn procedure char-ready?
@deffnx procedure char-ready? port
-Returns #t if a character is ready on the textual input
-
-port and returns #f otherwise. If char-ready returns #t then the next read-char operation
-on the given
+Returns @code{#t} if a character is ready on the textual input @var{port} and
+returns @code{#f} otherwise. If @code{char-ready} returns @code{#t} then
+the next @code{read-char} operation on the given @var{port} is guaranteed
+not to hang. If the @var{port} is at end of file then @code{char-ready?}
+returns @code{#t}.
-port is guaranteed not to hang. If the
+@subheading Rationale:
-port is at end of file then char-ready? returns #t.
+The @code{char-ready?} procedure exists to make it possible for a program to
+accept characters from interactive ports without getting stuck waiting for
+input. Any input editors associated with such ports must ensure that
+characters whose existence has been asserted by @code{char-ready?} cannot
+be removed from the input. If @code{char-ready?} were to return @code{#f} at end of
+file, a port at end of file would be indistinguishable from an interactive
+port that has no ready characters.
-Rationale: The char-ready? procedure exists to make it possible for a program to
-accept characters from interactive ports without getting stuck waiting for input.
-Any input editors associated with such ports must ensure that characters whose
-existence has been asserted by char-ready? cannot be removed from the input. If
-char-ready? were to return #f at end of file, a port at end of file would be
-indistinguishable from an interactive port that has no ready characters.
@end deffn
@deffn procedure read-string k
@deffnx procedure read-string k port
-Reads the next
+Reads the next @var{k} characters, or as many as are available before the end of file,
+from the textual
+input @var{port} into a newly allocated string in left-to-right order
+and returns the string.
+If no characters are available before the end of file,
+an end-of-file object is returned.
-k characters, or as many as are available before the end of file, from the textual input
-
-port into a newly allocated string in left-to-right order and returns the string. If no
-characters are available before the end of file, an end-of-file object is returned.
@end deffn
@deffn procedure read-u8
@deffnx procedure read-u8 port
Returns the next byte available from the binary input
-
-port, updating the
-
-port to point to the following byte. If no more bytes are available, an end-of-file object is
+@var{port}, updating the
+@var{port} to point to the following byte. If no more bytes are available, an end-of-file object is
returned.
+
@end deffn
@deffn procedure peek-u8
@deffnx procedure peek-u8 port
Returns the next byte available from the binary input
-
-port, but without updating the
-
-port to point to the following byte. If no more bytes are available, an end-of-file object is
+@var{port}, but without updating the
+@var{port} to point to the following byte. If no more bytes are available, an end-of-file object is
returned.
+
@end deffn
@deffn procedure u8-ready?
@deffnx procedure u8-ready? port
-Returns #t if a byte is ready on the binary input
-
-port and returns #f otherwise. If u8-ready? returns #t then the next read-u8 operation on
-the given
-
-port is guaranteed not to hang. If the
+Returns @code{#t} if a byte is ready on the binary input @var{port}
+and returns @code{#f} otherwise. If @code{u8-ready?} returns
+@code{#t} then the next @code{read-u8} operation on the given
+@var{port} is guaranteed not to hang. If the @var{port} is at end of
+file then @code{u8-ready?} returns @code{#t}.
-port is at end of file then u8-ready? returns #t.
@end deffn
@deffn procedure read-bytevector k
@deffnx procedure read-bytevector k port
-Reads the next
+Reads the next @var{k} bytes, or as many as are available before the end of file,
+from the binary
+input @var{port} into a newly allocated bytevector in left-to-right order
+and returns the bytevector.
+If no bytes are available before the end of file,
+an end-of-file object is returned.
-k bytes, or as many as are available before the end of file, from the binary input
-
-port into a newly allocated bytevector in left-to-right order and returns the bytevector. If
-no bytes are available before the end of file, an end-of-file object is returned.
@end deffn
@deffn procedure read-bytevector! bytevector
@@ -391,21 +397,16 @@ no bytes are available before the end of file, an end-of-file object is returned
@deffnx procedure read-bytevector! bytevector port start
@deffnx procedure read-bytevector! bytevector port start end
-Reads the next end − start bytes, or as many as are available before the end of file, from
-the binary input
-
-port into
-
-bytevector in left-to-right order beginning at the
-
-start position. If
-
-end is not supplied, reads until the end of
-
-bytevector has been reached. If
+Reads the next @var{end} @minus{} @var{start} bytes, or as many as are available
+before the end of file,
+from the binary
+input @var{port} into @var{bytevector} in left-to-right order
+beginning at the @var{start} position. If @var{end} is not supplied,
+reads until the end of @var{bytevector} has been reached. If
+@var{start} is not supplied, reads beginning at position 0.
+Returns the number of bytes read.
+If no bytes are available, an end-of-file object is returned.
-start is not supplied, reads beginning at position 0. Returns the number of bytes read. If
-no bytes are available, an end-of-file object is returned.
@end deffn
@node Output
