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  * @note Passing NULL results in undefined behavior
  84  */
  85 const char *csv_parser_get_error(csv_parser_t *parser);
  86
  87 /**
  88  * Free a CSV document and all associated memory
  89  * @param document Document to free (NULL is safe to pass)
  90  */
  91 void csv_document_free(csv_document_t *document);
  92
  93 /**
  94  * Convert error code to human-readable string
  95  * @param error Error code
  96  * @return Error description string
  97  */
  98 const char *csv_error_string(csv_error_t error);
  99
 100 /* Data access helper functions */
 101
 102 /**
 103  * Check if document has a header record
 104  * @param document CSV document (must not be NULL)
 105  * @return true if header exists, false if not
 106  * @note Passing NULL results in undefined behavior
 107  */
 108 bool csv_document_has_header(const csv_document_t *document);
 109
 110 /**
 111  * Get the first record from document (skipping header if present)
 112  * @param document CSV document (must not be NULL)
 113  * @return First data record or NULL if empty
 114  * @note Passing NULL results in undefined behavior
 115  */
 116 csv_record_t *csv_document_get_first_record(const csv_document_t *document);
 117
 118 /**
 119  * Get the next record in sequence
 120  * @param record Current record (must not be NULL)
 121  * @return Next record or NULL if at end
 122  * @note Passing NULL results in undefined behavior
 123  */
 124 csv_record_t *csv_record_get_next(const csv_record_t *record);
 125
 126 /**
 127  * Get the first field from a record
 128  * @param record CSV record (must not be NULL)
 129  * @return First field or NULL if record is empty
 130  * @note Passing NULL results in undefined behavior
 131  */
 132 csv_field_t *csv_record_get_first_field(const csv_record_t *record);
 133
 134 /**
 135  * Get the next field in sequence
 136  * @param field Current field (must not be NULL)
 137  * @return Next field or NULL if at end
 138  * @note Passing NULL results in undefined behavior
 139  */
 140 csv_field_t *csv_field_get_next(const csv_field_t *field);
 141
 142 /**
 143  * Get field content as string
 144  * @param field CSV field (must not be NULL)
 145  * @return Field content string or NULL on error
 146  * @note Passing NULL results in undefined behavior
 147  */
 148 const char *csv_field_get_content(const csv_field_t *field);
 149
 150 #endif /* CSV_PARSER_H */