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_PARAM = -3,
  20     CSV_ERROR_IO = -4
  21 } csv_error_t;
  22
  23 /* CSV field structure */
  24 struct csv_field {
  25     char *content;              /* Field content (null-terminated) */
  26     struct csv_field *next;     /* Next field in the record */
  27 };
  28
  29 /* CSV record structure */
  30 struct csv_record {
  31     csv_field_t *fields;        /* Linked list of fields */
  32     size_t field_count;         /* Number of fields in this record */
  33     struct csv_record *next;    /* Next record in the document */
  34 };
  35
  36 /* CSV document structure */
  37 struct csv_document {
  38     csv_record_t *records;      /* Linked list of records (excluding header) */
  39     size_t record_count;        /* Number of data records (excluding header) */
  40     csv_record_t *header;       /* Optional header record (can be NULL) */
  41 };
  42
  43 /* Parser context (opaque) */
  44 struct csv_parser;
  45
  46 /**
  47  * Create a new CSV parser instance
  48  * @return Parser instance or NULL on error
  49  */
  50 csv_parser_t *csv_parser_create(void);
  51
  52 /**
  53  * Destroy a CSV parser instance and free all associated memory
  54  * @param parser Parser instance to destroy (NULL is safe to pass)
  55  */
  56 void csv_parser_destroy(csv_parser_t *parser);
  57
  58 /**
  59  * Parse CSV data from a string
  60  * @param parser Parser instance (must not be NULL)
  61  * @param input Input CSV string (null-terminated, must not be NULL)
  62  * @param document Pointer to store the parsed document (must not be NULL)
  63  * @return CSV_SUCCESS on success, error code on failure
  64  * @note The parser will set *document to NULL on failure
  65  */
  66 csv_error_t csv_parser_parse_string(csv_parser_t *parser, const char *input, csv_document_t **document);
  67
  68 /**
  69  * Parse CSV data from a file pointer
  70  * @param parser Parser instance (must not be NULL)
  71  * @param file Open file pointer (must not be NULL and readable)
  72  * @param document Pointer to store the parsed document (must not be NULL)
  73  * @return CSV_SUCCESS on success, error code on failure
  74  * @note The parser will set *document to NULL on failure
  75  * @note File position will be advanced to end of parsed content
  76  */
  77 csv_error_t csv_parser_parse_file(csv_parser_t *parser, FILE *file, csv_document_t **document);
  78
  79 /**
  80  * Get the last error message from the parser
  81  * @param parser Parser instance (must not be NULL)
  82  * @return Error message string (valid until next parse operation)
  83  */
  84 const char *csv_parser_get_error(csv_parser_t *parser);
  85
  86 /**
  87  * Free a CSV document and all associated memory
  88  * @param document Document to free (NULL is safe to pass)
  89  */
  90 void csv_document_free(csv_document_t *document);
  91
  92 /**
  93  * Convert error code to human-readable string
  94  * @param error Error code
  95  * @return Error description string
  96  */
  97 const char *csv_error_string(csv_error_t error);
  98
  99 /* Data access helper functions */
 100
 101 /**
 102  * Check if document has a header record
 103  * @param document CSV document (must not be NULL)
 104  * @return true if header exists, false if not
 105  */
 106 bool csv_document_has_header(const csv_document_t *document);
 107
 108 /**
 109  * Get the first record from document (skipping header if present)
 110  * @param document CSV document (must not be NULL)
 111  * @return First data record or NULL if empty
 112  */
 113 csv_record_t *csv_document_get_first_record(const csv_document_t *document);
 114
 115 /**
 116  * Get the next record in sequence
 117  * @param record Current record (must not be NULL)
 118  * @return Next record or NULL if at end
 119  */
 120 csv_record_t *csv_record_get_next(const csv_record_t *record);
 121
 122 /**
 123  * Get the first field from a record
 124  * @param record CSV record (must not be NULL)
 125  * @return First field or NULL if record is empty
 126  */
 127 csv_field_t *csv_record_get_first_field(const csv_record_t *record);
 128
 129 /**
 130  * Get the next field in sequence
 131  * @param field Current field (must not be NULL)
 132  * @return Next field or NULL if at end
 133  */
 134 csv_field_t *csv_field_get_next(const csv_field_t *field);
 135
 136 /**
 137  * Get field content as string
 138  * @param field CSV field (must not be NULL)
 139  * @return Field content string or NULL on error
 140  */
 141 const char *csv_field_get_content(const csv_field_t *field);
 142
 143 /**
 144  * Set the first record as the header (moves it from records to header)
 145  * @param document CSV document (must not be NULL and have at least one record)
 146  * @return CSV_SUCCESS on success, error code on failure
 147  */
 148 csv_error_t csv_document_set_first_record_as_header(csv_document_t *document);
 149
 150 #endif /* CSV_PARSER_H */