mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-05-20 03:30:27 +02:00
Code Activity

Document scm_c_make_port and friends

Browse source 
* doc/ref/api-io.texi (I/O Extensions): Document scm_c_make_port and
  friends, and document "mode bits".
This commit is contained in:
Andy Wingo 2016-05-14 23:27:38 +02:00
parent a9d0fe9ea1
commit 556ac9777b
1 changed files with 21 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

22
doc/ref/api-io.texi
View file

@ -2242,7 +2242,9 @@ only you control. Get a stream from a port using the @code{SCM_STREAM}
macro. Note that your port methods are only ever called with ports of
your type.
A port type is created by calling @code{scm_make_port_type}.
A port type is created by calling @code{scm_make_port_type}. Once you
have your port type, you can create ports with @code{scm_c_make_port},
or @code{scm_c_make_port_with_encoding}.
@deftypefun scm_t_port_type* 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))
Define a new port type. The @var{name}, @var{read} and @var{write}
@ -2251,6 +2253,24 @@ below. The other fields are initialized with default values and can be
changed later.
@end deftypefun
@deftypefun SCM scm_c_make_port_with_encoding (scm_t_port_type *type, unsigned long mode_bits, SCM encoding, SCM conversion_strategy, scm_t_bits stream)
@deftypefunx SCM scm_c_make_port (scm_t_port_type *type, unsigned long mode_bits, scm_t_bits stream)
Make a port with the given @var{type}. The @var{stream} indicates the
private data associated with the port, which your port implementation
may later retrieve with @code{SCM_STREAM}. The mode bits should include
one or more of the flags @code{SCM_RDNG} or @code{SCM_WRTNG}, indicating
that the port is an input and/or an output port, respectively. The mode
bits may also include @code{SCM_BUF0} or @code{SCM_BUFLINE}, indicating
that the port should be unbuffered or line-buffered, respectively. The
default is that the port will be block-buffered. @xref{Buffering}.
As you would imagine, @var{encoding} and @var{conversion_strategy}
specify the port's initial textual encoding and conversion strategy.
Both are symbols. @code{scm_c_make_port} is the same as
@code{scm_c_make_port_with_encoding}, except it uses the default port
encoding and conversion strategy.
@end deftypefun
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.