AxlJson -- JSON
===============

JSON parser (JSMN-based) and builder (fixed buffer). Parse JSON strings into
a token tree, query values by path, and build JSON documents incrementally.

Header: ``<axl/axl-json.h>``

Overview
--------

AXL provides two JSON APIs:

- **Parser** -- parse a JSON string, extract values by key or iterate arrays
- **Builder** -- construct JSON in a caller-provided buffer with no dynamic allocation

Parsing JSON
~~~~~~~~~~~~

.. code-block:: c

   const char *json = "{\"name\":\"AXL\",\"version\":1,\"debug\":true}";
   AxlJsonCtx ctx;

   if (axl_json_parse(json, axl_strlen(json), &ctx)) {
       const char *name;
       size_t name_len;
       int64_t version;
       bool debug;

       axl_json_get_string(&ctx, "name", &name, &name_len);
       axl_json_get_int(&ctx, "version", &version);
       axl_json_get_bool(&ctx, "debug", &debug);

       axl_printf("name=%.*s version=%lld debug=%s\n",
                  (int)name_len, name, version,
                  debug ? "true" : "false");

       axl_json_free(&ctx);
   }

**Note**: String values returned by ``axl_json_get_string`` point into
the original JSON buffer (zero-copy). Do not free the original buffer
while using extracted strings.

Building JSON
~~~~~~~~~~~~~

The builder writes into a caller-provided buffer with no heap allocation.
Check ``overflow`` after building to detect truncation.

.. code-block:: c

   char buf[256];
   AxlJsonBuilder j;

   axl_json_init(&j, buf, sizeof(buf));
   axl_json_object_start(&j);
   axl_json_add_string(&j, "name", "AXL");
   axl_json_add_uint(&j, "version", 1);
   axl_json_add_bool(&j, "debug", true);
   axl_json_object_end(&j);
   axl_json_finish(&j);

   if (!j.overflow) {
       axl_printf("%s\n", buf);
       // {"name":"AXL","version":1,"debug":true}
   }

Iterating Arrays
~~~~~~~~~~~~~~~~

.. code-block:: c

   // Parse: {"items":["a","b","c"]}
   AxlJsonIter iter;
   if (axl_json_array_begin(&ctx, "items", &iter)) {
       AxlJsonElement elem;
       while (axl_json_array_next(&iter, &elem)) {
           axl_printf("  %.*s\n", (int)elem.len, elem.value);
       }
   }

API Reference
-------------

.. doxygenfile:: axl-json.h