Add email example; fix const correctness across all API signatures

- Propagate const char * through all public API parameters (context, value,
  syntax) and matching internal signatures in attribute.c, element.c,
  context.c, syntax.c, cfi_json.c — allows callers to pass string literals
  and const strings without casts
- Add examples/email.c: models a multi-part email with indexed recipient
  nodes, demonstrates BaseCfiLook enumeration, BaseCfiWalk, JSON round-trip
- Wire examples/email into Makefile (pattern rule, `make examples`, `make all`)
- Update README: lead with the email use case and a motivating snippet;
  point to examples/email.c for the full runnable version

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: phil-base

Makefile

@@ -18,25 +18,30 @@ DEPS    = $(OBJS:.o=.d)
 $(LIB): $(OBJS)
 	ar -rs $@ $^
 
-examples/test1.o: examples/test1.c
+examples/%.o: examples/%.c
 	$(CC) $(CFLAGS) -I. -c -o $@ $<
 
 test1: $(LIB) examples/test1.o
 	$(CC) $(CFLAGS) -o $@ examples/test1.o $(LIB)
 
+examples/email: $(LIB) examples/email.o
+	$(CC) $(CFLAGS) -o $@ examples/email.o $(LIB)
+
 check: test1
 	./test1
 
 memcheck: test1
 	valgrind --error-exitcode=1 --leak-check=full --show-leak-kinds=all ./test1
 
-all: $(LIB) test1
+examples: examples/email
+
+all: $(LIB) test1 examples
 
 clean:
-	$(RM) $(OBJS) $(DEPS) examples/test1.o examples/test1.d
+	$(RM) $(OBJS) $(DEPS) examples/test1.o examples/test1.d examples/email.o examples/email.d
 
 clobber: clean
-	$(RM) $(LIB) test1 $(MODULE).pc log.log
+	$(RM) $(LIB) test1 examples/email $(MODULE).pc log.log
 
 $(MODULE).pc: basecfi.pc.in
 	sed -e 's|@PREFIX@|$(PREFIX)|g' -e 's|@VERSION@|$(VERSION)|g' $< > $@
@@ -47,4 +52,4 @@ install: $(LIB) $(MODULE).pc
 	install -m 444 $(HEADERS) $(PREFIX)/include
 	install -m 444 $(MODULE).pc $(PCDIR)/$(MODULE).pc
 
-.PHONY: all check memcheck clean clobber install
+.PHONY: all check memcheck examples clean clobber install

README.md

@@ -1,52 +1,56 @@
 # CFI — Common Format Interface
 
-A self-contained C99 library for building and querying hierarchical key-value trees in memory. Nodes are addressed by slash-separated paths; each node holds named string attributes. No external dependencies.
+A self-contained C library for building and querying hierarchical key-value trees in memory. Nodes are addressed by slash-separated paths; each node holds named string attributes. No external dependencies.
+
+CFI is well-suited to structured message or protocol data: anything where you have
+repeated, named sub-elements (headers, parts, recipients) that you want to address
+by path and enumerate without knowing the shape upfront.
 
 ## Building
 
 ```sh
-make          # builds basecfi.a + test binaries
+make          # builds basecfi.a + example binaries
 make check    # run the test suite
 make install  # install basecfi.a and headers to /usr/local (override PREFIX=)
 ```
 
 CI runs on every push against Ubuntu and macOS.
 
-## Quick start
+## Example — modelling a multi-part email
 
 ```c
-#include "basecfi.h"
-#include "cfi_json.h"   /* for ToJson / FromJson / Copy */
-
-/* create a handle */
-void *h = NULL;
-BaseCfiCreate(&h, NULL);
-BaseCfiGoto(h, "/");
-
-/* build a tree */
-BaseCfiAdd(h, "user",  0);          /* add child node */
-BaseCfiAdd(h, "prefs", 0);
-
-BaseCfiGoto(h, "/user");
-BaseCfiSet(h, "name",  "Alice");    /* set attribute on current node */
-BaseCfiSet(h, "email", "a@example.com");
-
-BaseCfiGoto(h, "/prefs");
-BaseCfiSet(h, "theme", "dark");
+/* add three recipients as indexed child nodes under /headers */
+char *ctx;
+
+ctx = BaseCfiIndexer("to", 0);
+BaseCfiAdd(h, ctx, 1);               /* create /headers/to[0] and go there */
+BaseCfiSet(h, "name",    "Bob Smith");
+BaseCfiSet(h, "address", "bob@example.com");
+BaseCfiGoto(h, "/headers");
+free(ctx);
+
+/* ... repeat for to[1], to[2] ... */
+
+/* enumerate recipients without knowing the count upfront */
+char **children;
+BaseCfiLook(h, "/headers", BASE_CFI_LOOK_CONTEXT, &children);
+for (int i = 0; children[i]; i++) {
+    if (strncmp(children[i], "to[", 3) != 0) continue;
+    char path[128];
+    snprintf(path, sizeof(path), "/headers/%s/name", children[i]);
+    printf("%s\n", BaseCfiValue(h, path, 1));
+}
+for (int i = 0; children[i]; i++) free(children[i]);
+free(children);
 
-/* read back */
-char *v;
-BaseCfiGet(h, "/user/name", &v);    /* v → "Alice"; do NOT free */
+/* serialize the whole message to JSON */
+char *json = BaseCfiToJson(h, "/");
+```
 
