core: symbol: Add symbol managementmain

Signed-off-by: Ian Moffett <ian@mirocom.org>

4 files changed, 229 insertions, 0 deletions

diff --git a/core/state.c b/core/state.c
index f6ed48e..b64271c 100644
--- a/core/state.c
+++ b/core/state.c
@@ -35,6 +35,11 @@ state_init(struct cescal_state *state, const char *pathname)
         return -1;
     }
 
+    if (symbol_table_init(&state->symtab) < 0) {
+        close(state->in_fd);
+        return -1;
+    }
+
     if (ptrbox_init(&state->ptrbox) < 0) {
         close(state->in_fd);
         return -1;
@@ -50,4 +55,5 @@ state_close(struct cescal_state *state)
     state->in_fd = -1;
     ptrbox_destroy(&state->ptrbox);
     tokbuf_destroy(&state->tokbuf);
+    symbol_table_destroy(&state->symtab);
 }
diff --git a/core/symbol.c b/core/symbol.c
new file mode 100644
index 0000000..daa4411
--- /dev/null
+++ b/core/symbol.c
@@ -0,0 +1,130 @@
+/*
+ * Copyright (c) 2026, Chloe M.
+ * Provided under the BSD-3 clause
+ */
+
+#include <stdint.h>
+#include <stddef.h>
+#include <stdlib.h>
+#include <string.h>
+#include <errno.h>
+#include "cescal/symbol.h"
+
+/*
+ * Push a symbol into a symbol table
+ *
+ * @symtab:     Symbol table to push to
+ * @symbol:     Symbol to push
+ *
+ * Returns zero on success
+ */
+static int
+symbol_table_push(struct symbol_table *symtab, struct symbol *symbol)
+{
+    if (symtab == NULL || symbol == NULL) {
+        errno = EINVAL;
+        return -1;
+    }
+
+    symbol->next = NULL;
+    if (symtab->head == NULL || symtab->tail == NULL) {
+        symtab->head = symbol;
+        symtab->tail = symbol;
+    } else {
+        symtab->head->next = symbol;
+        symtab->head = symbol;
+    }
+
+    return 0;
+}
+
+int
+symbol_table_init(struct symbol_table *symtab)
+{
+    if (symtab == NULL) {
+        errno = EINVAL;
+        return -1;
+    }
+
+    symtab->head = NULL;
+    symtab->tail = NULL;
+    return 0;
+}
+
+int
+symbol_allocate(struct symbol_table *symtab, const char *name,
+    symtype_t type, struct symbol **res)
+{
+    struct symbol *symbol;
+
+    if (symtab == NULL || name == NULL) {
+        errno = EINVAL;
+        return -1;
+    }
+
+    if (res == NULL) {
+        errno = EINVAL;
+        return -1;
+    }
+
+    symbol = malloc(sizeof(*symbol));
+    if (symbol == NULL) {
+        errno = -ENOMEM;
+        return -1;
+    }
+
+    symbol->name = strdup(name);
+    symbol->type = type;
+    if (symbol_table_push(symtab, symbol) < 0) {
+        free(symbol);
+        return -1;
+    }
+
+    *res = symbol;
+    return 0;
+}
+
+void
+symbol_table_destroy(struct symbol_table *symtab)
+{
+    struct symbol *symbol, *tmp;
+
+    if (symtab == NULL) {
+        return;
+    }
+
+    symbol = symtab->tail;
+    while (symbol != NULL) {
+        tmp = symbol;
+        if (tmp->name != NULL)
+            free(tmp->name);
+        free(tmp);
+        symbol = symbol->next;
+    }
+}
+
+struct symbol *
+symbol_byname(struct symbol_table *symtab, const char *name)
+{
+    struct symbol *symbol;
+
+    if (symtab == NULL || name == NULL) {
+        return NULL;
+    }
+
+    symbol = symtab->head;
+    while (symbol != NULL) {
+        if (*symbol->name != *name) {
+            symbol = symbol->next;
+            continue;
+        }
+
+        if (strcmp(symbol->name, name) == 0) {
+            return symbol;
+        }
+
+        symbol = symbol->next;
+    }
+
+    return NULL;
+}
diff --git a/include/cescal/state.h b/include/cescal/state.h
index 8801837..43eddc1 100644
--- a/include/cescal/state.h
+++ b/include/cescal/state.h
@@ -10,6 +10,7 @@
 #include "cescal/readbuf.h"
 #include "cescal/tokbuf.h"
 #include "cescal/ptrbox.h"
+#include "cescal/symbol.h"
 
 /*
  * Compiler state machine
@@ -20,6 +21,7 @@
  * @ptrbox: Global pointer box
  * @lex_putback: Lexer putback buffer
  * @pass:  Current pass
+ * @symtab: Symbol table
  */
 struct cescal_state {
     int in_fd;
@@ -28,6 +30,7 @@ struct cescal_state {
     struct ptrbox ptrbox;
     char lex_putback;
     uint8_t pass;
+    struct symbol_table symtab;
 };
 
 /*
diff --git a/include/cescal/symbol.h b/include/cescal/symbol.h
new file mode 100644
index 0000000..c3e72eb
--- /dev/null
+++ b/include/cescal/symbol.h
@@ -0,0 +1,90 @@
+/*
+ * 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 */