libnwcore INI parser/writer plan

This document records the planned shared INI reader/writer layer for mars-nwe. It is a design note; the runtime implementation is not present yet.

Goals

mars-nwe needs one robust INI implementation that can be used by both server processes and interactive tools. It must not be a private helper inside the future TUI or translation layer.

The same project API should support:

legacy nw.ini compatibility readers;
future named configuration sections such as [transport.ipx] and [logging.process.nwconn];
nwsetup generated configuration files;
nwtoolbox applets that edit configuration interactively;
nwi18n catalog files if the catalog format stays INI-like;
safe read-modify-write operations that preserve administrator-friendly files well enough to avoid turning configuration into an opaque dump.

Layering

The INI API belongs in libnwcore, not in nwtui or an individual tool:

include/core/ini.h         public mars-nwe core INI API
src/core/ini.c             project-owned wrapper and policy over iniParser

Server code, nwtoolbox, nwsetup, nwfiler, nwsalvage and nwi18n should call only the mars-nwe nw_ini_* API. They must not call the vendored backend directly. This keeps the backend replaceable and keeps configuration semantics centralized.

Candidate backend

iniParser is the selected first backend. It is small C code, MIT licensed, can read and write INI files, and is pinned as third_party/iniparser at release tag v4.2.6 (4bef811283e0ec1658c60e09950bd5a1ddc92e4b).

The public contract remains the mars-nwe nw_ini_* API in libnwcore. Server code and tools must not include iniparser.h directly. minIni remains only a technical reference because the uploaded source is Apache-2.0 and is not a GPL-2.0-only core target. inih remains parser-only and is not enough for nwsetup, because setup and toolbox applets must be able to update INI files.

Project API shape

The first public API should stay small and boring:

int nw_ini_load_file(NwIniFile *ini, const char *path);
const char *nw_ini_get_string(NwIniFile *ini,
                              const char *section,
                              const char *key,
                              const char *fallback);
int nw_ini_get_bool(NwIniFile *ini,
                    const char *section,
                    const char *key,
                    int fallback);
uint32_t nw_ini_get_u32(NwIniFile *ini,
                        const char *section,
                        const char *key,
                        uint32_t fallback);
int nw_ini_set_string(NwIniFile *ini,
                      const char *section,
                      const char *key,
                      const char *value);
int nw_ini_delete_key(NwIniFile *ini, const char *section, const char *key);
int nw_ini_save_file(NwIniFile *ini, const char *path);
void nw_ini_free(NwIniFile *ini);

Exact names can follow existing mars-nwe style when implemented, but the capability set should cover read, update, delete and save.

Writer rules

The writer must be good enough for administrator-facing configuration:

preserve section/key ordering when possible;
preserve comments around untouched entries when the backend makes that feasible;
write known generated blocks in a stable order;
save through a temporary file plus rename when practical;
avoid rewriting a hand-edited configuration into a minimal key/value dump;
report parse/write errors through the future nwlog facade, not direct backend prints.

If the backend cannot preserve all comments, generated files must still remain readable and documented. The project wrapper owns that policy, not individual callers.

Legacy compatibility

The old numeric nw.ini format remains supported. The new core API should make it possible to expose named sections without breaking the old path. Compatibility adapters may translate old numeric entries such as 100..106 logging levels into new named process-level fields while still accepting old files.

Relationship to nwi18n

nwi18n may use the core INI API to load translation catalogs, but nwi18n is not the owner of the parser. The dependency direction is:

libnwcore INI -> nwi18n -> nwtui -> nwtoolbox applets

Production daemons may use the core INI API without pulling in nwi18n, nwtui or the toolbox stack.

4.3 KiB Raw Blame History