begun thinkering how to refactor (cleanup) CSV parser

1 files changed, 28 insertions, 22 deletions

diff --git a/include/qntan/Qntan.h b/include/qntan/Qntan.h
index fd7783d..d5ada3a 100644
--- a/include/qntan/Qntan.h
+++ b/include/qntan/Qntan.h
@@ -1003,38 +1003,44 @@ struct Qntan_Networker {
 
 struct Qntan_CsvDec {
 	/**/
+	void (*reset)( struct Qntan_CsvDec** );
+	/* Throws away parsing state and prepares to begin parsing on a new input
+	 * document.
+	 */
 	void (*write)( struct Qntan_CsvDec**,
 		void const*buf, int buf_len, int flgs,
 		void(*onDone)(int ret,Qntan_Cls), Qntan_Cls );
-	/* @param flgs
-	 *      0x4 set means this is last chunk.
-	 *      Any other bit set is UNDEFINED BEHAVIOR!
+	/* Write more data to the csv parser. Another `write` call MUST ONLY
+	 * happen after `onDone` of the previous call marks completion of
+	 * the previous action.
+	 * @param flgs
+	 *      0x4 set means this is last chunk. All other bits MUST be set
+	 *      to zero.
 	 */
 };
 
 
 struct Qntan_CsvDec_Mentor {
-	/**/
-	void (*onCsvDocEnd)( Qntan_Cls );
-	/* TODO doc
-	 */
-	void (*onEntityBeg)( Qntan_Cls );
-	/* TODO doc
+	/* WARN: Passed buffers only remain valid upon return.
 	 */
-	void (*onEntityEnd)( Qntan_Cls );
-	/* TODO doc
+	void (*onChunk)( struct Qntan_CsvDec_Mentor**,
+		int64_t row, int64_t col, char const*buf, int buf_len, unsigned flg,
+		void(*onDone)(Qntan_Cls), Qntan_Cls );
+	/* Called repeatedly with chunks of data. `row` is the ONE-based row
+	 * number (so 1st row has nr 1). `col` is the ONE-based column number (so
+	 * 1st colum is nr 1). `flg & 4` indicates this is the last buffer
+	 * for this cell.
 	 */
-	void (*onAttrBeg)( Qntan_Cls );
-	/* TODO doc
-	 */
-	void (*onAttrEnd)( Qntan_Cls );
-	/* TODO doc
-	 */
-	void (*onChunkNaked)( char const*buf, int buf_len, Qntan_Cls );
-	/* TODO doc
-	 */
-	void (*onChunkQuoted)( char const*buf, int buf_len, Qntan_Cls );
-	/* TODO doc
+// TODO 	void (*onChunkRaw)( struct Qntan_CsvDec_Mentor**,
+// TODO 		int64_t row, int64_t col, char const*buf, int buf_len, unsigned flg,
+// TODO 		void(*onDone)(Qntan_Cls), Qntan_Cls );
+// TODO 	/* Same as `onChunk`. BUT: Quotations will not be removed, but will
+// TODO 	 * be as found in the original document.
+// TODO 	 */
+	void (*onEnd)( struct Qntan_CsvDec_Mentor**, int err, char*emsg );
+	/* Called ONCE at end. with err `0` on success. `err` is a negated
+	 * error number on erorr. In this case, `emsg` MAY contains error
+	 * details in case of error.
 	 */
 };