{"id":24600791,"url":"https://github.com/pantoniou/libfyaml","last_synced_at":"2026-04-01T19:41:22.202Z","repository":{"id":35708789,"uuid":"208780361","full_name":"pantoniou/libfyaml","owner":"pantoniou","description":"Fully feature complete YAML parser and emitter, supporting the latest YAML spec and passing the full YAML testsuite.","archived":false,"fork":false,"pushed_at":"2026-03-20T11:44:26.000Z","size":13116,"stargazers_count":327,"open_issues_count":1,"forks_count":98,"subscribers_count":6,"default_branch":"master","last_synced_at":"2026-03-21T00:30:12.695Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pantoniou.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-09-16T11:13:33.000Z","updated_at":"2026-03-20T11:44:29.000Z","dependencies_parsed_at":"2024-07-12T15:35:15.303Z","dependency_job_id":"e734a6a2-005f-4bc1-9e3e-c2385a496b94","html_url":"https://github.com/pantoniou/libfyaml","commit_stats":{"total_commits":527,"total_committers":11,"mean_commits":47.90909090909091,"dds":"0.030360531309297945","last_synced_commit":"39f774503b4bd84ea595b5bd98e47a35736627b6"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"purl":"pkg:github/pantoniou/libfyaml","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pantoniou%2Flibfyaml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pantoniou%2Flibfyaml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pantoniou%2Flibfyaml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pantoniou%2Flibfyaml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pantoniou","download_url":"https://codeload.github.com/pantoniou/libfyaml/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pantoniou%2Flibfyaml/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291180,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-24T14:01:33.352Z","updated_at":"2026-04-01T19:41:22.194Z","avatar_url":"https://github.com/pantoniou.png","language":"C","funding_links":[],"categories":["Yaml","Recently Updated"],"sub_categories":["[Who Wants to Be a Millionare](https://www.boardgamecapital.com/who-wants-to-be-a-millionaire-rules.htm)"],"readme":"# libfyaml 1.0-alpha4\n\n[![Autotools CI](https://github.com/pantoniou/libfyaml/workflows/Standard%20Automake%20CI/badge.svg)](https://github.com/pantoniou/libfyaml/actions?query=workflow%3A%22Standard+Automake+CI%22)\n[![CMake CI](https://github.com/pantoniou/libfyaml/workflows/CMake%20CI/badge.svg)](https://github.com/pantoniou/libfyaml/actions?query=workflow%3A%22CMake+CI%22)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Language: C](https://img.shields.io/badge/language-C-brightgreen.svg)](https://en.wikipedia.org/wiki/C_(programming_language))\n\nlibfyaml is a high-performance YAML 1.2 and JSON parser/emitter with zero-copy\noperation, full document and event APIs, and the two major 1.0 alpha features:\n\n* generics: a schema-light, sum-type value model for YAML/JSON data in C\n* reflection/meta-type: typed YAML \u003c-\u003e C serdes driven by C type metadata\n\nThe alpha release adds a clear progression:\n\n* use the core API when you need parser, emitter, event, or document-tree control\n* use generics when your problem is \"work with values\"\n* use reflection when your problem is \"populate native C data structures\"\n\n## Why 1.0-alpha4 matters\n\n`1.0.0-alpha4` is the packaging repair follow-up to `1.0.0-alpha3`.\n\nIt keeps the same overall 1.0 direction, but fixes the Python release pipeline\nafter the `alpha3` wheel packaging problems:\n\n* `sdist` packaging now stages the full source tree correctly\n* Python packaging detects the staged source-tree root correctly during builds\n* the wheel matrix now includes `cp314`\n* the release is aimed at fixing the broken Python wheel / source-distribution flow from `alpha3`\n\n### Generic runtime\n\nThe center of the generic API is `fy_generic`.\n\n`fy_generic` is the sum-type value used to represent YAML and JSON data in C.\nIt carries one runtime value of one type: null, bool, int, float, string,\nsequence, mapping, or YAML-specific wrappers.\n\nIt is a single pointer-sized word with inline storage for common small values,\nincluding 61-bit signed integers on 64-bit builds, short strings, and inline\n32-bit floats.\n\nThe rest of the generic API is about working with `fy_generic` values:\n\n* creating `fy_generic` values from C literals or parsed input\n* reading typed values back out\n* transforming one `fy_generic` into another\n* controlling lifetime through stack-local values and builders\n\nThat gives C a Python-like data model:\n\n* scalars, sequences, and mappings as immutable tagged `fy_generic` values\n* construction via ``fy_value()``, ``fy_sequence()``, and ``fy_mapping()``\n* parse/emit helpers for YAML and JSON\n* functional collection operations such as map, filter, and reduce\n\nIf you know Python ``dict`` / ``list`` workflows, ``serde_json::Value``,\ntagged unions, or other sum-type/value-tree APIs, generics are the direct fit.\n\n### Reflection / meta-type\n\nThe reflection subsystem provides schema-driven typed serdes:\n\n* extract type metadata from annotated C headers\n* deserialize YAML directly into native C structs\n* emit native C structs back to YAML\n* inspect type and field metadata through the public reflection API\n* choose between direct libclang authoring or packed metadata blobs\n\nReflection is the typed layer for stable C data models.\n\n### Python binding\n\nThe Python binding in [`python-libfyaml/`](python-libfyaml/) is built on the\ngeneric runtime. It is a direct bridge into the C generics API:\n\n* Python ``FyGeneric`` lazy wrappers mirror C ``fy_generic`` values\n* the binding demonstrates dict/list/scalar usage over the same data model\n* users can move from Python prototypes to C without changing how they think\n  about the data\n\nSee the binding reference at\n[`python-libfyaml/docs/API.md`](python-libfyaml/docs/API.md).\n\n## Which layer should I use?\n\n### Core API\n\nChoose the core library when you need:\n\n* event-streaming parsing\n* YAML document tree access and mutation\n* path queries and document-building helpers\n* full control over emission details and original YAML structure\n\n### Generic API\n\nChoose generics when you need:\n\n* Python-like data handling in C\n* a schema-less or schema-light value layer\n* transformations over YAML/JSON values\n* a common model shared with the Python binding\n\n### Reflection API\n\nChoose reflection when you need:\n\n* direct YAML \u003c-\u003e C struct serdes\n* stable typed configuration objects\n* metadata-aware array/mapping handling\n* deployable packed schemas without runtime libclang dependency\n\n## Quick look\n\n### Generic literals in C\n\n```c\n#include \u003clibfyaml/libfyaml-generic.h\u003e\n\nfy_generic config = fy_mapping(\n    \"server\", fy_mapping(\n        \"host\", \"localhost\",\n        \"port\", 8080,\n        \"tls\",  true),\n    \"features\", fy_sequence(\"http\", \"metrics\", \"admin\"));\n```\n\n### Generic parse and transform\n\n```c\nfy_generic doc = fy_parse(\n    \"values: [1, 2, 3, 4]\",\n    FYOPPF_DISABLE_DIRECTORY | FYOPPF_INPUT_TYPE_STRING,\n    NULL);\n\nfy_generic values = fy_get(doc, \"values\", fy_invalid);\nfy_generic first = fy_first(values);\n```\n\n### Reflection-based typed parse\n\n```c\n#include \u003clibfyaml/libfyaml-reflection.h\u003e\n\nstruct fy_reflection *rfl = fy_reflection_from_c_file_with_cflags(\n    \"schema.h\", \"\", false, true, NULL);\n\nstruct fy_type_context_cfg cfg = {\n    .rfl = rfl,\n    .entry_type = \"struct app_config\",\n};\nstruct fy_type_context *ctx = fy_type_context_create(\u0026cfg);\n```\n\n## Documentation roadmap\n\nStart with these pages:\n\n* [`doc/generics-guide.rst`](doc/generics-guide.rst): value model, schemas, lifetimes\n* [`doc/reflection-guide.rst`](doc/reflection-guide.rst): typed serdes, libclang, packed blobs\n\nReference pages:\n\n* [`doc/libfyaml-core.rst`](doc/libfyaml-core.rst)\n* [`doc/libfyaml-generics.rst`](doc/libfyaml-generics.rst)\n* [`doc/libfyaml-reflection.rst`](doc/libfyaml-reflection.rst)\n\n## Examples\n\nThe refreshed examples directory now covers the new alpha workflows:\n\n* generic literals and Python-like object construction\n* generic parse/transform/reduce flows\n* generic lambda examples with captured local variables\n* generic serial and parallel lambda-based filter/map/reduce flows with an\n  explicit thread pool and configurable workload size\n* schema-sensitive generic round-trips\n* a Python-binding-to-C adoption bridge\n* reflection from libclang-processed headers\n* reflection export to packed blobs and runtime load from packed metadata\n\nSee [`examples/README.md`](examples/README.md) for the full list.\n\n## Existing strengths still apply\n\nlibfyaml also remains:\n\n* a full YAML 1.2 and JSON parser/emitter\n* zero-copy in core parsing paths\n* free of artificial key/document size limits\n* strong on diagnostics and document manipulation\n* fully MIT licensed\n\n## Installation\n\n### Using CMake\n\n```cmake\nfind_package(libfyaml 1.0 REQUIRED)\ntarget_link_libraries(your_app PRIVATE libfyaml::libfyaml)\n```\n\nIf the installed package was built with libclang support, the CMake package also\nexports ``libfyaml_HAS_LIBCLANG``.\n\n### Using pkg-config\n\n```bash\npkg-config --cflags libfyaml\npkg-config --libs libfyaml\n```\n\n### Building from source\n\nUsing CMake:\n\n```bash\nmkdir build \u0026\u0026 cd build\ncmake ..\ncmake --build .\nctest --progress -j\"$(nproc)\"\n```\n\nUsing Autotools:\n\n```bash\n./bootstrap.sh\n./configure\nmake\nmake check\n```\n\n### Optional dependencies\n\n* `llvm-dev libclang-dev`: author reflection metadata directly from C headers\n* no runtime libclang is required when using packed reflection blobs\n\n### Documentation builds\n\nSphinx documentation targets require the Python documentation toolchain:\n\n* `sphinx`\n* `sphinx_rtd_theme`\n* `sphinx-markdown-builder`\n* `linuxdoc`\n\nPDF documentation also requires a LaTeX toolchain with:\n\n* `latexmk`\n* `pdflatex`\n* `xcolor.sty`\n* `wrapfig.sty`\n\nOn Debian/Ubuntu, the practical package set is:\n\n```bash\npython3 -m pip install sphinx sphinx_rtd_theme sphinx-markdown-builder linuxdoc\nsudo apt-get install latexmk tex-gyre texlive-fonts-recommended texlive-latex-base texlive-latex-recommended texlive-latex-extra\n```\n\nThen build the docs with:\n\n```bash\ncmake --build build --target doc-html\ncmake --build build --target doc-latexpdf\n```\n\n## Python binding\n\nThe binding lives in [`python-libfyaml/`](python-libfyaml/). Run its tests with:\n\n```bash\ncd python-libfyaml\npython3 -m pytest tests/\n```\n\nThe binding is part of the alpha release story and shows the generic runtime's\ndata model in regular use. `v1.0.0-alpha3` improved the Windows story for the\nbinding, and `v1.0.0-alpha4` fixes the follow-on wheel and `sdist` packaging\nproblems from that release.\n\n## License\n\nlibfyaml is fully MIT licensed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpantoniou%2Flibfyaml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpantoniou%2Flibfyaml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpantoniou%2Flibfyaml/lists"}