# 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 };   oder   csv_t csv;
                            csv_init(&csv);
~~~

4\. Verarbeite die CSV-Datei

~~~
for ( size_t nf; (nf = csv_read(&csv, in)) != 0; ) {  /* eine Zeile aus `in` lesen */
	for ( size_t 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.
~~~