[Guile-commits] 12/21: Update port documentation

[Andy Wingo]

wingo pushed a commit to branch wip-port-refactor
in repository guile.

commit af1c443f83b492d97cba80648d9f3d7299440978
Author: Andy Wingo <address@hidden>
Date:   Fri May 13 16:48:02 2016 +0200

    Update port documentation
    
    * doc/ref/api-io.texi: Update for refactorings.
---
 doc/ref/api-io.texi |  120 ++++++++++++++++++---------------------------------
 1 file changed, 41 insertions(+), 79 deletions(-)

diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index 1a9c821..41efb35 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -230,9 +230,9 @@ Return the next character available from @var{port}, 
updating
 @var{port} to point to the following character.  If no more
 characters are available, the end-of-file object is returned.
 
-When @var{port}'s data cannot be decoded according to its
-character encoding, a @code{decoding-error} is raised and
address@hidden points past the erroneous byte sequence.
+When @var{port}'s data cannot be decoded according to its character
+encoding, a @code{decoding-error} is raised and @var{port} is not
+advanced past the erroneous byte sequence.
 @end deffn
 
 @deftypefn {C Function} size_t scm_c_read (SCM port, void *buffer, size_t size)
@@ -263,9 +263,7 @@ an interactive port will hang waiting for input whenever a 
call
 to @code{read-char} would have hung.
 
 As for @code{read-char}, a @code{decoding-error} may be raised
-if such a situation occurs.  However, unlike with @code{read-char},
address@hidden still points at the beginning of the erroneous byte
-sequence when the error is raised.
+if such a situation occurs.
 @end deffn
 
 @deffn {Scheme Procedure} unread-char cobj [port]
@@ -355,17 +353,13 @@ a print state, the old print state is reused.
 
 @deffn {Scheme Procedure} simple-format destination message . args
 @deffnx {C Function} scm_simple_format (destination, message, args)
