erster Versuch einer Dokumentation

1 files changed, 197 insertions, 0 deletions

diff --git a/csv.md b/csv.md
new file mode 100644
index 0000000..63b8d8a
--- /dev/null
+++ b/csv.md
@@ -0,0 +1,197 @@
+# csv - CSV-Dateien parsen
+
+- [x] korrekt
+- [x] einfach
+- [x] intuitiv
+- [x] schnell
+- [x] klein
+- [x] erweiterbar
+- [x] robust
+- [x] einfachst mögliche Lizenz
+
+Kurz: suckless!
+
+## Schnellstart für Ungeduldige
+
+1\. Füge die beiden Dateien [csv.c](csv.c) und [csv.h](csv.h) Deinem C/C++ Projekt hinzu.
+
+2\. Inkludiere die Headerdatei `csv.h`.
+
+~~~
+#include "csv.h"
+~~~
+
+3\. Erstelle und initialisiere ein CSV-Objekt.
+
+~~~
+csv_t csv = { 0 };
+~~~
+
+4\. Verarbeite die CSV-Datei
+
+~~~
+for ( int nf; (nf = csv_read(&csv, in)) != EOF; ) {  /* eine Zeile aus `in` lesen */
+        for ( int i = 0; i < nf; i++ ) {                 /* `nf` beinhaltet die Feldanzahl */
+                const char *s = csv_field(&csv, i);          /* jedes Feld der Zeile ansprechen */
+                /* ... */
+        }
+}
+~~~
+
+Es sind nur zwei Funktionen notwendig, um die Daten des FILE-Streams `in` vollständig zu verarbeiten:
+`csv_read()` liest eine Zeile aus dem Parameter `in` und liefert die Anzahl der erfolgreich geparsten Felder oder **`EOF`** bei Dateiende.
+`csv_field()` liefert einen (read only) `const char`-Zeiger für das i-te Feld.
+
+Der Speicher für das CSV-Objekt wird automatisch von `csv_read()` beim ersten Aufruf alloziert und wieder freigeben wenn der Stream `in` vollständig gelesen wurde.
+
+## Motivation
+
+Die meisten anderen CSV-Bibliotheken passen nicht:
+
+- falsche Verarbeitung bei eingeklammerten Feldern:  
+  C++: getline() -> stringstream -> getline();  
+  C: fgets() -> strtok()
+- fehlerhafte Verarbeitung von "problematischen" CSV-Dateien (Linebreaks innerhalb einer Zelle)
+- unvorteilhafte Lizenz (GPL)
+- umständliche API (Callbacks zum Verarbeiten der Inhalte, seltsames Handling am Dateiende)
+- globale Variablen, die den Einsatz in Multi-Threadumgebungen unmöglich machen
+- C++ wenn ich C brauche
+- Java/Python/Rust/Ruby/${YourLanguageHere} wenn ich C brauche
+- Langsam, Aufgebläht
+- schlecht oder gar nicht anpassbar
+
+=> Selber schreiben!
+
+## Tutorial
+
+to be written
+
+## API
+
+### Typen
+
+**Fehlercodes** für die Callbackhandler:
+
+~~~
+typedef enum {
+        CSV_ERR_OK            =  0,
+        CSV_ERR_OUT_OF_MEMORY = -1,
+        CSV_ERR_OUT_OF_RANGE  = -2,
+        CSV_ERR_IO_READ       = -3,
+        CSV_ERR_IO_WRITE      = -4
+} csv_err_t;
+~~~
+
+**Optionen** für das Parsen eines CSV-Streams:
+
+~~~
+typedef struct {
+        int field_delimiter;
+        int field_separator;
+
+        void (*cb_error)(csv_err_t, void *);
+        void *cb_error_arg;
+
+        void *(*cb_allocate)(size_t, size_t, void *);
+        void *(*cb_reallocate)(void *, size_t, size_t, void *);
+        void (*cb_free)(void *, size_t, size_t, void *);
+        void *cb_memory_arg;
+} csv_options_t;
+
+extern const csv_options_t csv_default_options;
+~~~
+
+**Contextobjekt** zur Aufnahme der aktuell gelesenen Zeile:
+
+~~~
+typedef struct {
+        csv_options_t *csv_options;
+        /* additional internal fields */
+} csv_t;
+
+~~~
+
+### Funktionen
+
+**Initialisieren**
+
+~~~
+void csv_init(csv_t *csv);
+void csv_init_opt(csv_t *csv, const csv_options_t * const csv_options);
+~~~
+
+**Manuelles Freigeben**
+
+~~~
+void csv_cleanup(csv_t *csv);
+~~~
+
+**Zeilenweises Lesen**
+
+~~~
+int csv_read(csv_t *csv, FILE *in);
+~~~
+
+**Feldzugriff**
+
+~~~
+int csv_nfields(const csv_t * const csv);
+const char * csv_field(const csv_t * const csv, int idx);
+~~~
+
+**Fehlercodes als Textmeldung**
+
+~~~
+const char * csv_err_str(csv_err_t csv_err);
+~~~
+
+## Fehlerbehandlung
+
+to be written
+
+## Anpassungen
+
+Die CSV-Bibliothek kann an verschiedene Bedürfnisse angepasst werden.
+
+### Übersetzungsoptionen
+
+Beim Compilieren der Datei csv.c können die Standardwerte für Feldbegrenzer und Feldtrenner als Makrodefinitionen `CSV_DEFAULT_DELIMITER` und `CSV_DEFAULT_SEPARATOR` voreingestellt werden.
+
+Option                         Beschreibung   Standardwert
+-------------------------- -------------- ---------------------------------
+`CSV_DEFAULT_DELIMITER`    Feldbegrenzer  `"`
+`CSV_DEFAULT_SEPARATOR`    Feldtrenner    `,`
+-------------------------- -------------- ---------------------------------
+Table: Makros
+
+Soll beispielsweise das in Deutschland viel häufiger vorkommende Semikolon (`;`) statt einem Komma (`,`) als Trennsymbol zwischen den Feldern einer CSV-Datei benutzt werden sieht der Aufruf zum Compilieren so aus:
+
+~~~
+cc -DCSV_DEFAULT_SEPARATOR="';'" -o csv-german.o -c csv.c
+~~~
+
+Anschließend wird die Datei `csv-german.o` statt `csv.o` zum Projekt dazugelinkt.
+
+Die Headerdatei (`csv.h`) bleibt unverändert.
+
+### Eigener Speicherallozierer
+
+to be written
+
+## Performance
+
+to be written
+
+## Lizenz
+
+In den letzten Jahrzehnten habe ich massiv vom Internet und seinen Inhalten profitiert. Ein gutes Stück meiner Kenntnisse und Fähigkeiten verdanke ich den vielen Foren, Webseiten, Newsgroups und Individuen die Informationen und Software kostenfrei und allgemein zugänglich bereitstellen.
+
+Aus diesem Grund stelle ich meine Software (sofern nicht anders angegeben) unter der freizügigen [Do What the Fuck You Want to Public License](http://www.wtfpl.net) zur Verfügung. Vielleicht findet jemand den Code nützlich oder kann Erkenntnisse daraus gewinnen.
+
+~~~
+Copyright © 2020 Thomas Schmucker
+This work is free. You can redistribute it and/or modify it under the
+terms of the Do What The Fuck You Want To Public License, Version 2,
+as published by Sam Hocevar. See https://www.wtfpl.net/ for more details.
+~~~
+