[Guile-commits] GNU Guile branch, stable-2.0, updated. v2.0.1-37-g040dfa6

[Andreas Rottmann]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU Guile".

http://git.savannah.gnu.org/cgit/guile.git/commit/?id=040dfa6f3727342a9596b4cb0625f0e171c3d612

The branch, stable-2.0 has been updated
       via  040dfa6f3727342a9596b4cb0625f0e171c3d612 (commit)
      from  b706a0112978b1daa4535dff2808eac299167bbf (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 040dfa6f3727342a9596b4cb0625f0e171c3d612
Author: Andreas Rottmann <address@hidden>
Date:   Sat May 7 22:30:40 2011 +0200

    More completely document the `(rnrs io ports)' library
    
    * doc/ref/api-io.texi (R6RS I/O Ports): Transcribe missing parts from
      the R6RS document.

-----------------------------------------------------------------------

Summary of changes:
 doc/ref/api-io.texi |  689 +++++++++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 668 insertions(+), 21 deletions(-)

diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index e7e91ed..09fdc83 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -1152,22 +1152,364 @@ The I/O port API of the @uref{http://www.r6rs.org/, 
Revised Report^6 on
 the Algorithmic Language Scheme (R6RS)} is provided by the @code{(rnrs
 io ports)} module.  It provides features, such as binary I/O and Unicode
 string I/O, that complement or refine Guile's historical port API
-presented above (@pxref{Input and Output}).
+presented above (@pxref{Input and Output}). Note that R6RS ports are not
+disjoint from Guile's native ports, so Guile-specific procedures will
+work on ports created using the R6RS API, and vice versa.
+
+The text in this section is taken from the R6RS standard libraries
+document, with only minor adaptions for inclusion in this manual.  The
+Guile developers offer their thanks to the R6RS editors for having
+provided the report's text under permissive conditions making this
+possible.
 
 @c FIXME: Update description when implemented.
 @emph{Note}: The implementation of this R6RS API is not complete yet.
 
 @menu
+* R6RS File Names::             File names.
+* R6RS File Options::           Options for opening files.
+* R6RS Buffer Modes::           Influencing buffering behavior.
+* R6RS Transcoders::            Influencing port encoding.
 * R6RS End-of-File::            The end-of-file object.
 * R6RS Port Manipulation::      Manipulating R6RS ports.
+* R6RS Input Ports::            Input Ports.
 * R6RS Binary Input::           Binary input.
+* R6RS Textual Input::          Textual input.
+* R6RS Output Ports::           Output Ports.
 * R6RS Binary Output::          Binary output.
+* R6RS Textual Output::         Textual output.
 @end menu
 
 A subset of the @code{(rnrs io ports)} module is provided by the
 @code{(ice-9 binary-ports)} module.  It contains binary input/output
 procedures and does not rely on R6RS support.
 
address@hidden R6RS File Names
address@hidden File Names
+
+Some of the procedures described in this chapter accept a file name as an
+argument. Valid values for such a file name include strings that name a file
+using the native notation of filesystem paths on an implementation's
+underlying operating system, and may include implementation-dependent
+values as well.
+
+A @var{filename} parameter name means that the
+corresponding argument must be a file name.
+
address@hidden R6RS File Options
address@hidden File Options
address@hidden file options
+
+When opening a file, the various procedures in this library accept a
address@hidden object that encapsulates flags to specify how the
+file is to be opened. A @code{file-options} object is an enum-set
+(@pxref{rnrs enums}) over the symbols constituting valid file options.
+
+A @var{file-options} parameter name means that the corresponding
+argument must be a file-options object.
+
address@hidden {Scheme Syntax} file-options @var{file-options-symbol} ...
+
+Each @var{file-options-symbol} must be a symbol.
+
+The @code{file-options} syntax returns a file-options object that
+encapsulates the specified options.
+
+When supplied to an operation that opens a file for output, the
+file-options object returned by @code{(file-options)} specifies that the
+file is created if it does not exist and an exception with condition
+type @code{&i/o-file-already-exists} is raised if it does exist.  The
+following standard options can be included to modify the default
+behavior.
+
address@hidden @code
address@hidden no-create
+      If the file does not already exist, it is not created;
+      instead, an exception with condition type @code{&i/o-file-does-not-exist}
+      is raised.
+      If the file already exists, the exception with condition type
+      @code{&i/o-file-already-exists} is not raised
+      and the file is truncated to zero length.
address@hidden no-fail
+      If the file already exists, the exception with condition type
+      @code{&i/o-file-already-exists} is not raised,
+      even if @code{no-create} is not included,
+      and the file is truncated to zero length.
address@hidden no-truncate
+      If the file already exists and the exception with condition type
+      @code{&i/o-file-already-exists} has been inhibited by inclusion of
+      @code{no-create} or @code{no-fail}, the file is not truncated, but
+      the port's current position is still set to the beginning of the
+      file.
address@hidden table
+
+These options have no effect when a file is opened only for input.
+Symbols other than those listed above may be used as
address@hidden; they have implementation-specific meaning,
+if any.
+
address@hidden Note
+  Only the name of @var{file-options-symbol} is significant.
address@hidden quotation
address@hidden deffn
+
address@hidden R6RS Buffer Modes
address@hidden Buffer Modes
+
+Each port has an associated buffer mode.  For an output port, the
+buffer mode defines when an output operation flushes the buffer
+associated with the output port.  For an input port, the buffer mode
+defines how much data will be read to satisfy read operations.  The
+possible buffer modes are the symbols @code{none} for no buffering,
address@hidden for flushing upon line endings and reading up to line
+endings, or other implementation-dependent behavior,
+and @code{block} for arbitrary buffering.  This section uses
+the parameter name @var{buffer-mode} for arguments that must be
+buffer-mode symbols.
+
+If two ports are connected to the same mutable source, both ports
+are unbuffered, and reading a byte or character from that shared
+source via one of the two ports would change the bytes or characters
+seen via the other port, a lookahead operation on one port will
+render the peeked byte or character inaccessible via the other port,
+while a subsequent read operation on the peeked port will see the
+peeked byte or character even though the port is otherwise unbuffered.
+
+In other words, the semantics of buffering is defined in terms of side
+effects on shared mutable sources, and a lookahead operation has the
+same side effect on the shared source as a read operation.
+
address@hidden {Scheme Syntax} buffer-mode @var{buffer-mode-symbol}
+
address@hidden must be a symbol whose name is one of
address@hidden, @code{line}, and @code{block}. The result is the
+corresponding symbol, and specifies the associated buffer mode.
+
address@hidden Note
+  Only the name of @var{buffer-mode-symbol} is significant.
address@hidden quotation
address@hidden deffn
+
address@hidden {Scheme Procedure} buffer-mode?  obj
+Returns @code{#t} if the argument is a valid buffer-mode symbol, and
+returns @code{#f} otherwise.
address@hidden deffn
+
address@hidden R6RS Transcoders
address@hidden Transcoders
address@hidden codec
address@hidden end-of-line style
address@hidden transcoder
address@hidden binary port
address@hidden textual port
+
+Several different Unicode encoding schemes describe standard ways to
+encode characters and strings as byte sequences and to decode those
+sequences. Within this document, a @dfn{codec} is an immutable Scheme
+object that represents a Unicode or similar encoding scheme.
+
+An @dfn{end-of-line style} is a symbol that, if it is not @code{none},
+describes how a textual port transcodes representations of line endings.
+
+A @dfn{transcoder} is an immutable Scheme object that combines a codec
+with an end-of-line style and a method for handling decoding errors.
+Each transcoder represents some specific bidirectional (but not
+necessarily lossless), possibly stateful translation between byte
+sequences and Unicode characters and strings.  Every transcoder can
+operate in the input direction (bytes to characters) or in the output
+direction (characters to bytes).  A @var{transcoder} parameter name
+means that the corresponding argument must be a transcoder.
+
+A @dfn{binary port} is a port that supports binary I/O, does not have an
+associated transcoder and does not support textual I/O.  A @dfn{textual
+port} is a port that supports textual I/O, and does not support binary
+I/O.  A textual port may or may not have an associated transcoder.
+
address@hidden {Scheme Procedure} latin-1-codec
address@hidden {Scheme Procedure} utf-8-codec
address@hidden {Scheme Procedure} utf-16-codec
+
+These are predefined codecs for the ISO 8859-1, UTF-8, and UTF-16
+encoding schemes.
+
+A call to any of these procedures returns a value that is equal in the
+sense of @code{eqv?} to the result of any other call to the same
+procedure.
address@hidden deffn
+
address@hidden {Scheme Syntax} eol-style @var{eol-style-symbol}
+
address@hidden should be a symbol whose name is one of
address@hidden, @code{cr}, @code{crlf}, @code{nel}, @code{crnel}, @code{ls},
+and @code{none}.
+
+The form evaluates to the corresponding symbol.  If the name of
address@hidden is not one of these symbols, the effect and
+result are implementation-dependent; in particular, the result may be an
+eol-style symbol acceptable as an @var{eol-style} argument to
address@hidden  Otherwise, an exception is raised.
+
+All eol-style symbols except @code{none} describe a specific
+line-ending encoding:
+
address@hidden @code
address@hidden lf
+linefeed
address@hidden cr
+carriage return
address@hidden crlf
+carriage return, linefeed
address@hidden nel
+next line
address@hidden crnel
+carriage return, next line
address@hidden ls
+line separator
address@hidden table
+
+For a textual port with a transcoder, and whose transcoder has an
+eol-style symbol @code{none}, no conversion occurs.  For a textual input
+port, any eol-style symbol other than @code{none} means that all of the
+above line-ending encodings are recognized and are translated into a
+single linefeed.  For a textual output port, @code{none} and @code{lf}
+are equivalent.  Linefeed characters are encoded according to the
+specified eol-style symbol, and all other characters that participate in
+possible line endings are encoded as is.
+
address@hidden Note
+  Only the name of @var{eol-style-symbol} is significant.
address@hidden quotation
address@hidden deffn
+
address@hidden {Scheme Procedure} native-eol-style
+Returns the default end-of-line style of the underlying platform, e.g.,
address@hidden on Unix and @code{crlf} on Windows.
address@hidden deffn
+
address@hidden {Condition Type} &i/o-decoding
address@hidden {Scheme Procedure} make-i/o-decoding-error  port
address@hidden {Scheme Procedure} i/o-decoding-error?  obj
+
+This condition type could be defined by
+
address@hidden
+(define-condition-type &i/o-decoding &i/o-port
+  make-i/o-decoding-error i/o-decoding-error?)
address@hidden lisp
+
+An exception with this type is raised when one of the operations for
+textual input from a port encounters a sequence of bytes that cannot be
+translated into a character or string by the input direction of the
+port's transcoder.
+
+When such an exception is raised, the port's position is past the
+invalid encoding.
address@hidden deffn
+
address@hidden {Condition Type} &i/o-encoding
address@hidden {Scheme Procedure} make-i/o-encoding-error  port char
address@hidden {Scheme Procedure} i/o-encoding-error?  obj
address@hidden {Scheme Procedure} i/o-encoding-error-char  condition
+
+This condition type could be defined by
+
address@hidden
+(define-condition-type &i/o-encoding &i/o-port
+  make-i/o-encoding-error i/o-encoding-error?
+  (char i/o-encoding-error-char))
address@hidden lisp
+
+An exception with this type is raised when one of the operations for
+textual output to a port encounters a character that cannot be
+translated into bytes by the output direction of the port's transcoder.
address@hidden is the character that could not be encoded.
address@hidden deffn
+
address@hidden {Scheme Syntax} error-handling-mode 
@var{error-handling-mode-symbol}
+
address@hidden should be a symbol whose name is one of
address@hidden, @code{raise}, and @code{replace}. The form evaluates to
+the corresponding symbol.  If @var{error-handling-mode-symbol} is not
+one of these identifiers, effect and result are
+implementation-dependent: The result may be an error-handling-mode
+symbol acceptable as a @var{handling-mode} argument to
address@hidden  If it is not acceptable as a
address@hidden argument to @code{make-transcoder}, an exception is
+raised.
+
address@hidden Note
+  Only the name of @var{error-handling-style-symbol} is significant.
address@hidden quotation
+
+The error-handling mode of a transcoder specifies the behavior
+of textual I/O operations in the presence of encoding or decoding
+errors.
+
+If a textual input operation encounters an invalid or incomplete
+character encoding, and the error-handling mode is @code{ignore}, an
+appropriate number of bytes of the invalid encoding are ignored and
+decoding continues with the following bytes.
+
+If the error-handling mode is @code{replace}, the replacement
+character U+FFFD is injected into the data stream, an appropriate
+number of bytes are ignored, and decoding
+continues with the following bytes.
+
+If the error-handling mode is @code{raise}, an exception with condition
+type @code{&i/o-decoding} is raised.
+
+If a textual output operation encounters a character it cannot encode,
+and the error-handling mode is @code{ignore}, the character is ignored
+and encoding continues with the next character.  If the error-handling
+mode is @code{replace}, a codec-specific replacement character is
+emitted by the transcoder, and encoding continues with the next
+character.  The replacement character is U+FFFD for transcoders whose
+codec is one of the Unicode encodings, but is the @code{?}  character
+for the Latin-1 encoding.  If the error-handling mode is @code{raise},
+an exception with condition type @code{&i/o-encoding} is raised.
address@hidden deffn
+
address@hidden {Scheme Procedure} make-transcoder  codec
address@hidden {Scheme Procedure} make-transcoder codec eol-style
address@hidden {Scheme Procedure} make-transcoder codec eol-style handling-mode
+
address@hidden must be a codec; @var{eol-style}, if present, an eol-style
+symbol; and @var{handling-mode}, if present, an error-handling-mode
+symbol.
+
address@hidden may be omitted, in which case it defaults to the native
+end-of-line style of the underlying platform.  @var{Handling-mode} may
+be omitted, in which case it defaults to @code{replace}.  The result is
+a transcoder with the behavior specified by its arguments.
address@hidden deffn
+
address@hidden {Scheme procedure} native-transcoder
+Returns an implementation-dependent transcoder that represents a
+possibly locale-dependent ``native'' transcoding.
address@hidden deffn
+
address@hidden {Scheme Procedure} transcoder-codec  transcoder
address@hidden {Scheme Procedure} transcoder-eol-style  transcoder
address@hidden {Scheme Procedure} transcoder-error-handling-mode  transcoder
+
+These are accessors for transcoder objects; when applied to a
+transcoder returned by @code{make-transcoder}, they return the
address@hidden, @var{eol-style}, and @var{handling-mode} arguments,
+respectively.
address@hidden deffn
+
address@hidden {Scheme Procedure} bytevector->string  bytevector transcoder
+
+Returns the string that results from transcoding the
address@hidden according to the input direction of the transcoder.
address@hidden deffn
+
address@hidden {Scheme Procedure} string->bytevector  string transcoder
+
+Returns the bytevector that results from transcoding the
address@hidden according to the output direction of the transcoder.
address@hidden deffn
+
 @node R6RS End-of-File
 @subsubsection The End-of-File Object
 
@@ -1200,6 +1542,65 @@ Return the end-of-file (EOF) object.
 
 The procedures listed below operate on any kind of R6RS I/O port.
 
address@hidden {Scheme Procedure} port? obj
+Returns @code{#t} if the argument is a port, and returns @code{#f}
+otherwise.
address@hidden deffn
+
address@hidden {Scheme Procedure} port-transcoder port
+Returns the transcoder associated with @var{port} if @var{port} is
+textual and has an associated transcoder, and returns @code{#f} if
address@hidden is binary or does not have an associated transcoder.
address@hidden deffn
+
address@hidden {Scheme Procedure} binary-port? port
+Return @code{#t} if @var{port} is a @dfn{binary port}, suitable for
+binary data input/output.
+
+Note that internally Guile does not differentiate between binary and
+textual ports, unlike the R6RS.  Thus, this procedure returns true when
address@hidden does not have an associated encoding---i.e., when
address@hidden(port-encoding @var{port})} is @code{#f} (@pxref{Ports,
+port-encoding}).  This is the case for ports returned by R6RS procedures
+such as @code{open-bytevector-input-port} and
address@hidden
+
+However, Guile currently does not prevent use of textual I/O procedures
+such as @code{display} or @code{read-char} with binary ports.  Doing so
+``upgrades'' the port from binary to textual, under the ISO-8859-1
+encoding.  Likewise, Guile does not prevent use of
address@hidden on a binary port, which also turns it into a
+``textual'' port.
address@hidden deffn
+
address@hidden {Scheme Procedure} textual-port? port
+Always return @var{#t}, as all ports can be used for textual I/O in
+Guile.
address@hidden deffn
+
address@hidden {Scheme Procedure} transcoded-port obj
+The @code{transcoded-port} procedure
+returns a new textual port with the specified @var{transcoder}.
+Otherwise the new textual port's state is largely the same as
+that of @var{binary-port}.
+If @var{binary-port} is an input port, the new textual
+port will be an input port and
+will transcode the bytes that have not yet been read from
address@hidden
+If @var{binary-port} is an output port, the new textual
+port will be an output port and
+will transcode output characters into bytes that are
+written to the byte sink represented by @var{binary-port}.
+
+As a side effect, however, @code{transcoded-port}
+closes @var{binary-port} in
+a special way that allows the new textual port to continue to
+use the byte source or sink represented by @var{binary-port},
+even though @var{binary-port} itself is closed and cannot
+be used by the input and output operations described in this
+chapter.
address@hidden deffn
+
 @deffn {Scheme Procedure} port-position port
 If @var{port} supports it (see below), return the offset (an integer)
 indicating where the next octet will be read from/written to in
@@ -1233,31 +1634,67 @@ Call @var{proc}, passing it @var{port} and closing 
@var{port} upon exit
 of @var{proc}.  Return the return values of @var{proc}.
 @end deffn
 
address@hidden {Scheme Procedure} binary-port? port
-Return @code{#t} if @var{port} is a @dfn{binary port}, suitable for
-binary data input/output.
address@hidden R6RS Input Ports
address@hidden Input Ports
 
-Note that internally Guile does not differentiate between binary and
-textual ports, unlike the R6RS.  Thus, this procedure returns true when
address@hidden does not have an associated encoding---i.e., when
address@hidden(port-encoding @var{port})} is @code{#f} (@pxref{Ports,
-port-encoding}).  This is the case for ports returned by R6RS procedures
-such as @code{open-bytevector-input-port} and
address@hidden
address@hidden {Scheme Procedure} input-port? obj@
+Returns @code{#t} if the argument is an input port (or a combined input
+and output port), and returns @code{#f} otherwise.
address@hidden deffn
 
-However, Guile currently does not prevent use of textual I/O procedures
-such as @code{display} or @code{read-char} with binary ports.  Doing so
-``upgrades'' the port from binary to textual, under the ISO-8859-1
-encoding.  Likewise, Guile does not prevent use of
address@hidden on a binary port, which also turns it into a
-``textual'' port.
address@hidden {Scheme Procedure} port-eof? port
+Returns @code{#t}
+if the @code{lookahead-u8} procedure (if @var{input-port} is a binary port)
+or the @code{lookahead-char} procedure (if @var{input-port} is a textual port)
+would return
+the end-of-file object, and @code{#f} otherwise.
+The operation may block indefinitely if no data is available
+but the port cannot be determined to be at end of file.
 @end deffn
 
address@hidden {Scheme Procedure} textual-port? port
-Always return @var{#t}, as all ports can be used for textual I/O in
-Guile.
address@hidden {Scheme Procedure} open-file-input-port filename
address@hidden {Scheme Procedure} open-file-input-port filename file-options
address@hidden {Scheme Procedure} open-file-input-port filename file-options 
buffer-mode
address@hidden {Scheme Procedure} open-file-input-port filename file-options 
buffer-mode maybe-transcoder
address@hidden must be either a transcoder or @code{#f}.
+
+The @code{open-file-input-port} procedure returns an
+input port for the named file. The @var{file-options} and
address@hidden arguments are optional.
+
+The @var{file-options} argument, which may determine
+various aspects of the returned port (@pxref{R6RS File Options}),
+defaults to the value of @code{(file-options)}.
+
+The @var{buffer-mode} argument, if supplied,
+must be one of the symbols that name a buffer mode.
+The @var{buffer-mode} argument defaults to @code{block}.
+
+If @var{maybe-transcoder} is a transcoder, it becomes the transcoder associated
+with the returned port.
+
+If @var{maybe-transcoder} is @code{#f} or absent,
+the port will be a binary port and will support the
address@hidden and @code{set-port-position!}  operations.
+Otherwise the port will be a textual port, and whether it supports
+the @code{port-position} and @code{set-port-position!} operations
+is implementation-dependent (and possibly transcoder-dependent).
 @end deffn
 
address@hidden {Scheme Procedure} standard-input-port
+Returns a fresh binary input port connected to standard input.  Whether
+the port supports the @code{port-position} and @code{set-port-position!}
+operations is implementation-dependent.
address@hidden deffn
+
address@hidden {Scheme Procedure} current-input-port
+This returns a default textual port for input.  Normally, this default
+port is associated with standard input, but can be dynamically
+re-assigned using the @code{with-input-from-file} procedure from the
address@hidden simple (6)} library (@pxref{rnrs io simple}).  The port may or
+may not have an associated transcoder; if it does, the transcoder is
+implementation-dependent.
address@hidden deffn
 
 @node R6RS Binary Input
 @subsubsection Binary Input
@@ -1374,6 +1811,173 @@ reached.  Return either a new bytevector containing the 
data read or the
 end-of-file object (if no data were available).
 @end deffn
 
address@hidden R6RS Textual Input
address@hidden Textual Input
+
address@hidden {Scheme Procedure} get-char port
+Reads from @var{textual-input-port}, blocking as necessary, until a
+complete character is available from @var{textual-input-port},
+or until an end of file is reached.
+
+If a complete character is available before the next end of file,
address@hidden returns that character and updates the input port to
+point past the character. If an end of file is reached before any
+character is read, @code{get-char} returns the end-of-file object.
address@hidden deffn
+
address@hidden {Scheme Procedure} lookahead-char port
+The @code{lookahead-char} procedure is like @code{get-char}, but it does
+not update @var{textual-input-port} to point past the character.
address@hidden deffn
+
address@hidden {Scheme Procedure} get-string-n port count
+
address@hidden must be an exact, non-negative integer object, representing
+the number of characters to be read.
+
+The @code{get-string-n} procedure reads from @var{textual-input-port},
+blocking as necessary, until @var{count} characters are available, or
+until an end of file is reached.
+
+If @var{count} characters are available before end of file,
address@hidden returns a string consisting of those @var{count}
+characters. If fewer characters are available before an end of file, but
+one or more characters can be read, @code{get-string-n} returns a string
+containing those characters. In either case, the input port is updated
+to point just past the characters read. If no characters can be read
+before an end of file, the end-of-file object is returned.
address@hidden deffn
+
address@hidden {Scheme Procedure} get-string-n! port string start count
+
address@hidden and @var{count} must be exact, non-negative integer objects,
+with @var{count} representing the number of characters to be read.
address@hidden must be a string with at least address@hidden + @var{count}$
+characters.
+
+The @code{get-string-n!} procedure reads from @var{textual-input-port}
+in the same manner as @code{get-string-n}.  If @var{count} characters
+are available before an end of file, they are written into @var{string}
+starting at index @var{start}, and @var{count} is returned. If fewer
+characters are available before an end of file, but one or more can be
+read, those characters are written into @var{string} starting at index
address@hidden and the number of characters actually read is returned as an
+exact integer object. If no characters can be read before an end of
+file, the end-of-file object is returned.
address@hidden deffn
+
address@hidden {Scheme Procedure} get-string-all port count
+Reads from @var{textual-input-port} until an end of file, decoding
+characters in the same manner as @code{get-string-n} and
address@hidden
+
+If characters are available before the end of file, a string containing
+all the characters decoded from that data are returned. If no character
+precedes the end of file, the end-of-file object is returned.
address@hidden deffn
+
address@hidden {Scheme Procedure} get-line port
+Reads from @var{textual-input-port} up to and including the linefeed
+character or end of file, decoding characters in the same manner as
address@hidden and @code{get-string-n!}.
+
+If a linefeed character is read, a string containing all of the text up
+to (but not including) the linefeed character is returned, and the port
+is updated to point just past the linefeed character. If an end of file
+is encountered before any linefeed character is read, but some
+characters have been read and decoded as characters, a string containing
+those characters is returned. If an end of file is encountered before
+any characters are read, the end-of-file object is returned.
+
address@hidden Note
+  The end-of-line style, if not @code{none}, will cause all line endings
+  to be read as linefeed characters.  @xref{R6RS Transcoders}.
address@hidden quotation
address@hidden deffn
+
address@hidden {Scheme Procedure} get-datum port count
+Reads an external representation from @var{textual-input-port} and returns the
+datum it represents.  The @code{get-datum} procedure returns the next
+datum that can be parsed from the given @var{textual-input-port}, updating
address@hidden to point exactly past the end of the external
+representation of the object.
+
+Any @emph{interlexeme space} (comment or whitespace, @pxref{Scheme
+Syntax}) in the input is first skipped.  If an end of file occurs after
+the interlexeme space, the end-of-file object (@pxref{R6RS End-of-File})
+is returned.
+
+If a character inconsistent with an external representation is
+encountered in the input, an exception with condition types
address@hidden&lexical} and @code{&i/o-read} is raised.  Also, if the end of
+file is encountered after the beginning of an external representation,
+but the external representation is incomplete and therefore cannot be
+parsed, an exception with condition types @code{&lexical} and
address@hidden&i/o-read} is raised.
address@hidden deffn
+
address@hidden R6RS Output Ports
address@hidden Output Ports
+
address@hidden {Scheme Procedure} output-port? obj
+Returns @code{#t} if the argument is an output port (or a
+combined input and output port), @code{#f} otherwise.
address@hidden deffn
+
address@hidden {Scheme Procedure} flush-output-port port
+Flushes any buffered output from the buffer of @var{output-port} to the
+underlying file, device, or object. The @code{flush-output-port}
+procedure returns an unspecified values.
address@hidden deffn
+
address@hidden {Scheme Procedure} open-file-output-port filename
address@hidden {Scheme Procedure} open-file-output-port filename file-options
address@hidden {Scheme Procedure} open-file-output-port filename file-options 
buffer-mode
address@hidden {Scheme Procedure} open-file-output-port filename file-options 
buffer-mode maybe-transcoder
+
address@hidden must be either a transcoder or @code{#f}.
+
+The @code{open-file-output-port} procedure returns an output port for the 
named file.
+
+The @var{file-options} argument, which may determine various aspects of
+the returned port (@pxref{R6RS File Options}), defaults to the value of
address@hidden(file-options)}.
+
+The @var{buffer-mode} argument, if supplied,
+must be one of the symbols that name a buffer mode.
+The @var{buffer-mode} argument defaults to @code{block}.
+
+If @var{maybe-transcoder} is a transcoder, it becomes the transcoder
+associated with the port.
+
+If @var{maybe-transcoder} is @code{#f} or absent,
+the port will be a binary port and will support the
address@hidden and @code{set-port-position!}  operations.
+Otherwise the port will be a textual port, and whether it supports
+the @code{port-position} and @code{set-port-position!} operations
+is implementation-dependent (and possibly transcoder-dependent).
address@hidden deffn
+
address@hidden {Scheme Procedure} standard-output-port
address@hidden {Scheme Procedure} standard-error-port
+Returns a fresh binary output port connected to the standard output or
+standard error respectively.  Whether the port supports the
address@hidden and @code{set-port-position!} operations is
+implementation-dependent.
address@hidden deffn
+
address@hidden {Scheme Procedure} current-output-port
address@hidden {Scheme Procedure} current-error-port
+These return default textual ports for regular output and error output.
+Normally, these default ports are associated with standard output, and
+standard error, respectively.  The return value of
address@hidden can be dynamically re-assigned using the
address@hidden procedure from the @code{io simple (6)}
+library (@pxref{rnrs io simple}).  A port returned by one of these
+procedures may or may not have an associated transcoder; if it does, the
+transcoder is implementation-dependent.
address@hidden deffn
+
 @node R6RS Binary Output
 @subsubsection Binary Output
 
@@ -1432,6 +2036,50 @@ Write the contents of @var{bv} to @var{port}, optionally 
starting at
 index @var{start} and limiting to @var{count} octets.
 @end deffn
 
address@hidden R6RS Textual Output
address@hidden Textual Output
+
address@hidden {Scheme Procedure} put-char port char
+Writes @var{char} to the port. The @code{put-char} procedure returns
address@hidden deffn
+
address@hidden {Scheme Procedure} put-string port string
address@hidden {Scheme Procedure} put-string port string start
address@hidden {Scheme Procedure} put-string port string start count
+
address@hidden and @var{count} must be non-negative exact integer objects.
address@hidden must have a length of at least @address@hidden +
address@hidden  @var{start} defaults to 0.  @var{count} defaults to
address@hidden@code{(string-length @var{string})} - @var{start}}$. The
address@hidden procedure writes the @var{count} characters of
address@hidden starting at index @var{start} to the port.  The
address@hidden procedure returns an unspecified value.
address@hidden deffn
+
address@hidden {Scheme Procedure} put-datum port datum
address@hidden should be a datum value.  The @code{put-datum} procedure
+writes an external representation of @var{datum} to
address@hidden  The specific external representation is
+implementation-dependent.  However, whenever possible, an implementation
+should produce a representation for which @code{get-datum}, when reading
+the representation, will return an object equal (in the sense of
address@hidden) to @var{datum}.
+
address@hidden Note
+  Not all datums may allow producing an external representation for which
+  @code{get-datum} will produce an object that is equal to the
+  original.  Specifically, NaNs contained in @var{datum} may make
+  this impossible.
address@hidden quotation
+
address@hidden Note
+  The @code{put-datum} procedure merely writes the external
+  representation, but no trailing delimiter.  If @code{put-datum} is
+  used to write several subsequent external representations to an
+  output port, care should be taken to delimit them properly so they can
+  be read back in by subsequent calls to @code{get-datum}.
address@hidden quotation
address@hidden deffn
 
 @node I/O Extensions
 @subsection Using and Extending Ports in C
@@ -1690,7 +2338,6 @@ Set using
 
 @end table
 
-
 @c Local Variables:
 @c TeX-master: "guile.texi"
 @c End:


hooks/post-receive
-- 
GNU Guile