-/* list children of root */
-char **list;
-BaseCfiLook(h, "/", BASE_CFI_LOOK_CONTEXT, &list);
-/* list = {"user", "prefs", NULL} — free each element, then the array */
-for (int i = 0; list[i]; i++) free(list[i]);
-free(list);
+A fully runnable version of this example is in [`examples/email.c`](examples/email.c).
+Build it with `make examples` (or `make all`) and run `./examples/email`.
 
-BaseCfiDestroy(h);
-```
+## Quick start
 
 ## Paths
 

attribute.c

@@ -125,7 +125,7 @@ int BaseCfiAttributeDestroy(BaseCfiElement *element)
  *  Returns BASE_CFI_OK on success.  Otherwise returns error status.
  */
 
-int BaseCfiAttributeFindByName(BaseCfiElement *element, char *name, int *offset)
+int BaseCfiAttributeFindByName(BaseCfiElement *element, const char *name, int *offset)
 {
     static char     *thisfunc = "BaseCfiAttributeFindByName()";
     int             i;
@@ -213,7 +213,7 @@ int BaseCfiAttributeDestroyByPosition(BaseCfiElement *element, int position)
  *  Returns BASE_CFI_OK on success.  Otherwise returns error status.
  */
 
-int BaseCfiAttributeDestroyByName(BaseCfiElement *element, char *name)
+int BaseCfiAttributeDestroyByName(BaseCfiElement *element, const char *name)
 {
     static char     *thisfunc = "BaseCfiAttributeDestroyByName()";
     int             status;
@@ -264,7 +264,7 @@ int BaseCfiAttributeDestroyByName(BaseCfiElement *element, char *name)
  *  Returns BASE_CFI_OK on success.  Otherwise returns error status.
  */
 
-int BaseCfiAttributeCreate(BaseCfiElement *element, char *name, char *value)
+int BaseCfiAttributeCreate(BaseCfiElement *element, const char *name, const char *value)
 {
     static char     *thisfunc = "BaseCfiAttributeCreate()";
     int             i;
@@ -340,7 +340,7 @@ int BaseCfiAttributeCreate(BaseCfiElement *element, char *name, char *value)
  *  Returns BASE_CFI_OK on success.  Otherwise returns an error status.
  */
 
-int BaseCfiAttributeSet(BaseCfiElement *element, char *name, char *value, int set)
+int BaseCfiAttributeSet(BaseCfiElement *element, const char *name, const char *value, int set)
 {
     static char     *thisfunc = "BaseCfiAttributeSet()";
     int             status;
@@ -438,7 +438,7 @@ int BaseCfiAttributeSet(BaseCfiElement *element, char *name, char *value, int se
  *  Returns BASE_CFI_OK on success.  Otherwise returns error status.
  */
 
-int BaseCfiAttributeGetByName(BaseCfiElement *element, char *name, char **value)
+int BaseCfiAttributeGetByName(BaseCfiElement *element, const char *name, char **value)
 {
     static char     *thisfunc = "BaseCfiAttributeGetByName()";
     int             i;

attribute.h

@@ -24,5 +24,5 @@
 
 // prototypes
 
-int BaseCfiAttributeSet(BaseCfiElement *, char *, char *, int);
-int BaseCfiAttributeGetByName(BaseCfiElement *, char *, char **);
+int BaseCfiAttributeSet(BaseCfiElement *, const char *, const char *, int);
+int BaseCfiAttributeGetByName(BaseCfiElement *, const char *, char **);

basecfi.h

@@ -82,7 +82,7 @@
  *         and not yet implemented; non-NULL values are accepted but ignored.
  * *cfihandle: receives an opaque handle on success.
  */
-int BaseCfiCreate(void **cfihandle, char *syntax);
+int BaseCfiCreate(void **cfihandle, const char *syntax);
 
 /*
  * BaseCfiDestroy — free the tree and all its contents.
@@ -99,28 +99,28 @@ int BaseCfiDestroy(void *cfihandle);
  * Returns BASE_CFI_CONTEXT_FOUND if the node already exists.
  * If gothere is non-zero, the default context is moved to the new node.
  */
-int BaseCfiAdd(void *cfihandle, char *context, int gothere);
+int BaseCfiAdd(void *cfihandle, const char *context, int gothere);
 
 /*
  * BaseCfiDelete — remove the node at context and all of its descendants.
  */
-int BaseCfiDelete(void *cfihandle, char *context);
+int BaseCfiDelete(void *cfihandle, const char *context);
 
 /*
  * BaseCfiSet — set (or replace) an attribute on the node at context.
  *
  * The library copies value; the caller retains ownership.
  * Pass NULL as value to delete the attribute.
  */
-int BaseCfiSet(void *cfihandle, char *context, char *value);
+int BaseCfiSet(void *cfihandle, const char *context, const char *value);
 
 /*
  * BaseCfiExtend — append value to an existing attribute.
  *
  * Creates the attribute if it does not yet exist.
  * The library copies value; the caller retains ownership.
  */
-int BaseCfiExtend(void *cfihandle, char *context, char *value);
+int BaseCfiExtend(void *cfihandle, const char *context, const char *value);
 
 /*
  * BaseCfiGet — retrieve an attribute value.
@@ -130,7 +130,7 @@ int BaseCfiExtend(void *cfihandle, char *context, char *value);
  * *value is set to NULL (and BASE_CFI_OK is returned) when the attribute
  * or its parent node does not exist.
  */
-int BaseCfiGet(void *cfihandle, char *context, char **value);
+int BaseCfiGet(void *cfihandle, const char *context, char **value);
 
 /*
  * BaseCfiLook — list the direct children of a node.
@@ -144,15 +144,15 @@ int BaseCfiGet(void *cfihandle, char *context, char **value);
  *     for (int i = 0; (*list)[i]; i++) free((*list)[i]);
  *     free(*list);
  */
-int BaseCfiLook(void *cfihandle, char *context, int type, char ***list);
+int BaseCfiLook(void *cfihandle, const char *context, int type, char ***list);
 
 /*
  * BaseCfiGoto — set the default context for relative path resolution.
  *
  * Pass "/" to reset to the root. Subsequent calls that use a relative
  * context path resolve from this point.
  */
-int BaseCfiGoto(void *cfihandle, char *context);
+int BaseCfiGoto(void *cfihandle, const char *context);
 
 /*
  * BaseCfiValue — convenience wrapper around BaseCfiGet.
@@ -161,7 +161,7 @@ int BaseCfiGoto(void *cfihandle, char *context);
  * If safe is non-zero, returns "" (never NULL) when the attribute is
  * missing or an error occurs. If safe is zero, returns NULL on error.
  */
-char *BaseCfiValue(void *cfihandle, char *context, int safe);
+char *BaseCfiValue(void *cfihandle, const char *context, int safe);
 
 /*
  * BaseCfiIndexer — format a context name with an array index.
@@ -170,19 +170,19 @@ char *BaseCfiValue(void *cfihandle, char *context, int safe);
  * The caller must free the returned pointer.
  * Returns NULL on allocation failure.
  */
-char *BaseCfiIndexer(char *context, int index);
+char *BaseCfiIndexer(const char *context, int index);
 
 /*
  * BaseCfiSetLong — store a long integer as a string attribute.
  */
-int BaseCfiSetLong(void *cfihandle, char *context, long value);
+int BaseCfiSetLong(void *cfihandle, const char *context, long value);
 
 /*
  * BaseCfiValueLong — retrieve an attribute and return it as a long.
  *
  * Returns 0 when the attribute is absent or cannot be converted.
  */
-long BaseCfiValueLong(void *cfihandle, char *context);
+long BaseCfiValueLong(void *cfihandle, const char *context);
 
 /*
  * Walk API
@@ -217,7 +217,7 @@ typedef int (*BaseCfiWalkFn)(void *cfihandle,
                               int         flags,
                               void       *userdata);
 
-int BaseCfiWalk(void *cfihandle, char *context,
+int BaseCfiWalk(void *cfihandle, const char *context,
                 BaseCfiWalkFn callback, void *userdata);
 
 /*
@@ -227,7 +227,7 @@ int BaseCfiWalk(void *cfihandle, char *context,
  * any argument is invalid. Does not write to the error output and does
  * not alter the last-error state.
  */
-int BaseCfiExists(void *cfihandle, char *context);
+int BaseCfiExists(void *cfihandle, const char *context);
 
 /*
  * BaseCfiCount — count the direct children and/or attributes of a node.
@@ -236,7 +236,7 @@ int BaseCfiExists(void *cfihandle, char *context);
  * BASE_CFI_LOOK_ATTRIBUTE, or both OR'd together.
  * Returns the count on success, -1 on error.
  */
-int BaseCfiCount(void *cfihandle, char *context, int type);
+int BaseCfiCount(void *cfihandle, const char *context, int type);
 
 /*
  * BaseCfiCopy — deep-copy the subtree at src_ctx into dst at dst_ctx.
@@ -246,4 +246,4 @@ int BaseCfiCount(void *cfihandle, char *context, int type);
  * a name with attributes on src_ctx.
  * Returns BASE_CFI_OK on success, an error code otherwise.
  */
-int BaseCfiCopy(void *src, char *src_ctx, void *dst, char *dst_ctx);
+int BaseCfiCopy(void *src, const char *src_ctx, void *dst, const char *dst_ctx);