-Write @var{message} to @var{destination}, defaulting to
-the current output port.
address@hidden can contain @code{~A} (was @code{%s}) and
address@hidden (was @code{%S}) escapes.  When printed,
-the escapes are replaced with corresponding members of
address@hidden:
address@hidden formats using @code{display} and @code{~S} formats
-using @code{write}.
-If @var{destination} is @code{#t}, then use the current output
-port, if @var{destination} is @code{#f}, then return a string
-containing the formatted text. Does not add a trailing newline.
+Write @var{message} to @var{destination}, defaulting to the current
+output port.  @var{message} can contain @code{~A} and @code{~S} escapes.
+When printed, the escapes are replaced with corresponding members of
address@hidden: @code{~A} formats using @code{display} and @code{~S} formats
+using @code{write}.  If @var{destination} is @code{#t}, then use the
+current output port, if @var{destination} is @code{#f}, then return a
+string containing the formatted text.  Does not add a trailing newline.
 @end deffn
 
 @rnindex write-char
@@ -415,10 +409,10 @@ all open output ports.  The return value is unspecified.
 
 @deffn {Scheme Procedure} close-port port
 @deffnx {C Function} scm_close_port (port)
-Close the specified port object.  Return @code{#t} if it
-successfully closes a port or @code{#f} if it was already
-closed.  An exception may be raised if an error occurs, for
-example when flushing buffered output.  See also @ref{Ports and
+Close the specified port object.  Return @code{#t} if it successfully
+closes a port or @code{#f} if it was already closed.  An exception may
+be raised if an error occurs, for example when flushing buffered output.
address@hidden, for more on buffered output.  See also @ref{Ports and
 File Descriptors, close}, for a procedure which can close file
 descriptors.
 @end deffn
@@ -499,7 +493,7 @@ as a block, without regard to what is in the block.  
Likewise reads are
 read in at the block size, though if there are fewer bytes available to
 read, the buffer may not be entirely filled.
 
-Note that reads or writes that are larger than the buffer size go
+Note that binary reads or writes that are larger than the buffer size go
 directly to the mutable store without passing through the buffers.  If
 your access pattern involves many big reads or writes, buffering might
 not matter so much to you.
@@ -923,8 +917,6 @@ initialized with the @var{port} argument.
 @cindex Types of ports
 @cindex Port, types
 
-[Types of port; how to make them.]
-
 @menu
 * File Ports:: Ports on an operating system file.
 * String Ports:: Ports on a Scheme string.
@@ -1017,25 +1009,6 @@ is requested.
 
 If a file cannot be opened with the access requested, @code{open-file}
 throws an exception.
-
-When the file is opened, its encoding is set to the current
address@hidden, unless the @code{b} flag was supplied.
-Sometimes it is desirable to honor Emacs-style coding declarations in
address@hidden 2.0.0 to 2.0.7 would do this by default.  This
-behavior was deemed inappropriate and disabled starting from Guile
-2.0.8.}.  When that is the case, the @code{file-encoding} procedure can
-be used as follows (@pxref{Character Encoding of Source Files,
address@hidden):
-
address@hidden
-(let* ((port     (open-input-file file))
-       (encoding (file-encoding port)))
-  (set-port-encoding! port (or encoding (port-encoding port))))
address@hidden example
-
-In theory we could create read/write ports which were buffered
-in one direction only.  However this isn't included in the
-current interfaces.
 @end deffn
 
 @rnindex open-input-file
@@ -2256,47 +2229,36 @@ the representation, will return an object equal (in the 
sense of
 @node I/O Extensions
 @subsection Implementing New Port Types in C
 
-This section describes how to implement a new port type in C.  Before
-getting to the details, here is a summary of how the generic port
-interface works internally.
-
address@hidden ptob
address@hidden scm_t_ptob_descriptor
address@hidden scm_t_port
address@hidden SCM_PTAB_ENTRY
address@hidden SCM_PTOBNUM
address@hidden scm_ptobs
-Guile's port facility consists of two main data types: port type objects
-and port instances.  A port type object (or @dfn{ptob}) is of type
address@hidden, and holds pointers to the methods that
-implement the port type.  A port instance is of type @code{scm_t_port},
-and holds all state for the port.
-
-Given an @code{SCM} variable which points to a port, the corresponding C
-port object can be obtained using the @code{SCM_PTAB_ENTRY} macro.  The
-ptob can be obtained by using @code{SCM_PTOBNUM} to give an index into
-the @code{scm_ptobs} global array.
+This section describes how to implement a new port type in C.  Although
+ports support many operations, as a data structure they present an
+opaque interface to the user.  To the port implementor, you have two
+additional pieces of information: the port type code, which you allocate
+when defining your port type; and a port's ``stream'', which you
+allocate when you create a port.
 
address@hidden C interface
+The type code helps you identify which ports are actually yours.  The
+``stream'' is the private data associated with that port which you and
+only you control.  Get a stream from a port using the @code{SCM_STREAM}
+macro.
 
-A port type object is created by calling @code{scm_make_port_type}.
+A port type is created by calling @code{scm_make_port_type}.
 
 @deftypefun scm_t_bits scm_make_port_type (char *name, size_t (*read) (SCM 
port, SCM dst, size_t start, size_t count), size_t (*write) (SCM port, SCM src, 
size_t start, size_t count))
-Return a new port type object.  The @var{name}, @var{read} and
address@hidden parameters are initial values for those port type fields, as
-described below.  The other fields are initialized with default values
-and can be changed later.
+Define a new port type.  The @var{name}, @var{read} and @var{write}
+parameters are initial values for those port type fields, as described
+below.  The other fields are initialized with default values and can be
+changed later.
 @end deftypefun
 
-All of the elements of the port type object, apart from @code{name}, are
-procedures which collectively implement the port behaviour.  Creating a
-new port type mostly involves writing these procedures.
+The port type has a number of associate procedures and properties which
+collectively implement the port's behavior.  Creating a new port type
+mostly involves writing these procedures.
 
 @table @code
 @item name
 A pointer to a NUL terminated string: the name of the port type.  This
-is the only element of @code{scm_t_ptob_descriptor} which is not
-a procedure.  Set via the first argument to @code{scm_make_port_type}.
+property is initialized via the first argument to
address@hidden
 
 @item read
 A port's @code{read} implementation fills read buffers.  It should copy
@@ -2312,12 +2274,12 @@ starting at offset @code{start} and continuing for 
@code{count} bytes,
 and return the number of bytes that were written.
 
 @item print
-Called when @code{write} is called on the port object, to print a
-port description.  E.g., for an fport it may produce something like:
address@hidden<input: /etc/passwd 3>}.   Set using
+Called when @code{write} is called on the port, to print a port
+description.  For example, for a file port it may produce something
+like: @code{#<input: /etc/passwd 3>}.  Set using
 
 @deftypefun void scm_set_port_print (scm_t_bits tc, int (*print) (SCM port, 
SCM dest_port, scm_print_state *pstate))
-The first argument @var{port} is the object being printed, the second
+The first argument @var{port} is the port being printed, the second
 argument @var{dest_port} is where its description should go.
 @end deftypefun
 
@@ -2455,7 +2417,7 @@ BOM.  Similarly, if the user writes first, then later 
reads will
 @emph{not} consume a BOM.
 
 @item
-For ports that do not support seeking (e.g. pipes, sockets, and
+For ports that are not random access (e.g. pipes, sockets, and
 terminals), the input and output streams are considered
 @emph{independent} for purposes of BOM handling: the first read will
 consume a BOM (if appropriate), and the first write will @emph{also}