[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Guile-commits] 18/21: Document scm_c_make_port and friends
From: |
Andy Wingo |
Subject: |
[Guile-commits] 18/21: Document scm_c_make_port and friends |
Date: |
Mon, 16 May 2016 07:39:35 +0000 (UTC) |
wingo pushed a commit to branch wip-port-refactor
in repository guile.
commit 556ac9777b06c0d53713752b1b3ccd6480baf118
Author: Andy Wingo <address@hidden>
Date: Sat May 14 23:27:38 2016 +0200
Document scm_c_make_port and friends
* doc/ref/api-io.texi (I/O Extensions): Document scm_c_make_port and
friends, and document "mode bits".
---
doc/ref/api-io.texi | 22 +++++++++++++++++++++-
1 file changed, 21 insertions(+), 1 deletion(-)
diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index 8c91bae..23d3b50 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -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
address@hidden 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)
address@hidden 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
address@hidden, except it uses the default port
+encoding and conversion strategy.
address@hidden 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.
- [Guile-commits] branch wip-port-refactor updated (d28d1a5 -> da456d2), Andy Wingo, 2016/05/16
- [Guile-commits] 07/21: Embed scm_t_port in scm_t_port_internal, Andy Wingo, 2016/05/16
- [Guile-commits] 21/21: Bump objcode version, Andy Wingo, 2016/05/16
- [Guile-commits] 02/21: Implement lookahead-u8, get-u8 in Scheme, Andy Wingo, 2016/05/16
- [Guile-commits] 10/21: Make scm_t_port private, Andy Wingo, 2016/05/16
- [Guile-commits] 17/21: Update port mode bits documentation., Andy Wingo, 2016/05/16
- [Guile-commits] 08/21: Make file/line/column fields of ports private, Andy Wingo, 2016/05/16
- [Guile-commits] 20/21: Update NEWS for release, Andy Wingo, 2016/05/16
- [Guile-commits] 18/21: Document scm_c_make_port and friends,
Andy Wingo <=
- [Guile-commits] 01/21: %read-char speedup, Andy Wingo, 2016/05/16
- [Guile-commits] 12/21: Update port documentation, Andy Wingo, 2016/05/16
- [Guile-commits] 04/21: Add (ice-9 sports) module, Andy Wingo, 2016/05/16
- [Guile-commits] 13/21: Make scm_t_ptob_descriptor private., Andy Wingo, 2016/05/16
- [Guile-commits] 15/21: Update port type documentation, Andy Wingo, 2016/05/16
- [Guile-commits] 09/21: Make port buffering fields private, Andy Wingo, 2016/05/16
- [Guile-commits] 16/21: Add SCM_OPN to mode bits when making ports, Andy Wingo, 2016/05/16
- [Guile-commits] 03/21: Beginnings of shunting ports-in-scheme off to a module, Andy Wingo, 2016/05/16
- [Guile-commits] 14/21: Use heap-allocated port types instead of ptobnums, Andy Wingo, 2016/05/16
- [Guile-commits] 11/21: Remove scm_t_port_internal, Andy Wingo, 2016/05/16