libfyaml README

The project's README from github.com/pantoniou/libfyaml. As one markdown file: README.md.

libfyaml 1.0-beta2

Autotools CI CMake CI License: MIT Language: C

libfyaml is a high-performance YAML 1.2 and JSON parser/emitter with zero-copy operation, full document and event APIs, and the two major 1.0 features:

The 1.0 series adds a clear progression:

Why 1.0-beta2 matters

1.0.0-beta2 is a correctness and portability release. It adds no new API.

The linker interface version moves to 8:1:6: the interfaces are unchanged.

Generic runtime

The center of the generic API is fy_generic.

fy_generic is the sum-type value used to represent YAML and JSON data in C. It carries one runtime value of one type: null, bool, int, float, string, sequence, mapping, or YAML-specific wrappers.

It is a single pointer-sized word with inline storage for common small values, including 61-bit signed integers on 64-bit builds, short strings, and inline 32-bit floats.

The rest of the generic API is about working with fy_generic values:

That gives C a Python-like data model:

If you know Python dict / list workflows, serde_json::Value, tagged unions, or other sum-type/value-tree APIs, generics are the direct fit.

Reflection / meta-type

The reflection subsystem provides schema-driven typed serdes:

Reflection is the typed layer for stable C data models.

Python binding

The Python binding in python-libfyaml/ is built on the generic runtime. It is a direct bridge into the C generics API:

See the binding reference at python-libfyaml/docs/API.md.

Which layer should I use?

Core API

Choose the core library when you need:

Generic API

Choose generics when you need:

Reflection API

Choose reflection when you need:

Quick look

Generic literals in C

#include <libfyaml/libfyaml-generic.h>

fy_generic config = fy_mapping(
    "server", fy_mapping(
        "host", "localhost",
        "port", 8080,
        "tls",  true),
    "features", fy_sequence("http", "metrics", "admin"));

Generic parse and transform

fy_generic doc = fy_parse(
    "values: [1, 2, 3, 4]",
    FYOPPF_DISABLE_DIRECTORY | FYOPPF_INPUT_TYPE_STRING,
    NULL);

fy_generic values = fy_get(doc, "values", fy_invalid);
fy_generic first = fy_first(values);

Reflection-based typed parse

#include <libfyaml/libfyaml-reflection.h>

struct fy_reflection *rfl = fy_reflection_from_c_file_with_cflags(
    "schema.h", "", false, true, NULL);

struct fy_type_context_cfg cfg = {
    .rfl = rfl,
    .entry_type = "struct app_config",
};
struct fy_type_context *ctx = fy_type_context_create(&cfg);

Documentation roadmap

Start with these pages:

Reference pages:

Examples

The refreshed examples directory now covers the new alpha workflows:

See examples/README.md for the full list.

Existing strengths still apply

libfyaml also remains:

Supported platforms

libfyaml is built and tested on these platforms:

Platform Versions Architectures Compilers
Linux (Ubuntu) 22.04, 24.04, 26.04 x86-64, arm64 gcc, clang
Linux (other distributions) Debian stable and testing, Fedora, Arch, Rocky Linux 9, Alpine (musl), Nix x86-64 gcc
Linux (other architectures) Ubuntu / Debian i386, armv7, riscv64, ppc64 (big-endian) gcc
macOS 15, 26 arm64 Apple clang, gcc
Windows Server 2022, Server 2025, 11 x64, arm64, x86 (Win32) MSVC, clang, MinGW-w64 gcc
FreeBSD 15.1 x86-64 clang
NetBSD 11.0 x86-64 gcc
OpenBSD 7.9 x86-64 clang
illumos (OmniOS) r151058 x86-64 gcc

Pushes and pull requests build a subset of these. The full CMake matrix, including ASAN builds on Linux and macOS, runs daily, and every platform above runs weekly.

Some features depend on the platform:

Installation

Using CMake

find_package(libfyaml 1.0 REQUIRED)
target_link_libraries(your_app PRIVATE libfyaml::libfyaml)

If the installed package was built with libclang support, the CMake package also exports libfyaml_HAS_LIBCLANG.

Using pkg-config

pkg-config --cflags libfyaml
pkg-config --libs libfyaml

Building from source

Using CMake:

mkdir build && cd build
cmake ..
cmake --build .
ctest --progress -j"$(nproc)"

