#ifndef ICAL_PARSER_H
#define ICAL_PARSER_H

#include <stddef.h>
#include <stdio.h>
#include <stdbool.h>

/* Include collection library headers */
#include <derp/common.h>
#include <derp/vector.h>

/* Forward declarations */
typedef struct ical_parser ical_parser_t;
typedef struct ical_property ical_property_t;
typedef struct ical_parameter ical_parameter_t;
typedef struct ical_component ical_component_t;

/* Error codes */
typedef enum {
    ICAL_SUCCESS = 0,
    ICAL_ERROR_MEMORY = -1,
    ICAL_ERROR_PARSE = -2,
    ICAL_ERROR_INVALID_PARAMETER = -3,
    ICAL_ERROR_IO = -4
} ical_error_t;

/* Error information structure */
typedef struct {
    const char *message;        /* Error message (valid until next parse operation) */
    int line;                   /* Line number where error occurred (1-based, 0 if unknown) */
    int column;                 /* Column number where error occurred (1-based, 0 if unknown) */
    bool has_location;          /* Whether line/column information is available */
} ical_error_info_t;

/* iCalendar parameter structure */
struct ical_parameter {
    char *name;                 /* Parameter name (uppercase) */
    char *value;                /* Parameter value */
};

/* iCalendar property structure */
struct ical_property {
    char *name;                 /* Property name (uppercase) */
    vector *parameters;         /* Vector of ical_parameter_t* */
    char *value;                /* Property value */
};

/* iCalendar component structure */
struct ical_component {
    char *type;                 /* Component type (uppercase, e.g., "VCALENDAR", "VEVENT") */
    vector *properties;         /* Vector of ical_property_t* */
    vector *subcomponents;      /* Vector of ical_component_t* (nested components) */
};

/* Parser (opaque, stateful - maintains error state between operations) */
struct ical_parser;

/**
 * Create a new iCalendar parser
 * @note Parser maintains error state; create separate parsers for concurrent use
 */
ical_parser_t *ical_parser_create(void);

/**
 * Free an iCalendar parser and all associated memory
 */
void ical_parser_destroy(ical_parser_t *parser);

/**
 * Parse iCalendar data from a string
 * @note Sets *calendar to NULL on failure
 * @return ical_component_t* representing the VCALENDAR on success, NULL on failure
 */
ical_error_t ical_parser_parse_string(ical_parser_t *parser, const char *input, ical_component_t **calendar);

/**
 * Parse iCalendar data from a file
 * @note Sets *calendar to NULL on failure
 * @note Advances file position to end of parsed content
 * @return ical_component_t* representing the VCALENDAR on success, NULL on failure
 */
ical_error_t ical_parser_parse_file(ical_parser_t *parser, FILE *file, ical_component_t **calendar);

/**
 * Get detailed error information from the parser
 * @note Message pointer is valid until the next parse operation
 */
ical_error_info_t ical_parser_get_error_info(ical_parser_t *parser);

/**
 * Convert error code to human-readable string
 */
const char *ical_error_string(ical_error_t error);

/**
 * Free an iCalendar component and all its associated memory
 */
void ical_component_free(ical_component_t *component);

/**
 * Free an iCalendar property and all its associated memory
 */
void ical_property_free(ical_property_t *property);

/**
 * Free an iCalendar parameter and all its associated memory
 */
void ical_parameter_free(ical_parameter_t *parameter);

#endif /* ICAL_PARSER_H */