begriffs open source - sa-parse/blob - src/csv_parser.h

   1 #ifndef CSV_PARSER_H
   2 #define CSV_PARSER_H
   3
   4 #include <stddef.h>
   5 #include <stdio.h>
   6 #include <stdbool.h>
   7
   8 /* Forward declarations */
   9 typedef struct csv_parser csv_parser_t;
  10 typedef struct csv_field csv_field_t;
  11 typedef struct csv_record csv_record_t;
  12 typedef struct csv_document csv_document_t;
  13
  14 /* Error codes */
  15 typedef enum {
  16     CSV_SUCCESS = 0,
  17     CSV_ERROR_MEMORY = -1,
  18     CSV_ERROR_PARSE = -2,
  19     CSV_ERROR_INVALID_PARAMETER = -3,
  20     CSV_ERROR_IO = -4
  21 } csv_error_t;
  22
  23 /* Error information structure */
  24 typedef struct {
  25     const char *message;        /* Error message (valid until next parse operation) */
  26     int line;                   /* Line number where error occurred (1-based, 0 if unknown) */
  27     int column;                 /* Column number where error occurred (1-based, 0 if unknown) */
  28     bool has_location;          /* Whether line/column information is available */
  29 } csv_error_info_t;
  30
  31 /* CSV field structure - represents a single cell in the CSV */
  32 struct csv_field {
  33     char *value;                /* Cell content (null-terminated string) */
  34     struct csv_field *next;     /* Next field in the record */
  35 };
  36
  37 /* CSV record structure - represents a single row in the CSV */
  38 struct csv_record {
  39     csv_field_t *fields;        /* Linked list of fields */
  40     size_t field_count;         /* Number of fields in this record */
  41     struct csv_record *next;    /* Next record in the document */
  42 };
  43
  44 /* CSV document structure - represents the complete parsed CSV */
  45 struct csv_document {
  46     csv_record_t *records;      /* Linked list of records */
  47     size_t record_count;        /* Number of records */
  48 };
  49
  50 /* Parser (opaque, stateful - maintains error state between operations) */
  51 struct csv_parser;
  52
  53 /**
  54  * Create a new CSV parser
  55  * @note Parser maintains error state; create separate parsers for concurrent use
  56  */
  57 csv_parser_t *csv_parser_create(void);
  58
  59 /**
  60  * Free a CSV parser and all associated memory
  61  */
  62 void csv_parser_destroy(csv_parser_t *parser);
  63
  64 /**
  65  * Parse CSV data from a string
  66  * @note Sets *document to NULL on failure
  67  */
  68 csv_error_t csv_parser_parse_string(csv_parser_t *parser, const char *input, csv_document_t **document);
  69
  70 /**
  71  * Parse CSV data from a file
  72  * @note Sets *document to NULL on failure
  73  * @note Advances file position to end of parsed content
  74  */
  75 csv_error_t csv_parser_parse_file(csv_parser_t *parser, FILE *file, csv_document_t **document);
  76
  77 /**
  78  * Get detailed error information from the parser
  79  * @note Message pointer is valid until the next parse operation
  80  */
  81 csv_error_info_t csv_parser_get_error_info(csv_parser_t *parser);
  82
  83 /**
  84  * Free a CSV document and all associated memory
  85  */
  86 void csv_document_free(csv_document_t *document);
  87
  88 /**
  89  * Convert error code to human-readable string
  90  */
  91 const char *csv_error_string(csv_error_t error);
  92
  93 /* Data access functions */
  94
  95 /**
  96  * Get the first record from document
  97  */
  98 csv_record_t *csv_document_get_first_record(const csv_document_t *document);
  99
 100 /**
 101  * Get the next record in sequence
 102  */
 103 csv_record_t *csv_record_get_next(const csv_record_t *record);
 104
 105 /**
 106  * Get the first field from a record
 107  */
 108 csv_field_t *csv_record_get_first_field(const csv_record_t *record);
 109
 110 /**
 111  * Get the next field in sequence
 112  */
 113 csv_field_t *csv_field_get_next(const csv_field_t *field);
 114
 115 /**
 116  * Get cell content as string
 117  */
 118 const char *csv_field_get_value(const csv_field_t *field);
 119
 120 #endif /* CSV_PARSER_H */