From cf401612ba117ad4803fc05f704c29cd7b279dab Mon Sep 17 00:00:00 2001 From: =?utf8?q?Ludovic=20Court=C3=A8s?= Date: Thu, 9 Apr 2009 01:02:13 +0200 Subject: [PATCH] doc: Started documenting `(rnrs io ports)'. * doc/api-r6rs.texi (R6RS I/O Ports): New node. --- doc/api-r6rs.texi | 175 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) diff --git a/doc/api-r6rs.texi b/doc/api-r6rs.texi index 59123f5..3d80436 100644 --- a/doc/api-r6rs.texi +++ b/doc/api-r6rs.texi @@ -7,6 +7,7 @@ Language'' aka. @url{http://www.r6rs.org/, R6RS}. @menu * Bytevectors:: Interpreting raw bit strings. +* R6RS I/O Ports:: Input/output ports. @end menu @c ********************************************************************* @@ -371,6 +372,180 @@ or UTF-32-decoded contents of bytevector @var{utf}. @end deffn +@c ********************************************************************* +@node R6RS I/O Ports +@section I/O Ports + +The I/O port API of the R6RS is provided by the @code{(rnrs io ports)} +module. In many areas it complements or refines Guile's own historical +port API (@pxref{Input and Output,,, guile, The GNU Guile Reference +Manual}). + +@c FIXME: Update description when implemented. +@emph{Note}: The implementation of this R6RS API is currently far from +complete, notably due to the lack of support for Unicode I/O and strings +in Guile 1.8. + +@menu +* R6RS End-of-File:: The end-of-file object. +* R6RS Port Manipulation:: Manipulating R6RS ports. +* R6RS Binary I/O:: Binary input/output. +@end menu + +@node R6RS End-of-File +@subsection The End-of-File Object + +@cindex EOF +@cindex end-of-file + +R5RS' @code{eof-object?} procedure is provided by the @code{(rnrs io +ports)} module: + +@deffn {Scheme Procedure} eof-object? obj +@deffnx {C Function} scm_eof_object_p (obj) +Return true if @var{obj} is the end-of-file (EOF) object. +@end deffn + +In addition, the following procedure is provided: + +@deffn {Scheme Procedure} eof-object +@deffnx {C Function} scm_r6rs_eof_object () +Return the end-of-file (EOF) object. + +@lisp +(eof-object? (eof-object)) +@result{} #t +@end lisp +@end deffn + + +@node R6RS Port Manipulation +@subsection Port Manipulation + +The procedures listed below operate on any kind of R6RS I/O port. + +@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 +@var{port}. If @var{port} does not support this operation, an error +condition is raised. +@end deffn + +@deffn {Scheme Procedure} port-has-port-position? port +Return @code{#t} is @var{port} supports @code{port-position}. +@end deffn + +@deffn {Scheme Procedure} set-port-position! port offset +If @var{port} supports it (see below), set the position where the next +octet will be read from/written to @var{port} to @var{offset} (an +integer). If @var{port} does not support this operation, an error +condition is raised. +@end deffn + +@deffn {Scheme Procedure} port-has-set-port-position!? port +Return @code{#t} is @var{port} supports @code{set-port-position!}. +@end deffn + +@deffn {Scheme Procedure} call-with-port port proc +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 + + +@node R6RS Binary I/O +@subsection Binary Input/Output + +@cindex binary input + +R6RS binary input and output ports can be created with the procedures +described below. + +@deffn {Scheme Procedure} open-bytevector-input-port bv [transcoder] +@deffnx {C Function} scm_r6rs_open_bytevector_input_port (bv, transcoder) +Return an input port whose contents are drawn from bytevector @var{bv} +(@pxref{Bytevectors}). + +@c FIXME: Update description when implemented. +The @var{transcoder} argument is currently not supported. +@end deffn + +@deffn {Scheme Procedure} open-bytevector-output-port [transcoder] +@deffnx {C Function} scm_r6rs_open_bytevector_output_port (transcoder) +Return two values: a binary output port and a procedure. The latter +should be called with zero arguments to obtain a bytevector containing +the data accumulated by the port, as illustrated below. + +@lisp +(call-with-values + (lambda () + (open-bytevector-output-port)) + (lambda (port get-bytevector) + (display "hello" port) + (get-bytevector))) + +@result{} #vu8(104 101 108 108 111) +@end lisp + +@c FIXME: Update description when implemented. +The @var{transcoder} argument is currently not supported. +@end deffn + +@cindex custom binary input ports + +@deffn {Scheme Procedure} make-custom-binary-input-port id read! [get-position [set-position! [close]]] +@deffnx {C Function} scm_r6rs_make_custom_binary_input_port (id, read!, get-position, set-position!, close) +Return a new custom binary input port@footnote{This is similar in spirit +to Guile's @dfn{soft ports} (@pxref{Soft Ports,,, guile, The GNU Guile +Reference Manual}).} named @var{id} (a string) whose input is drained by +invoking @var{read!} and passing it a bytevector, an index where bytes +should be written, and the number of bytes to read. The @code{read!} +procedure must return an integer indicating the number of bytes read, or +@code{0} to indicate the end-of-file. + +Optionally, @var{get-position}, a thunk, will be called when +@var{port-position} is invoked on the custom binary port and should +return an integer indicating the position within the underlying data +stream; if @var{get-position} was not supplied, the returned port does +not support @var{port-position}. + +Likewise, if @var{set-position!} is given, it should be a one-argument +procedure. When @var{set-port-position!} is invoked on the custom +binary input port, @var{set-position!} is passed an integer indicating +the position of the next byte is to read. + +Finally, if @var{close} is supplied, it must be a thunk. It is invoked +when the custom binary input port is closed. + +Using a custom binary input port, the @code{open-bytevector-input-port} +could be implemented as follows: + +@lisp +(define (open-bytevector-input-port source) + (define position 0) + (define length (bytevector-length source)) + + (define (read! bv start count) + (let ((count (min count (- length position)))) + (bytevector-copy! source position + bv start count) + (set! position (+ position count)) + count)) + + (define (get-position) position) + + (define (set-position! new-position) + (set! position new-position)) + + (make-custom-binary-input-port "the port" read! + get-position + set-position!)) + +(read (open-bytevector-input-port (string->utf8 "hello"))) +@result{} hello +@end lisp +@end deffn + + FIXME: Finish. @c LocalWords: Bytevectors bytevector bytevectors endianness endian accessors -- 2.11.4.GIT