Services and Tools

Encode Library

encode is a small non-GUI library layered directly on top of core. In this checkout it provides three things: Base64 helpers, a DBind-driven JSON reader/writer, and a lightweight URL parser used by higher layers such as inet.

Relevant Source Files

src/encode/CMakeLists.txt src/encode/encode.h src/encode/encode.c src/encode/base64.h src/encode/base64.c src/encode/json.h src/encode/json.c src/encode/url.h src/encode/url.c demo/htjson/htjson.c src/nappgui.h

Position In The Library Stack

The target declaration is nap_library(encode "core" ...), so encode is a first-class library, not a header-only helper. Its lifecycle mirrors the rest of the stack: encode_start() is reference-counted and, on the first user, calls core_start(); encode_finish() unwinds that relationship on the last user.

It is also outside the all-in-one nappgui.h umbrella. That header only includes osapp and gui, so projects that use Base64, JSON, or URL parsing include the encode headers explicitly.

Base64 Helpers

The Base64 surface is intentionally direct. It exposes raw size helpers, raw encode/decode functions, and convenience wrappers that accept a Stream, file path, raw byte block, String, or C string.

The implementation is in-memory rather than streaming. File and stream helpers read the full payload and then build either a NAppGUI String or Buffer. That keeps the API small and consistent with the rest of the core runtime, but it also means encode is aimed at modest data blobs rather than chunked transport pipelines.

JSON Is Driven By DBind Metadata

The JSON API is macro-fronted. Calls like json_read(stm, opts, Products) and json_write(stm, data, opts, Products) stringify the type name and pass it to the implementation, which resolves the type through the DBind registry.

In practice that means the parser and writer understand NAppGUI's runtime type model rather than a separate schema language. Primitive booleans, integers, reals, enums, strings, structs, binary values, and containers all flow through DBind. Unknown JSON object members are skipped instead of failing the whole parse, and optional diagnostics can be appended to JsonOpts.log with line and column information.

Typed Behavior Worth Knowing

  • Enums: JSON uses enum aliases, not raw integer ordinals, because writing goes through dbind_enum_alias(...).
  • Containers: array input maps onto DBind containers, with separate handling for pointer containers like ArrPt(...) versus value containers like ArrSt(...).
  • Binary fields: binary DBind values are represented as Base64 strings in JSON, reusing the same Base64 helpers from this library.
  • Nulls: string pointers, binary blobs, containers, and struct-pointer members can be cleared through DBind's null-setting hooks.
  • Output style: the writer produces compact JSON and appends a trailing NUL byte to the target stream, which matches the rest of the stream/string conventions in the project.

What The Demo Actually Proves

demo/htjson is the clearest source-backed walkthrough. It reads and writes primitive scalars, arrays, and DBind-registered structs, then demonstrates an Image case after starting draw2d. That matters because encode itself depends only on core; richer types become serializable only when their owning subsystem has registered the corresponding DBind metadata.

URL Parsing Is Lightweight And Structural

url_parse() scans a URL into scheme, optional user/password, host, optional numeric port, path, params, query, and fragment. url_resource() reconstructs the path-plus-suffix part that inet later passes to HTTP requests.

This is a simple splitter, not a full RFC-normalizing URL toolkit. There is no percent-decoding, no query-map abstraction, and no rich URL builder. If no explicit port is present, the parser leaves the value at UINT16_MAX; callers such as http_create() and http_secure() interpret that as the default 80 or 443.

Reading Order

Start with encode.c for lifecycle, then read base64.h/base64.c for the simple utility layer. After that, move to json.h/json.c together with demo/htjson/htjson.c, because the JSON subsystem makes most sense once you see the DBind-driven usage pattern. Finish with url.c if you need to understand how inet splits and reconstructs request URLs.

If you want repo-backed usage patterns rather than architecture, continue with Encode API Examples.