2 files changed, 93 insertions, 0 deletions
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 */