Skip to content
NOQTIS

nqdnew(3)

nqdnew, nqdparse, nqdload, nqdjson, nqdsave, nqdrfree, nqdlen, nqdat, nqdkey, nqdput, nqdset, nqddel, nqdsrc — make, read and change a data record

libnqd, -lnqd -lnoqtis

#include <nqd.h>

int
nqdnew(nqdrec **r);

int
nqdparse(const char *json, size_t n, nqdrec **r, char *why, size_t cap);

int
nqdload(const char *dir, nqdrec **r, char *why, size_t cap);

int
nqdjson(const nqdrec *r, char *out, size_t cap, size_t *outlen);

int
nqdsave(const nqdrec *r, const char *dir);

void
nqdrfree(nqdrec *r);

size_t
nqdlen(const nqdrec *r, const char *member);

int
nqdat(const nqdrec *r, const char *member, size_t i, char *out, size_t cap, size_t *outlen);

int
nqdkey(const nqdrec *r, const char *member, const char *key, char *out, size_t cap, size_t *outlen);

int
nqdput(nqdrec *r, const char *member, const char *json, size_t n, char *why, size_t cap);

int
nqdset(nqdrec *r, const char *member, const char *key, const char *field, const char *json, size_t n, char *why, size_t cap);

int
nqddel(nqdrec *r, const char *member, const char *key);

int
nqdsrc(nqdrec *r, const char *dir, const char *path, char *why, size_t cap);

A nqdrec holds a data record (noqtis-data(5)); its layout is private. Elements go in and out as JSON text, so every binding builds the same record: the library checks each one against the format and writes the whole in canonical form.

() makes a record that holds only its format. () reads n bytes of JSON text: every member must be one the format defines, of its type, every required member present, no key twice; arrays keyed by path or name are sorted here. () reads noqtis.data.json in dir, which must also be in canonical form. On failure, both write a sentence to why (cap bytes; it may be NULL) that names the member and says what is wrong, such as ‘sources[0].sha256: must be 64 lower-case hex digits’.

() writes the canonical JSON of the record to out (cap bytes, NUL added) and its length to *outlen, also when it returns NQEBUF for a cap too small: call it with out NULL to learn the size. () writes it to noqtis.data.json in dir, through a temporary file and a rename. () frees a record; NULL is fine.

The members are the arrays ‘sources’, ‘schemas’, ‘stats’, ‘chunks’, ‘steps’, ‘checks’, ‘commits’ and the objects ‘env’ and ‘cite’. () returns the number of elements of an array member, 1 or 0 for an object member, 0 for any other name. () writes element i (0 for an object member) as canonical JSON, as nqdjson() does. () does the same for the element of a keyed member with key (its path, or its name for ‘checks’). () adds an element: ‘sources’, ‘schemas’, ‘stats’ and ‘chunks’ are keyed by path and ‘checks’ by name, and an element with the same key is replaced; ‘steps’ and ‘commits’ are appended; ‘env’ and ‘cite’ are set. () sets one field of the element with key (NULL for ‘env’ and ‘cite’) to the JSON value json, or removes it when json is NULL; the element must still be valid after it. () removes the element with key, or the whole member when key is NULL.

() records the SHA-256 and size of the file path (relative to dir, ‘/’ between folders) in its ‘sources’ element, keeping the element's other fields, or adds the element.

NQOK on success; NQEDEC for JSON or an element the format does not allow (with why), NQELIM over 64 MiB or 32 levels, NQEBUF for an output buffer too small, NQEIO for a record, element or file that is not there or cannot be read or written, NQEARG for an unknown member, a key that cannot change (nqdset() of path or name) or a path a capsule cannot hold, NQEMEM when memory runs out.

#include <nqd.h>

nqdrec *r;
char why[256];
if (nqdnew(&r) == NQOK &&
    nqdsrc(r, "results", "data/a.csv", why, sizeof why) == NQOK &&
    nqdset(r, "sources", "data/a.csv", "url",
           "\"https://example.org/a.csv\"", 27, why, sizeof why) == NQOK)
  nqdsave(r, "results");
nqdrfree(r);

noqtis-data(1), nqdchk(3), noqtis-data(5)