X-Git-Url: https://git.distorted.org.uk/~mdw/mLib-python/blobdiff_plain/579d01693c86259110fe7a2c2a6f005f1bdbad5b..HEAD:/selbuf.pyx

diff --git a/selbuf.pyx b/selbuf.pyx
index 4a5a288..53964c7 100644
--- a/selbuf.pyx
+++ b/selbuf.pyx
@@ -1,35 +1,38 @@
-# -*-pyrex-*-
-#
-# $Id$
-#
-# Selecting line-buffers
-#
-# (c) 2005 Straylight/Edgeware
-#
+### -*-pyrex-*-
+###
+### Selecting line-buffers
+###
+### (c) 2005 Straylight/Edgeware
+###
 
-#----- Licensing notice -----------------------------------------------------
-#
-# This file is part of the Python interface to mLib.
-#
-# mLib/Python is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation; either version 2 of the License, or
-# (at your option) any later version.
-# 
-# mLib/Python is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-# 
-# You should have received a copy of the GNU General Public License
-# along with mLib/Python; if not, write to the Free Software Foundation,
-# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+###----- Licensing notice ---------------------------------------------------
+###
+### This file is part of the Python interface to mLib.
+###
+### mLib/Python is free software; you can redistribute it and/or modify
+### it under the terms of the GNU General Public License as published by
+### the Free Software Foundation; either version 2 of the License, or
+### (at your option) any later version.
+###
+### mLib/Python is distributed in the hope that it will be useful,
+### but WITHOUT ANY WARRANTY; without even the implied warranty of
+### MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+### GNU General Public License for more details.
+###
+### You should have received a copy of the GNU General Public License
+### along with mLib/Python; if not, write to the Free Software Foundation,
+### Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 
 cdef class SelLineBuffer:
+  """
+  SelLineBuffer(FILE, [lineproc = None], [eofproc = None])
+
+  Split an asynchronous stream into lines.
+  """
   cdef selbuf b
   cdef _line
   cdef _eof
-  def __new__(me, fd, lineproc = None, eofproc = None, *hunoz, **hukairz):
+  def __cinit__(me, fd, lineproc = None, eofproc = None, *hunoz, **hukairz):
     selbuf_init(&me.b, &_sel, _getfd(fd), _selbfunc, <void *>me)
     selbuf_disable(&me.b)
     me._line = _checkcallable(lineproc, 'line proc')
@@ -37,12 +40,15 @@ cdef class SelLineBuffer:
   def __dealloc__(me):
     selbuf_destroy(&me.b)
   property activep:
+    """SLB.activep -> BOOL: is the buffer still active?"""
     def __get__(me):
       return _tobool(me.b.b.f & LBUF_ENABLE)
   property fd:
+    """SLB.fd -> INT: the file descriptor"""
     def __get__(me):
       return me.b.reader.fd
   property delim:
+    """SLB.delim -> CHAR | LBUF_...: line-end delimiter"""
     def __get__(me):
       if me.b.b.delim == _LBUF_CRLF or me.b.b.delim == _LBUF_STRICTCRLF:
         return me.b.b.delim
@@ -54,6 +60,7 @@ cdef class SelLineBuffer:
       else:
         me.b.b.delim = ord(d)
   property size:
+    """SLB.size -> INT: buffer size limit"""
     def __get__(me):
       return me.b.b.sz
     def __set__(me, sz):
@@ -61,6 +68,7 @@ cdef class SelLineBuffer:
         raise TypeError, 'size must be positive'
       selbuf_setsize(&me.b, sz)
   property lineproc:
+    """SLB.lineproc -> FUNC: call FUNC(LINE) on each line"""
     def __get__(me):
       return me._line
     def __set__(me, proc):
@@ -68,6 +76,7 @@ cdef class SelLineBuffer:
     def __del__(me):
       me._line = None
   property eofproc:
+    """SLB.eofproc -> FUNC: call FUNC() at end-of-file"""
     def __get__(me):
       return me._eof
     def __set__(me, proc):
@@ -75,24 +84,30 @@ cdef class SelLineBuffer:
     def __del__(me):
       me._eof = None
   def enable(me):
+    """SLB.enable(): enable the buffer, allowing lines to be emitted"""
     if me.b.b.f & LBUF_ENABLE:
       raise ValueError, 'already enabled'
     selbuf_enable(&me.b)
     me.enabled()
     return me
   def disable(me):
+    """SLB.disable(): disable the buffer, suspending line emission"""
     if not (me.b.b.f & LBUF_ENABLE):
       raise ValueError, 'already disabled'
     selbuf_disable(&me.b)
     me.disabled()
     return me
   def enabled(me):
+    """SLB.enabled(): called when buffer is enabled"""
     pass
   def disabled(me):
+    """SLB.disabled(): called when buffer is disabled"""
     pass
   def line(me, line):
+    """SLB.line(LINE): called for each completed line"""
     return _maybecall(me._line, (line,))
   def eof(me):
+    """SLB.eof(): called at end-of-file"""
     return _maybecall(me._eof, ())
 
 cdef void _selbfunc(char *s, size_t n, void *arg):
@@ -103,4 +118,4 @@ cdef void _selbfunc(char *s, size_t n, void *arg):
   else:
     sb.line(PyString_FromStringAndSize(s, n))
 
-#----- That's all, folks ----------------------------------------------------
+###----- That's all, folks --------------------------------------------------