/*
 * Copyright (c) 2026, Chloe M.
 * Provided under the BSD-3 clause
 */

#ifndef CESCAL_SYMBOL_H
#define CESCAL_SYMBOL_H 1

#include <stdint.h>
#include <stddef.h>

/*
 * Represents valid symbol types
 *
 * @SYMBOL_NONE:    No associated type
 * @SYMBOL_MACRO:   This symbol is a macro
 */
typedef enum {
    SYMBOL_NONE,
    SYMBOL_MACRO
} symtype_t;

/*
 * Represents a program symbol
 *
 * @name: Name of symbol
 * @type: Symbol type
 * @next: Next symbol in list
 */
struct symbol {
    char *name;
    symtype_t type;
    struct symbol *next;
};

/*
 * Represents a symbol table which holds one or
 * more symbols
 *
 * @head: List head
 * @tail: List tail
 *
 * XXX TODO: This should be a hashmap instead of a linked
 *           list.
 */
struct symbol_table {
    struct symbol *head;
    struct symbol *tail;
};

/*
 * Allocate a new symbol and add it to the specified symbol table
 *
 * @name:   Name of symbol to allocate
 * @type:   Symbol type to assign
 * @res:    Result is written here
 *
 * Returns zero on success
 */
int symbol_allocate(
    struct symbol_table *symtab, const char *name,
    symtype_t type, struct symbol **res);

/*
 * Obtain a symbol by name from the symbol table
 *
 * @symtab: Symbol table to look up within
 * @name:   Name to look up
 *
 * Returns the found symbol on success, otherwise NULL on failure
 */
struct symbol *symbol_byname(struct symbol_table *symtab, const char *name);

/*
 * Initialize a symbol table
 *
 * @symtab: Symbol table to initialize
 *
 * Returns zero on success
 */
int symbol_table_init(struct symbol_table *symtab);

/*
 * Destroy a symbol table and its allocated resources
 *
 * @symtab: Symbol table to destroy
 */
void symbol_table_destroy(struct symbol_table *symtab);

#endif  /* !CESCAL_SYMBOL_H */