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 /* 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 value in the CSV */
  32 struct csv_field {
  33     char *value;                /* Field value (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 field values */
  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 data records (excluding header) */
  47     size_t record_count;        /* Number of data records (excluding header) */
  48     csv_record_t *header;       /* Optional header record (can be NULL) */
  49 };
  50
  51 /* Parser context (opaque, stateful - maintains error state between operations) */
  52 struct csv_parser;
  53
  54 /**
  55  * Create a new CSV parser context
  56  * @return Parser context or NULL on error
  57  * @note Parser maintains error state; create separate parsers for concurrent use
  58  */
  59 csv_parser_t *csv_parser_create(void);
  60
  61 /**
  62  * Destroy a CSV parser context and free all associated memory
  63  * @param parser Parser context to destroy (NULL is safe to pass)
  64  */
  65 void csv_parser_destroy(csv_parser_t *parser);
  66
  67 /**
  68  * Parse CSV data from a string
  69  * @param parser Parser context (must not be NULL)
  70  * @param input Input CSV string (null-terminated, must not be NULL)
  71  * @param document Pointer to store the parsed document (must not be NULL)
  72  * @return CSV_SUCCESS on success, error code on failure
  73  * @note The parser will set *document to NULL on failure
  74  */
  75 csv_error_t csv_parser_parse_string(csv_parser_t *parser, const char *input, csv_document_t **document);
  76
  77 /**
  78  * Parse CSV data from a file pointer
  79  * @param parser Parser context (must not be NULL)
  80  * @param file Open file pointer (must not be NULL and readable)
  81  * @param document Pointer to store the parsed document (must not be NULL)
  82  * @return CSV_SUCCESS on success, error code on failure
  83  * @note The parser will set *document to NULL on failure
  84  * @note File position will be advanced to end of parsed content
  85  */
  86 csv_error_t csv_parser_parse_file(csv_parser_t *parser, FILE *file, csv_document_t **document);
  87
  88 /**
  89  * Get detailed error information from the parser
  90  * @param parser Parser context (must not be NULL)
  91  * @return Error information structure
  92  * @note The returned message pointer is valid until the next parse operation
  93  */
  94 csv_error_info_t csv_parser_get_error_info(csv_parser_t *parser);
  95
  96 /**
  97  * Free a CSV document and all associated memory
  98  * @param document Document to free (NULL is safe to pass)
  99  */
 100 void csv_document_free(csv_document_t *document);
 101
 102 /**
 103  * Convert error code to human-readable string
 104  * @param error Error code
 105  * @return Error description string
 106  */
 107 const char *csv_error_string(csv_error_t error);
 108
 109 /* Data access helper functions */
 110
 111 /**
 112  * Check if document has a header record
 113  * @param document CSV document (must not be NULL)
 114  * @return true if header exists, false if not
 115  */
 116 bool csv_document_has_header(const csv_document_t *document);
 117
 118 /**
 119  * Get the first data record from document (skipping header if present)
 120  * @param document CSV document (must not be NULL)
 121  * @return First data record or NULL if empty
 122  */
 123 csv_record_t *csv_document_get_first_record(const csv_document_t *document);
 124
 125 /**
 126  * Get the next record in sequence
 127  * @param record Current record (must not be NULL)
 128  * @return Next record or NULL if at end
 129  */
 130 csv_record_t *csv_record_get_next(const csv_record_t *record);
 131
 132 /**
 133  * Get the first field from a record
 134  * @param record CSV record (must not be NULL)
 135  * @return First field or NULL if record is empty
 136  */
 137 csv_field_t *csv_record_get_first_field(const csv_record_t *record);
 138
 139 /**
 140  * Get the next field in sequence
 141  * @param field Current field (must not be NULL)
 142  * @return Next field or NULL if at end
 143  */
 144 csv_field_t *csv_field_get_next(const csv_field_t *field);
 145
 146 /**
 147  * Get field value as string
 148  * @param field CSV field (must not be NULL)
 149  * @return Field value string or NULL on error
 150  * @note Returns the parsed string value from a CSV cell
 151  */
 152 const char *csv_field_get_value(const csv_field_t *field);
 153
 154 /**
 155  * Set the first record as the header (moves it from records to header)
 156  * @param document CSV document (must not be NULL and have at least one record)
 157  * @return CSV_SUCCESS on success, error code on failure
 158  * @note This operation modifies the document structure by promoting the first data record
 159  */
 160 csv_error_t csv_document_set_first_record_as_header(csv_document_t *document);
 161
 162 #endif /* CSV_PARSER_H */