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 /* Include collection library headers */
   9 #include <derp/common.h>
  10 #include <derp/vector.h>
  11
  12 /* Forward declarations */
  13 typedef struct csv_parser csv_parser_t;
  14 typedef struct csv_record csv_record_t;
  15
  16 /* Error codes */
  17 typedef enum {
  18     CSV_SUCCESS = 0,
  19     CSV_ERROR_MEMORY = -1,
  20     CSV_ERROR_PARSE = -2,
  21     CSV_ERROR_INVALID_PARAMETER = -3,
  22     CSV_ERROR_IO = -4
  23 } csv_error_t;
  24
  25 /* Error information structure */
  26 typedef struct {
  27     const char *message;        /* Error message (valid until next parse operation) */
  28     int line;                   /* Line number where error occurred (1-based, 0 if unknown) */
  29     int column;                 /* Column number where error occurred (1-based, 0 if unknown) */
  30     bool has_location;          /* Whether line/column information is available */
  31 } csv_error_info_t;
  32
  33 /* CSV record structure - represents a single row in the CSV */
  34 struct csv_record {
  35     vector *fields;             /* Vector of char* field values */
  36 };
  37
  38 /* Parser (opaque, stateful - maintains error state between operations) */
  39 struct csv_parser;
  40
  41 /**
  42  * Create a new CSV parser
  43  * @note Parser maintains error state; create separate parsers for concurrent use
  44  */
  45 csv_parser_t *csv_parser_create(void);
  46
  47 /**
  48  * Free a CSV parser and all associated memory
  49  */
  50 void csv_parser_destroy(csv_parser_t *parser);
  51
  52 /**
  53  * Parse CSV data from a string
  54  * @note Sets *records to NULL on failure
  55  * @return Vector of csv_record_t* on success, NULL on failure
  56  */
  57 csv_error_t csv_parser_parse_string(csv_parser_t *parser, const char *input, vector **records);
  58
  59 /**
  60  * Parse CSV data from a file
  61  * @note Sets *records to NULL on failure
  62  * @note Advances file position to end of parsed content
  63  * @return Vector of csv_record_t* on success, NULL on failure
  64  */
  65 csv_error_t csv_parser_parse_file(csv_parser_t *parser, FILE *file, vector **records);
  66
  67 /**
  68  * Get detailed error information from the parser
  69  * @note Message pointer is valid until the next parse operation
  70  */
  71 csv_error_info_t csv_parser_get_error_info(csv_parser_t *parser);
  72
  73 /**
  74  * Convert error code to human-readable string
  75  */
  76 const char *csv_error_string(csv_error_t error);
  77
  78 #endif /* CSV_PARSER_H */