[Pspp-cvs] pspp/src/data casereader.h [simpler-proc]

[Ben Pfaff]

CVSROOT:        /cvsroot/pspp
Module name:    pspp
Branch:         simpler-proc
Changes by:     Ben Pfaff <blp> 07/05/07 05:06:05

Modified files:
        src/data       : casereader.h 

Log message:
        Add comment.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/pspp/src/data/casereader.h?cvsroot=pspp&only_with_tag=simpler-proc&r1=1.1.2.4&r2=1.1.2.5

Patches:
Index: casereader.h
===================================================================
RCS file: /cvsroot/pspp/pspp/src/data/Attic/casereader.h,v
retrieving revision 1.1.2.4
retrieving revision 1.1.2.5
diff -u -b -r1.1.2.4 -r1.1.2.5
--- casereader.h        6 May 2007 22:48:27 -0000       1.1.2.4
+++ casereader.h        7 May 2007 05:06:05 -0000       1.1.2.5
@@ -16,6 +16,40 @@
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
    02110-1301, USA. */
 
+/* Casereader client interface.
+
+   A casereader abstracts interfaces through which cases may be
+   read.  A casereader may be a front-end for a system file, a
+   portable file, the active file in a data set, or anything else
+   on which a casereader interface has been overlaid.  Casereader
+   layering, in which a casereader acts as a filter or translator
+   on top of another casereader, is also supported.
+
+   There is no central interface for obtaining casereaders: a
+   casereader for reading a system file is obtained from the
+   system file reading module, and so on.  Once a casereader has
+   been obtained, by whatever means, the interface to it is
+   uniform.  The most important functions for casereader usage
+   are:
+
+     - casereader_read: Reads a case from the casereader.  The
+       case is consumed and cannot be read again.  The caller is
+       responsible for destroying the case.
+
+     - casereader_clone: Makes a copy of a casereader.  May be
+       used to read one or a set of cases from a casereader
+       repeatedly.
+
+     - casereader_destroy: Destroys a casereader.
+
+   Casereaders can encounter error conditions, such as I/O
+   errors, as they read cases.  Error conditions prevent any more
+   cases from being read from the casereader.  Error conditions
+   are reported by casereader_error.  Error condition may be
+   propagated to or from a casereader with taint_propagate using
+   the casereader's taint object, which may be obtained with
+   casereader_get_taint. */
+
 #ifndef DATA_CASEREADER_H
 #define DATA_CASEREADER_H 1