new argument :buffering to make-source

doc/html.xsl

@@ -57,8 +57,8 @@
 	<li>
           <a href="klacks.html">Klacks parser</a>
           <ul class="sub">
-            <li><a href="klacks.html#parsing">Parsing incrementally</a></li>
-            <li><a href="klacks.html#sax">Bridging Klacks and SAX</a></li>
+            <li><a href="klacks.html#sources">Parsing incrementally</a></li>
+            <li><a href="klacks.html#klacksax">Bridging Klacks and SAX</a></li>
           </ul>
         </li>
 	<li>

doc/klacks.xml

@@ -45,7 +45,8 @@ NIL
 * <b>(klacks:consume *source*)</b>
 NIL</pre>
 
-    <h3>Klacks sources</h3>
+    <a name="sources"/>
+    <h3>Parsing incrementally using sources</h3>
     <p>
       To parse using Klacks, create an XML <tt>source</tt> first.
     </p>
@@ -96,8 +97,22 @@ NIL</pre>
       closed otherwise.
     </p>
     <p>
-      <b>Keyword arguments</b> have the same meaning as with the SAX parser,
-      please refer to the documentation of <a
+      <b>Buffering:</b> By default, the Klacks parser performs buffering
+      of octets being read from the stream as an optimization.  This can
+      result in unwanted blocking if the stream is a socket and the
+      parser tries to read more data than required to parse the current
+      event.  Use <tt>:buffering nil</tt> to disable this optimization.
+    </p>
+    <ul>
+      <li>
+        <tt>buffering</tt> -- Boolean, defaults to <tt>t</tt>.  If
+        enabled, read data several kilobytes at time.  If disabled,
+        read only single bytes at a time.
+      </li>
+    </ul>
+    <p>
+      The following <b>keyword arguments</b> have the same meaning as
+      with the SAX parser, please refer to the documentation of <a
       href="sax.html#parser">parse-file</a> for more information:
     </p>
     <ul>
@@ -216,6 +231,7 @@ NIL</pre>
       exiting <tt>body</tt>, whether normally or abnormally.
     </p>
 
+    <a name="klacksax"/>
     <h3>Bridging Klacks and SAX</h3>
     <p>
       <div class="def">Function KLACKS:SERIALIZE-SOURCE (source handler)</div>

klacks/klacks-impl.lisp

@@ -101,10 +101,12 @@
 (defun make-source
     (input &rest args
      &key validate dtd root entity-resolver disallow-internal-subset
-	  pathname)
+	  (buffering t) pathname)
   (declare (ignore validate dtd root entity-resolver disallow-internal-subset))
   (etypecase input
     (xstream
+      (when (and (not buffering) (< 1 (runes::xstream-speed input)))
+	(warn "make-source called with !buffering, but xstream is buffering"))
       (let ((*ctx* nil))
 	(let ((zstream (make-zstream :input-stack (list input))))
 	  (peek-rune input)
@@ -113,10 +115,10 @@
 		   zstream
 		   (loop
 		       for (name value) on args by #'cddr
-		       unless (eq name :pathname)
+		       unless (member name '(:pathname :buffering))
 		       append (list name value)))))))
     (stream
-      (let ((xstream (make-xstream input)))
+      (let ((xstream (make-xstream input :speed (if buffering 8192 1))))
 	(setf (xstream-name xstream)
 	      (make-stream-name
 	       :entity-name "main document"
@@ -126,7 +128,8 @@
 	(apply #'make-source xstream args)))
     (pathname
       (let* ((xstream
-	      (make-xstream (open input :element-type '(unsigned-byte 8)))))
+	      (make-xstream (open input :element-type '(unsigned-byte 8))
+			    :speed (if buffering 8192 1))))
 	(setf (xstream-name xstream)
 	      (make-stream-name
 	       :entity-name "main document"