X-Git-Url: https://git.distorted.org.uk/~mdw/mLib-python/blobdiff_plain/5b1830f325c55c70d65fd020f08dd958493e528d..HEAD:/lbuf.pyx

diff --git a/lbuf.pyx b/lbuf.pyx
index b80b5cc..c5f2688 100644
--- a/lbuf.pyx
+++ b/lbuf.pyx
@@ -27,6 +27,11 @@ LBUF_CRLF = _LBUF_CRLF
 LBUF_STRICTCRLF = _LBUF_STRICTCRLF
 
 cdef class LineBuffer:
+  """
+  LineBuffer([lineproc = None], [eofproc = None])
+
+  Split an incoming stream into lines.
+  """
   cdef lbuf b
   cdef _line
   cdef _eof
@@ -37,9 +42,11 @@ cdef class LineBuffer:
   def __dealloc__(me):
     lbuf_destroy(&me.b)
   property activep:
+    """LB.activep -> BOOL: is the buffer still active?"""
     def __get__(me):
       return _tobool(me.b.f & LBUF_ENABLE)
   property delim:
+    """LB.delim -> CHAR | LBUF_...: line-end delimiter"""
     def __get__(me):
       if me.b.delim == _LBUF_CRLF or me.b.delim == _LBUF_STRICTCRLF:
         return me.b.delim
@@ -51,6 +58,7 @@ cdef class LineBuffer:
       else:
         me.b.delim = ord(d)
   property size:
+    """LB.size -> INT: buffer size limit"""
     def __get__(me):
       return me.b.sz
     def __set__(me, sz):
@@ -58,6 +66,7 @@ cdef class LineBuffer:
         raise TypeError, 'size must be positive'
       lbuf_setsize(&me.b, sz)
   property lineproc:
+    """LB.lineproc -> FUNC: call FUNC(LINE) on each line"""
     def __get__(me):
       return me._line
     def __set__(me, proc):
@@ -65,6 +74,7 @@ cdef class LineBuffer:
     def __del__(me):
       me._line = None
   property eofproc:
+    """LB.eofproc -> FUNC: call FUNC() at end-of-file"""
     def __get__(me):
       return me._eof
     def __set__(me, proc):
@@ -72,28 +82,33 @@ cdef class LineBuffer:
     def __del__(me):
       me._eof = None
   def enable(me):
+    """LB.enable(): enable the buffer, allowing lines to be emitted"""
     if me.b.f & LBUF_ENABLE:
       raise ValueError, 'already enabled'
     me.b.f = me.b.f | LBUF_ENABLE
     me.enabled()
     return me
   def disable(me):
+    """LB.disable(): disable the buffer, suspending line emission"""
     if not (me.b.f & LBUF_ENABLE):
       raise ValueError, 'already disabled'
     me.b.f = me.b.f & ~LBUF_ENABLE
     me.disabled()
     return me
   def close(me):
+    """LB.close(): report the end of the input stream"""
     if not (me.b.f & LBUF_ENABLE):
       raise ValueError, 'buffer disabled'
     lbuf_close(&me.b)
     return me
   property free:
+    """LB.free -> INT: amount of space remaining in buffer"""
     def __get__(me):
       cdef char *p
       return lbuf_free(&me.b, &p)
   def flush(me, str):
-    cdef int len
+    """LB.flush(STR) -> insert STR into the buffer and emit lines"""
+    cdef Py_ssize_t len
     cdef char *p
     cdef char *q
     cdef size_t n
@@ -110,12 +125,16 @@ cdef class LineBuffer:
       lbuf_flush(&me.b, q, n)
     return PyString_FromStringAndSize(p, len)
   def enabled(me):
+    """LB.enabled(): called when buffer is enabled"""
     pass
   def disabled(me):
+    """LB.disabled(): called when buffer is disabled"""
     pass
   def line(me, line):
+    """LB.line(LINE): called for each completed line"""
     return _maybecall(me._line, (line,))
   def eof(me):
+    """LB.eof(): called at end-of-file"""
     return _maybecall(me._eof, ())
 
 cdef void _lbfunc(char *s, size_t n, void *arg):