core: Add pointer box / RAII impl

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

include/cescal/ptrbox.h

@@ -0,0 +1,71 @@
+/*
+ * Copyright (c) 2026, Chloe M.
+ * Provided under the BSD-3 clause
+ */
+
+#ifndef CESCAL_PTRBOX_H
+#define CESCAL_PTRBOX_H 1
+
+/*
+ * Represents a pointer box entry in which allocated data can
+ * be stored within
+ *
+ * @data: Allocated data backed by entry
+ * @next: Next pointer box entry
+ */
+struct ptrbox_entry {
+    void *data;
+    struct ptrbox_entry *next;
+};
+
+/*
+ * Represents a pointer box that enables RAII like behavior
+ *
+ * @head: Pointer box head
+ * @tail: Pointer box tail
+ */
+struct ptrbox {
+    struct ptrbox_entry *head;
+    struct ptrbox_entry *tail;
+};
+
+/*
+ * Initialize a pointer box
+ *
+ * @ptrbox: Pointer box to initialize
+ *
+ * Returns zero on success
+ */
+int ptrbox_init(struct ptrbox *ptrbox);
+
+/*
+ * Allocate memory and save the reference within a pointer box
+ *
+ * @ptrbox: Pointer box to save reference within
+ * @len:    Length of memory to allocate
+ *
+ * Returns the base of the allocated memory on success, otherwise
+ * NULL.
+ */
+void *ptrbox_alloc(struct ptrbox *ptrbox, size_t len);
+
+/*
+ * Duplicate a string and store the reference within a
+ * pointer box
+ *
+ * @ptrbox: Pointer box to store reference within
+ * @s:      String to duplicate
+ *
+ * Returns the duplicated string on success, otherwise NULL.
+ */
+char *ptrbox_strdup(struct ptrbox *ptrbox, const char *s);
+
+/*
+ * Destroy a pointer box along with all references stored
+ * within
+ *
+ * @ptrbox: Pointer box to destroy
+ */
+void ptrbox_destroy(struct ptrbox *ptrbox);
+
+#endif  /* !CESCAL_PTRBOX_H */

include/cescal/state.h

@@ -9,6 +9,7 @@
 #include <stdint.h>
 #include "cescal/readbuf.h"
 #include "cescal/tokbuf.h"
+#include "cescal/ptrbox.h"
 
 /*
  * Compiler state machine
@@ -16,11 +17,13 @@
  * @in_fd:  Input file descriptor
  * @rb:     Read buffer
  * @tokbuf: Token buffer
+ * @ptrbox: Global pointer box
  */
 struct cescal_state {
     int in_fd;
     struct readbuf rb;
     struct tokbuf tokbuf;
+    struct ptrbox ptrbox;
 };
 
 /*