yo-c

C and C++ developer kit for yo, an embedded multi-model database that lives in one .yo file.

Status

Nothing to use yet, and unlike the other bindings there is no placeholder package to install either.

C has no package registry, so there is no name to reserve and nothing to publish early. The library ships as libyo and libyo-dev through apt and dnf, and through CMake, pkg-config, vcpkg and Conan, none of which can be claimed ahead of having something to put in them.

The engine is at M0. The record plane and the file format are M1 and in progress. Watch the milestones.

What is here and what is not

The raw ABI is not here. yo.h, the yo_* symbols and the YO_ERR_* codes live in tamnd/yo with the engine, because they are frozen alongside it.

This repository is the layer above: the idiom, the examples and the packaging. It compiles against the frozen ABI and never against engine internals, which is the whole reason it is a separate repository. If it needed to see inside the engine, the ABI would not be doing its job.

The library keeps the short name. It is libyo, the header is yo.h, the symbols are yo_* and the pkg-config file is yo.pc. Only the command line tool is yodb, because the collision that rename fixes is a PATH collision with Yeoman, and a Node command line tool ships no header.

What this will be

#include <stdio.h>
#include <yo.h>

int main(void) {
  yo_error err = { .size = sizeof(yo_error) };
  yo_db *db = yo_open("app.yo", NULL, &err);
  if (!db) { fprintf(stderr, "%s\n%s\n", err.message, err.detail ? err.detail : ""); return 1; }

  yo_arena *a = yo_arena_new(db);
  yo_coll *kv = yo_kv_open(db, "users", &err);
  yo_kv_put(kv, YO_STR("ada"), YO_STR("99.5"), &err);

  yo_slice v;
  if (yo_kv_get(kv, YO_STR("ada"), &v, &err))
    printf("%.*s\n", (int)v.len, v.ptr);

  yo_arena_free(a);
  yo_coll_close(kv);
  yo_close(db);
  return 0;
}

The quickstart uses the key value surface rather than the document surface, deliberately. C has no generics, so a document API in C is a field index API: real, complete, and not a first page. The document path is the second page and the size budget accounts for the difference honestly rather than showing you a shorter program than the language can write.

Planned, on top of the raw ABI:

• YO_STR("x") and YO_BYTES(p, n) slice constructors.
• YO_TRY and YO_CHECK, which propagate a yo_error without a hand-written if (!x) return on every line, for those who want them.
• yo-gen, a small generator that reads an annotated struct and emits the shape description, the tag, the field index constants and the pack and unpack functions, because C has no reflection and cannot compute them.
• Cleanup attributes where the compiler has them, so defer-like scoping is available on gcc and clang, marked clearly as non-portable and shown alongside the explicit close form.
• A compilable example per feature area, all of them built in CI with -Wall -Wextra -Wpedantic -Werror.

C++ is tier 2 and lives in this same repository as a header-only wrapper over the same ABI.

Design

The full C, C++ and tier-3 specification is dx/09 in the project specification, and the ABI itself is dx/02.

Licence

Apache 2.0 or MIT, at your option.