Using Autotools:

./bootstrap.sh
./configure
make
make check

Optional dependencies

Documentation builds

Sphinx documentation targets require the Python documentation toolchain:

PDF documentation also requires a LaTeX toolchain with:

On Debian/Ubuntu, the practical package set is:

python3 -m pip install sphinx sphinx_rtd_theme sphinx-markdown-builder linuxdoc
sudo apt-get install latexmk tex-gyre texlive-fonts-recommended texlive-latex-base texlive-latex-recommended texlive-latex-extra

Then build the docs with:

cmake --build build --target doc-html
cmake --build build --target doc-latexpdf

Python binding

The binding lives in python-libfyaml/. Run its tests with:

cd python-libfyaml
python3 -m pytest tests/

The binding is part of the 1.0 release story and shows the generic runtime's data model in regular use. v1.0.0-alpha3 improved the Windows story for the binding, v1.0.0-alpha4 repaired the wheel and sdist packaging flow, v1.0.0-alpha5 broadened build and CI coverage, and v1.0.0-alpha6 expands generic formatting/document handling. v1.0.0-alpha7 adds transparent parse caching, optimized generic emission, and Stable ABI Python wheels. v1.0.0-alpha8 adds durable storage, auto-anchor emission, stronger comment round-tripping, and more complete generic helper APIs. v1.0.0-beta1 starts the beta cycle with additional conversion, predicate, iteration, formatting, and correctness fixes on top of that alpha surface. v1.0.0-beta2 fixes the fuzzing reports and extends the supported platforms.

License

libfyaml is fully MIT licensed.

libfyaml (pantoniou/libfyaml)

Searching Database…

346 ·GitHub
Libfyaml
What is this?libfyaml is a high-performance YAML 1.2 and JSON parser/emitter for C, built for zero-copy operation with full document-tree and event-streaming APIs, and it passes the full YAML testsuite.
Is this a library I link into my code, or a standalone CLI tool?It is a C library you link into your own program; it also ships a Python binding built on top of its generic runtime, but there is no standalone CLI tool described.
How do I add libfyaml to my project?Build it from source using CMake, pkg-config, or Autotools, then link the resulting library into your C project.
Do I need libclang to use the reflection API?Only if you want to author reflection metadata directly from annotated C headers; if you use packed reflection blobs instead, no runtime libclang dependency is needed.
Are all features available on every platform?The generic subsystem (and therefore the Python bindings) needs GCC or Clang statement expressions on a little-endian target, so it does not work with MSVC or on big-endian platforms, and durable-arena garbage collection only works on Linux and macOS.
Which operating systems and architectures are actually tested?It is built and tested on Linux (x86-64, arm64, plus i386/armv7/riscv64/ppc64), macOS (arm64), Windows (x64, arm64, x86), FreeBSD, NetBSD, OpenBSD, and illumos.
What's the difference between the core, generics, and reflection APIs?Core API gives you low-level parser/emitter/event/document-tree control; the generics API lets you work with YAML/JSON as Python-like dict/list/scalar values via the fygeneric sum-type; reflection lets you deserialize YAML directly into (and emit from) typed native C structs using metadata.
What is fygeneric?fygeneric is a single pointer-sized sum-type value used to represent any YAML or JSON data in C: null, bool, int, float, string, sequence, or mapping, with inline storage for small values like 61-bit integers and short strings.
Why does the 1.0-beta2 release matter?It's a correctness and portability release with no new API: it fixes dozens of fuzzing-reported bugs (memory leaks, double frees, use-after-free, unbounded recursion) and extends tested support to FreeBSD, NetBSD, OpenBSD, illumos, MinGW-w64, and more architectures.
Can I serialize/deserialize directly into my own C structs?Yes, the reflection API extracts type metadata from annotated C headers (via libclang or packed metadata blobs) and uses it to deserialize YAML straight into native C structs and emit structs back to YAML.
What are similar projects?simdjson, cJSON, flatbuffers, protobuf.js, rapidjson, vis, cosmopolitan, coost
Which topics is it in?zero-copy, clang, risc-v, openbsd, metadata, fuzzing, serialization, nix, schema, x86, parser, freebsd
Creator
pantoniou
Size
16.4 MB
Stars
346
Updated
CommitOct 16Releasev1.0.0-beta2Sep 25
Age
7y
Commits · 90 Days