*.pyx: Add some rather laconic docstrings.

[mLib-python] / codec.pyx.in

### -*-pyrex-*-
###
### Generic encoder/decoder
###
### (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.

cdef extern from 'mLib/%PREFIX%.h':
  ctypedef struct %PREFIX%_ctx:
    char *indent
    int maxline
  void _%PREFIX%_init "%PREFIX%_init"(%PREFIX%_ctx *b)
  void _%PREFIX%_encode "%PREFIX%_encode"(%PREFIX%_ctx *b,
                                          void *p, size_t sz, dstr *d)
  void _%PREFIX%_decode"%PREFIX%_decode"(%PREFIX%_ctx *b,
                                         void *p, size_t sz, dstr *d)

cdef class %CLASS%Encode:
  """
  %CLASS%([indent = '\\n'], [maxline = 72])

  Obsolete %CLASS% encoder.
  """
  cdef %PREFIX%_ctx ctx
  def __cinit__(me, *hunoz, **hukairz):
    _%PREFIX%_init(&me.ctx)
    me.ctx.indent = NULL
  def __init__(me, indent = '\n', maxline = 72):
    if me.ctx.indent:
      xfree(<void *>me.ctx.indent)
    me.ctx.indent = xstrdup(indent)
    me.ctx.maxline = maxline
  def __dealloc__(me):
    if me.ctx.indent:
      xfree(<void *>me.ctx.indent)
  property indent:
    """E.indent -> INT: indent level for new lines"""
    def __get__(me):
      return me.ctx.indent
    def __set__(me, indent):
      if me.ctx.indent:
        xfree(<void *>me.ctx.indent)
      me.ctx.indent = xstrdup(indent)
  property maxline:
    """E.maxline -> INT: maximum length of line, or 0 to prevent splitting"""
    def __get__(me):
      return me.ctx.maxline
    def __set__(me, maxline):
      me.ctx.maxline = maxline
  def encode(me, text):
    """E.encode(IN) -> OUT: continue encoding"""
    cdef void *p
    cdef Py_ssize_t len
    cdef dstr d
    DCREATE(&d)
    try:
      PyObject_AsReadBuffer(text, <cvp *>&p, &len)
      _%PREFIX%_encode(&me.ctx, p, len, &d)
      rc = PyString_FromStringAndSize(d.buf, d.len)
    finally:
      dstr_destroy(&d)
    return rc
  def done(me):
    """E.done() -> OUT: finish encoding, returning final output"""
    cdef dstr d
    DCREATE(&d)
    try:
      _%PREFIX%_encode(&me.ctx, NULL, 0, &d)
      rc = PyString_FromStringAndSize(d.buf, d.len)
    finally:
      dstr_destroy(&d)
    return rc

def %PREFIX%_encode(text, *arg, **kw):
  """%PREFIX%_encode(IN, [ARGS...]) -> OUT: %CLASS%-encode the string IN"""
  e = %CLASS%Encode(*arg, **kw)
  return e.encode(text) + e.done()

cdef class %CLASS%Decode:
  """
  %CLASS%()

  Obsolete %CLASS% decoder.
  """
  cdef %PREFIX%_ctx ctx
  def __cinit__(me, *hunoz, **hukairz):
    _%PREFIX%_init(&me.ctx)
    me.ctx.indent = NULL
  def decode(me, text):
    """D.encode(IN) -> OUT: continue decoding"""
    cdef void *p
    cdef Py_ssize_t len
    cdef dstr d
    DCREATE(&d)
    try:
      PyObject_AsReadBuffer(text, <cvp *>&p, &len)
      _%PREFIX%_decode(&me.ctx, p, len, &d)
      rc = PyString_FromStringAndSize(d.buf, d.len)
    finally:
      dstr_destroy(&d)
    return rc
  def done(me):
    """D.done() -> OUT: finish decoding, returning final output"""
    cdef dstr d
    DCREATE(&d)
    try:
      _%PREFIX%_decode(&me.ctx, NULL, 0, &d)
      rc = PyString_FromStringAndSize(d.buf, d.len)
    finally:
      dstr_destroy(&d)
    return rc

def %PREFIX%_decode(text, *arg, **kw):
  """%PREFIX%_decode(IN) -> OUT: %CLASS%-decode the string IN"""
  d = %CLASS%Decode(*arg, **kw)
  return d.decode(text) + d.done()

###----- That's all, folks --------------------------------------------------