From 44f460a7d2e37ef61bd619c00dc83b84bbb08181 Mon Sep 17 00:00:00 2001 From: Marius Gerbershagen Date: Sat, 2 Mar 2019 17:32:52 +0100 Subject: [PATCH] doc: document ANSI stream extensions --- src/doc/manual/standards/streams.txi | 194 +++++++++++++++++++++++++-- 1 file changed, 182 insertions(+), 12 deletions(-) diff --git a/src/doc/manual/standards/streams.txi b/src/doc/manual/standards/streams.txi index 8620c4e3e..a55b40ab6 100644 --- a/src/doc/manual/standards/streams.txi +++ b/src/doc/manual/standards/streams.txi @@ -107,21 +107,62 @@ and the table of known symbols is shown below. Note how some symbols (@code{:cr} @node Streams - Dictionary @subsection Dictionary -@lspindex open -@lspindex si:set-buffering-mode -@defun open filename &key (direction :input) (element-type character) if-exists if-does-not-exist (external-format :default) (cstream t) -Open a file stream -@subsubheading Synopsis -@table @var -@item cstream -A generalized boolean; If true, internally use a C @code{FILE*} stream, else a POSIX file descriptor -@end table +@subsubsection Sequence Streams + +@lspindex ext:sequence-stream +@deftp {System Class} ext:sequence-stream + +@subsubheading Class Precedence List +@code{ext:sequence-stream, stream, t} + @subsubheading Description -All keyword arguments except @var{cstream} behave as specified by the ANSI standard @bibcite{ANSI}. +Sequence streams work similar to string streams for vectors. The +supplied vectors that the streams read from or write to must have a +byte sized element type, i.e. @code{(signed-byte 8)}, +@code{(unsigned-byte 8)} or @code{base-char}. + +The semantics depend on the vector element type and the external +format of the stream. If no external format is supplied and the +element type is an integer type, the stream is a binary stream and +accepts only integers of the same type as the element type of the +vector. Otherwise, the stream accepts both characters and integers and +converts them using the given external format. If the element type is +@code{base-char}, the elements of the vectors are treated as bytes. +This means that writing a character may use multiple elements of the +vector, whose @code{char-code}s will be equal to the values of the +bytes comprising the character in the given external format. +@end deftp + +@lspindex ext:make-sequence-input-stream +@defun ext:make-sequence-input-stream vector &key (start 0) (end nil) (external-format nil) +Create a sequence input stream with the subsequence bounded by +@var{start} and @var{end} of the given vector. +@end defun +@lspindex ext:make-sequence-output-stream +@defun ext:make-sequence-output-stream vector &key (external-format nil) +Create a sequence output stream. @end defun -@defun si:set-buffering-mode stream mode +@exindex Using sequence streams +Example: + +Using sequence streams to convert to a UTF8 encoded base string +@lisp +CL-USER> (defvar *output* (make-array 20 :element-type 'base-char :adjustable t :fill-pointer 0)) +*OUTPUT* +CL-USER> (defvar *stream* (ext:make-sequence-output-stream *output* :external-format :utf-8)) +*STREAM* +CL-USER> (write-string "Spätzle mit Soß'" *stream*) +"Spätzle mit Soß'" +CL-USER> *output* +"Spätzle mit SoÃ\237'" +@end lisp + +@subsubsection File Stream Extensions + +@lspindex ext:set-buffering-mode +@defun ext:set-buffering-mode stream mode Control the buffering mode of a stream @subsubheading Synopsis @table @var @@ -129,11 +170,140 @@ Control the buffering mode of a stream an ANSI stream @item mode one of @code{nil}, @code{:none}, @code{:line}, @code{:line-buffered}, @code{:full} or @code{:full-buffered} +@item returns +The supplied stream @end table @subsubheading Description -If @var{mode} is @code{nil} or @code{:none}, @var{stream} will not be buffered, if it is @code{:line} or @code{:line-buffered} resp. @code{:full} or @code{:full-buffered}, @var{stream} will be line resp. fully buffered. Streams created with the @code{:cstream} argument to @code{open} set to @code{nil} will never be buffered. +If @var{mode} is @code{nil} or @code{:none}, @var{stream} will not be +buffered, if it is @code{:line} or @code{:line-buffered} resp. +@code{:full} or @code{:fully-buffered}, @var{stream} will be line resp. +fully buffered. If the stream does not support buffering, nothing will +happen. @end defun +@lspindex ext:file-stream-fd +@defun ext:file-stream-fd file-stream +Return the POSIX file descriptor of @var{file-stream} as an integer +@end defun + +@subsubsection External Format Extensions + +@lspindex ext:all-encodings +@defun ext:all-encodings +Return a list of all supported external formats +@end defun + +@lspindex ext:character-coding-error +@deftp Condition ext:character-coding-error + +Character coding error + +@subsubheading Class Precedence List +@code{ext:character-coding-error, error, serious-condition, condition, t} + +@subsubheading Methods +@lspindex ext:character-coding-error-external-format +@defun ext:character-coding-error-external-format condition +@table @var +@item returns +The external format of @var{condition} +@end table +@end defun + +@subsubheading Description +Superclass of @code{ext:character-encoding-error} and @code{ext:character-decoding-error}. +@end deftp + +@lspindex ext:character-encoding-error +@deftp Condition ext:character-encoding-error + +Character encoding error + +@subsubheading Class Precedence List +@code{ext:character-encoding-error, ext:character-coding-error, error, serious-condition, condition, t} + +@subsubheading Methods +@lspindex ext:character-encoding-error-code +@defun ext:character-encoding-error-code condition +@table @var +@item returns +The character code of the character, which can't be encoded +@end table +@end defun + +@subsubheading Description +Condition for characters, which can't be encoded with some external +format. +@end deftp + + +@lspindex ext:character-decoding-error +@deftp Condition ext:character-decoding-error + +Character decoding error + +@subsubheading Class Precedence List +@code{ext:character-decoding-error, ext:character-coding-error, error, serious-condition, condition, t} + +@subsubheading Methods +@lspindex ext:character-decoding-error-octects +@defun ext:character-decoding-error-octects condition +@table @var +@item returns +A list of integers with the values of the @code{unsigned char}'s which +can't be decoded. +@end table +@end defun + +@subsubheading Description +Condition for characters, which can't be decoded with some external +format. +@end deftp + +@lspindex ext:stream-encoding-error +@deftp Condition ext:stream-encoding-error + +Stream encoding error + +@subsubheading Class Precedence List +@code{ext:stream-encoding-error, ext:character-encoding-error, ext:character-coding-error, stream-error, error, serious-condition, condition, t} + +@subsubheading Description +This condition is signaled when trying to write a character to a +stream, which can't be encoded with the streams external format. +@end deftp + + +@lspindex ext:stream-decoding-error +@deftp Condition ext:stream-decoding-error + +Stream decoding error + +@subsubheading Class Precedence List +@code{ext:stream-decoding-error, ext:character-decoding-error, ext:character-coding-error, stream-error, error, serious-condition, condition, t} + +@subsubheading Description +This condition is signaled when trying to read a character from a + stream, which can't be decoded with the streams external format. +@end deftp + +@lspindex ext:encoding-error +@defun ext:encoding-error stream external-format code +Signal a @code{ext:stream-encoding-error} with the given +@var{external-format} and @var{code}. Make a restart available so +that the error can be ignored or the character can be replaced with a +different one. +@end defun + +@lspindex ext:decoding-error +@defun ext:decoding-error stream external-format octects +Signal a @code{ext:stream-decoding-error} with the given +@var{external-format} and @var{octets}. Make a restart available so +that the error can be ignored or the octets can be replaced with a +character. +@end defun + + @node Streams - C Reference @subsection C Reference