[flexi-streams-cvs] r42 - branches/edi

[eweitz at common-lisp.net]

Author: eweitz
Date: Tue May 20 21:28:34 2008
New Revision: 42

Modified:
   branches/edi/output.lisp
Log:
More documentation


Modified: branches/edi/output.lisp
==============================================================================
--- branches/edi/output.lisp	(original)
+++ branches/edi/output.lisp	Tue May 20 21:28:34 2008
@@ -1,5 +1,5 @@
 ;;; -*- Mode: LISP; Syntax: COMMON-LISP; Package: FLEXI-STREAMS; Base: 10 -*-
-;;; $Header: /usr/local/cvsrep/flexi-streams/output.lisp,v 1.59 2008/05/21 01:17:45 edi Exp $
+;;; $Header: /usr/local/cvsrep/flexi-streams/output.lisp,v 1.60 2008/05/21 01:26:43 edi Exp $
 
 ;;; Copyright (c) 2005-2008, Dr. Edmund Weitz.  All rights reserved.
 
@@ -130,7 +130,13 @@
   (stream-write-char stream #\Newline))
 
 (defmethod stream-write-sequence ((stream flexi-output-stream) sequence start end &key)
-;  (declare #.*standard-optimize-settings*)
+  "An optimized version which uses a buffer underneath.  The function
+can accepts characters as well as octets and it decides what to do
+based on the element type of the sequence \(if possible) or on the
+individual elements, i.e. you can mix characters and octets in
+SEQUENCE if you want.  Whether that really works might also depend on
+your Lisp, some of the implementations are more picky than others."
+  (declare #.*standard-optimize-settings*)
   (declare (fixnum start end))
   (with-accessors ((column flexi-stream-column)
                    (external-format flexi-stream-external-format)
@@ -151,23 +157,32 @@
                (boolean octet-seen-p)
                (type (array octet *) buffer))
       (labels ((flush-buffer ()
+                 "Sends all octets in BUFFER to the underlying stream."
                  (write-sequence buffer stream :end buffer-pos)
                  (setq buffer-pos 0))
                (write-octet (octet)
+                 "Adds one octet to the buffer and flush it if necessary."
                  (declare (octet octet))
                  (when (>= buffer-pos buffer-size)
                    (flush-buffer))
                  (setf (aref buffer buffer-pos) octet)
                  (incf buffer-pos))
                (write-character (char)
+                 "Adds the octets representing the character CHAR to the buffer."
                  (char-to-octets external-format char #'write-octet))
                (write-object (object)
+                 "Dispatches to WRITE-OCTET or WRITE-CHARACTER
+depending on the type of OBJECT."
                  (etypecase object
                    (octet (setq octet-seen-p t)
                           (write-octet object))
                    (character (write-character object)))))
         (declare (dynamic-extent (function write-octet)))
         (macrolet ((iterate (octets-p output-form)
+                     "An unhygienic macro to implement the actual
+iteration through SEQUENCE.  OUTPUT-FORM is the form to retrieve one
+sequence element and put its octet representation into the buffer.
+OCTETS-P is true if we know in advance that we will send octets."
                      `(progn
                         ,@(if octets-p '((setq octet-seen-p t)))
                         (loop for index of-type fixnum from start below end
@@ -184,6 +199,7 @@
                       (iterate t (write-octet (aref sequence index))))
                      (t (iterate nil (write-object (aref sequence index)))))))
             (list (iterate nil (write-object (nth index sequence)))))
+          ;; update the column slot, setting if to NIL if we sent octets
           (setq column
                 (cond (octet-seen-p nil)
                       (t (let ((last-newline-pos (position #\Newline sequence