AxlConfig -- Configuration
==========================

Unified configuration framework. Declare options once in a descriptor
table, populate from command-line args or programmatic set calls, and
retrieve with typed getters. Supports auto-apply via ``offsetof``,
callbacks for custom logic, and parent inheritance for cascading defaults.

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

Overview
--------

AxlConfig replaces ad-hoc key-value parsing with a declarative system.
You define a table of option descriptors (name, type, default value),
then set values from any source. Type validation happens automatically.

Defining Options
~~~~~~~~~~~~~~~~

.. code-block:: c

   #include <axl.h>

   typedef struct {
       size_t  port;
       bool    verbose;
       size_t  max_connections;
   } ServerConfig;

   static const AxlConfigDesc opts[] = {
       { "port",     AXL_CFG_UINT, "8080", 0, "Listen port",
         offsetof(ServerConfig, port), sizeof(size_t) },
       { "verbose",  AXL_CFG_BOOL, "false", 0, "Verbose output",
         offsetof(ServerConfig, verbose), sizeof(bool) },
       { "max.conn", AXL_CFG_UINT, "16", 0, "Max connections",
         offsetof(ServerConfig, max_connections), sizeof(size_t) },
       { 0 }
   };

Creating and Querying
~~~~~~~~~~~~~~~~~~~~~

.. code-block:: c

   ServerConfig sc;
   AXL_AUTOPTR(AxlConfig) cfg = axl_config_new(opts);

   // Set the auto-apply target -- values are written directly
   // into the struct fields via offsetof
   axl_config_set_target(cfg, &sc);

   // Set values (type-validated)
   axl_config_set(cfg, "port", "9090");       // sc.port = 9090
   axl_config_set(cfg, "verbose", "true");    // sc.verbose = true

   // Query values
   size_t port = axl_config_get_uint(cfg, "port");
   const char *port_str = axl_config_get(cfg, "port");  // "9090"

Command-Line Integration
~~~~~~~~~~~~~~~~~~~~~~~~~

Parse ``-p 8080 --verbose`` directly into the config:

.. code-block:: c

   static const AxlOpt cli_opts[] = {
       { 'p', "--port",    AXL_OPT_VALUE, "PORT", "Listen port" },
       { 'v', "--verbose", AXL_OPT_FLAG,  NULL,   "Verbose" },
       { 0 }
   };

   // axl_config_parse_args maps short/long flags to config keys
   axl_config_parse_args(cfg, argc, argv, cli_opts);

Multi-Value Options
~~~~~~~~~~~~~~~~~~~

For options that can be specified multiple times (e.g., ``-H "Name: Value"``):

.. code-block:: c

   size_t count = axl_config_get_multi_count(cfg, "headers");
   for (size_t i = 0; i < count; i++) {
       const char *hdr = axl_config_get_multi(cfg, "headers", i);
       axl_printf("  header: %s\n", hdr);
   }

Parent Inheritance
~~~~~~~~~~~~~~~~~~

Create a child config that inherits defaults from a parent:

.. code-block:: c

   AxlConfig *defaults = axl_config_new(opts);
   axl_config_set(defaults, "port", "8080");

   AxlConfig *override = axl_config_new_with_parent(opts, defaults);
   // override inherits "port"="8080" until explicitly set

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

.. doxygenfile:: axl-config.h