1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
# 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); /* Feld `i` der gelesenen 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 nachdem 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`()
Irgendwelche regulären Ausdrücke
- 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**
~~~
size_t csv_read(csv_t *csv, FILE *in);
~~~
**Feldzugriff**
~~~
size_t csv_nfields(const csv_t *const csv);
const char *csv_field(const csv_t *const csv, size_t 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.
~~~
|
