fkYAML is a C++ header-only library to deserialize, serialize and build YAML documents.
It is also carefully desinged and tested to work with various compilers, C++ standards and platforms.
So, if you want portability & development speed-up, fkYAML is the way to go.
You can add YAML support into your projects by just including the header file(s).
This simple example deserializes a YAML string into a document, make simple modifications, and finally serializes the modified documentation to a YAML string.
#include <iostream>
#include <string>
#include <fkYAML/node.hpp>
int main() {
// 1. deserialize a YAML string into a document.
// The input can be other container types or their iterators.
// `deserialize` accepts `FILE*`, `std::istream` as well.
std::string yaml = R"(
project: fkYAML
required C++ version: 11
works on:
- Linux
- macOS
)";
auto node = fkyaml::node::deserialize(yaml);
// 2. Modify it.
// as_seq() returns a `std::vector<fkyaml::node>&` object.
node["maintainer"] = "fktn-k";
node.at("works on").as_seq().emplace_back("Windows");
// 3. serialize the modified document to a YAML string and save it.
std::ofstream ofs("out.yaml");
ofs << node;
// Contents of out.yaml
//
// maintainer: fktn-k
// project: fkYAML
// required C++ version: 11
// works on:
// - Linux
// - macOS
// - Windows
}- Design goals
- Features
- Test suite status
- Supported compilers
- Benchmarking
- Community Support
- Testing
- Contributing
- Used third party tools
- License
There are a lot of YAML libraries written in C/C++ out there, and each may have its reasons to exist.
fkYAML has been developed with these design goals:
The library depends only on C++ standards, and is carefully designed to work on many platforms so that fkYAML can be imported into existing C++ projects written in C++11 or better.
No external dependencies, no sub-projects, and no additional compiler flags are required.
Although fkYAML is a library with multiple header files by default, you can use the single-header version. You can further use fkyaml_fwd.hpp for forward declarations.
Furthermore, the project supports CMake and provides the documentation exclusively for CMake integration.
Those characteristics allow existing C++ project using CMake for builds to quickly incorporate YAML support with just a little effort.
The documentation provides plenty of information so that users can understand what fkYAML is and what they can achieve with fkYAML.
For instance, the tutorial pages show how you can read/write/customize using fkYAML to handle YAML documents while creating a simple C++ project using CMake.
Also, API reference pages provide more detailed, exclusive descriptions with example usages for each fkYAML API.
fkYAML has been unit-tested and its test suite covers 100% of lines and conditions of the codebase. (You can see the actual coverage here.)
We check with Valgrind and the Clang Sanitizers that there are no runtime issues such as memory leak.
Furthermore, the quality of our codebase has been checked with Clang-Tidy, CodeQL and Codacy.
GitHub Actions workflows run against every commit pushed on the main & develop branches to ensure that the fkYAML library can be successfully built/tested with a variety of compilers, operating systems and C++ standards.
See the supported compilers section for more details.
- General
- Cross-platforms
- Compilers: GCC, Clang, Visual Studio, etc.
- Operating systems: Linux, macOS, Windows.
- Easy integration
- Header-only library. Just copy the headers to your project. CMake packages are also available in the release page.
- Self-contained, minimal dependencies
- The C++ standard is the only dependency. No external dependencies, sub-projects or additional compiler flags are required.
- Cross-platforms
- YAML Standard Compliance (with the YAML specification v1.2.2)
- YAML syntax
- Support scalars, sequences, mappings in both block and flow styles.
- Sequences and mappings are accepted as mapping keys in de/serialization. Such a key can also be passed to query a mapping value like
operator[]orat. - Node values can be referenced by using
as_seqoras_map, or converted to arbitrary types byget_valueorget_value_inplace. - Empty mapping keys like
: valueor- : valueare NOT supported.
- Sequences and mappings are accepted as mapping keys in de/serialization. Such a key can also be passed to query a mapping value like
- Support
%TAGand%YAMLdirectives%YAMLdirectives have no effect and YAML 1.2 is always assumed.- Any unknown directives are just ignored during deserialization.
- Support tags, anchors and aliases
- Support de/serializing a single document by
deserializeandserialize. - Support de/serializing multiple documents in input stream as well by
deserialize_docsandserialize_docs.
- Support scalars, sequences, mappings in both block and flow styles.
- Encodings
- Support UTF-8, UTF-16 and UTF-32 encodings, including both little and big endians.
- Character types are
charfor all the above encodings,char8_t(since C++20) for UTF-8,char16_tfor UTF-16 andchar32_tfor UTF-32.
- Character types are
- Support automatic detection of encodings in input stream.
- The first character should be a BOM or an ASCII character as described in the specification.
- Otherwise, the UTF-8 encoding is assumed.
- Support encoding validation internally.
- A Byte Order Mark (BOM) at the beginning of input stream is automatically consumed during deserialization. Any BOMs at the other places are treated as contents.
- Support UTF-8, UTF-16 and UTF-32 encodings, including both little and big endians.
- Line break formats
- Support the Unix style
\nand the Windows style\r\nfor deserialization. - Serialization uses the Unix style
\n. No configuration is available for now.
- Support the Unix style
- YAML syntax
- Customization Points
- Node value types
- Scalars, sequences and mappings are all stored in
fkyaml::nodeobjects asboolfor booleans,int64_tfor integers,doublefor floating point values,std::stringfor strings,std::vector<fkyaml::basic_node>for sequences andstd::map<fkyaml::basic_node, fkyaml::basic_node>for mappings.
The types to use for storage are customizable to your needs by changing template parameter types offkyaml::basic_node.
- Scalars, sequences and mappings are all stored in
- Arbitrary type conversions
- fkYAML has a number of built-in conversion functions from/to
fkyaml::basic_nodefor a lot of STL container/scalar types.
You can implement your ownfrom_nodeandto_nodefunctions for types which are defined by your project or third party projects.
See the tutorial page for details.
- fkYAML has a number of built-in conversion functions from/to
- Node value types
- Miscellaneous
- fkyaml_fwd.hpp is available for forward declarations of fkYAML APIs so unnecessary definitions will not slow down compilation.
- Some features introduced in C++14 and better are available depending on the active C++ standard at compile time, for examples:
- Structured binding support for mappings.
- std::string_view for input stream.
- std::optional for conversions from node values.
More detailed descriptions are to be found on GitHub Pages.
Here is the list you might want to know:
- Tutorial - getting started
- CMake Integration - CMake integration with your project
- API references - all the details with examples
Compilers with complete C++11 support should compile the library without warnings.
Actually, fkYAML is compiled and tested with 40+ different C++ compilers with different operating systems and C++ standards in GitHub Actions workflows.
| Compiler | Operating System |
|---|---|
| AppleClang 14.0.0.14000029 | macOS 13 |
| AppleClang 14.0.3.14030022 | macOS 13 |
| AppleClang 15.0.0.15000040 | macOS 13 |
| AppleClang 15.0.0.15000040 | macOS 14 |
| AppleClang 15.0.0.15000100 | macOS 13 |
| AppleClang 15.0.0.15000100 | macOS 14 |
| AppleClang 15.0.0.15000309 | macOS 14 |
| AppleClang 16.0.0.16000026 | macOS 15 |
| Clang 3.4.2 | Ubuntu 22.04 |
| Clang 3.5.2 | Ubuntu 22.04 |
| Clang 3.6.2 | Ubuntu 22.04 |
| Clang 3.7.1 | Ubuntu 22.04 |
| Clang 3.8.1 | Ubuntu 22.04 |
| Clang 3.9.1 | Ubuntu 22.04 |
| Clang 4.0.1 | Ubuntu 22.04 |
| Clang 5.0.2 | Ubuntu 22.04 |
| Clang 6.0.1 | Ubuntu 22.04 |
| Clang 7.1.0 | Ubuntu 22.04 |
| Clang 9.0.1 | Ubuntu 22.04 |
| Clang 10.0.1 | Ubuntu 22.04 |
| Clang 11.1.0 | Ubuntu 22.04 |
| Clang 12.0.1 | Ubuntu 22.04 |
| Clang 13.0.1 | Ubuntu 22.04 |
| Clang 14.0.6 | Ubuntu 22.04 |
| Clang 15.0.7 | Ubuntu 22.04 |
| Clang 16.0.6 | Ubuntu 22.04 |
| Clang 17.0.6 | Ubuntu 22.04 |
| Clang 18.1.6 | Ubuntu 22.04 |
| Clang 19.1.4 | Ubuntu 22.04 |
| GCC 4.8.5 | Ubuntu 22.04 |
| GCC 5.3.1 | Ubuntu 22.04 |
| GCC 6.4.0 | Ubuntu 22.04 |
| GCC 7.5.0 | Ubuntu 22.04 |
| GCC 8.5.0 | Ubuntu 22.04 |
| GCC 9.5.0 | Ubuntu 22.04 |
| GCC 10.5.0 | Ubuntu 22.04 |
| GCC 11.4.0 | Ubuntu 22.04 |
| GCC 12.3.0 | Ubuntu 22.04 |
| GCC 13.3.0 | Ubuntu 22.04 |
| GCC 14.2.0 | Ubuntu 22.04 |
| IntelLLVM 2024.1.2 | Ubuntu 22.04 |
| MinGW-64 8.1.0 | Windows Server 2019 |
| MinGW-64 12.2.0 | Windows Server 2022 |
| Visual Studio 16 2019 | Windows Server 2019 |
| Visual Studio 17 2022 | Windows Server 2022 |
Requests for new compiler supports are welcome.
If you encounter a problem regarding compilers, please let us know by creating an issue or a PR with the information of your Operating System so that the same issue can be reproduced.
Testing of the library with the YAML test suite is currently a work in progress.
Though efficiency is not everything, speed and memory consumption are very important characteristics for C++ developers. Regarding speed, benchmarking scores are now available with the dedicated benchmarking tool for the parsing.
The following tables are created from the benchmarking results in the following environment:
- CPU: AMD Ryzen 7 5800H @3.20GHz
- OS: Ubuntu22.04 (WSL2)
- Compiler: g++11.4.0
Parsing ubuntu.yml
| Benchmark | processed bytes per second (Release) |
|---|---|
| fkYAML | 62.5049Mi/s |
| libfyaml | 39.235Mi/s |
| rapidyaml (with mutable buff) |
22.007Gi/s |
| rapidyaml (with immutable buff) |
133.311Mi/s |
| yaml-cpp | 9.07876Mi/s |
Parsing citm_catalog.json
| Benchmark | processed bytes per second (Release) |
|---|---|
| fkYAML | 97.216Mi/s |
| libfyaml | 57.3021Mi/s |
| rapidyaml (with mutable buff) |
37.9026Gi/s |
| rapidyaml (with immutable buff) |
140.375Mi/s |
| yaml-cpp | 14.3192Mi/s |
Parsing citm_catalog.yml
| Benchmark | processed bytes per second (Release) |
|---|---|
| fkYAML | 38.7563Mi/s |
| libfyaml | 24.7526Mi/s |
| rapidyaml (with mutable buff) |
37.9676Gi/s |
| rapidyaml (with immutable buff) |
68.4245Mi/s |
| yaml-cpp | 6.47003Mi/s |
Although rapidyaml is about 2x faster with immutable buffers and far faster with mutable buffers than fkYAML as it focuses on high performance, fkYAML is in general 70% faster than libfyaml and also about 6.5x faster than yaml-cpp.
Note that, since fkYAML deserializes scalars into native booleans or integers during the parsing, the performance could be more faster in some use cases since there is no need for string manipulations upon data queries.
If you have questions regarding the fkYAML library, feel free to open a Q&A discussion at GitHub.
If you find a way to improve fkYAML, let us know by opening an Ideas discussion.
It's really helpful for us if you describe what the new feature aims at and why it's needed.
If you encounter an issue or find a bug, open an issue.
Please describe your problem as detailed as possible, and also mention the version of the library you are using as well as the versions of your compiler and operating system.
Opening an issue at GitHub allows other users and contributors of this library to collabolate and helps us find a better way to resolve it.
If you want to make a private report (e.g., for a vulnerability or to attach an example that is not meant to be published), please send an email to fktn.dev@gmail.com.
You can execute the unit tests with the following commands.
Make sure a CMake executable path has been added to your PATH in advance.
$ cd path/to/fkYAML
$ cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug -DFK_YAML_BUILD_TEST=ON
$ cmake --build build
$ ctest -C Debug --test-dir build --output-on-failureSee the CONTRIBUTING.md file for detailed information.
The library itself depends only on C++ standards and licensed under the MIT licence. However, it is built, tested or documented with a lot of third-party tools and services. Thanks a lot!
- amalgamate.py - Amalgamate C source and header files to generate a single header file.
- Catch2 as a unit-test framework.
- Clang for compilation, coding style checks, and static/runtime analysis.
- CMake for automation of build & testing.
- Codacy for further code analysis.
- Coveralls to measure code coverage.
- Google Benchmark as a benchmarking framework.
- github-changelog-generator to generate the CHANGELOG.md file.
- include-what-you-use to check the fkYAML library source files are each self-contained.
- lcov to process coverage information and generate an HTML view.
- Material for MkDocs for the style of the documentation site.
- MkDocs as the documentation site generator.
- reuse-tool to generate license/copyright headers in source files to meet REUSE software recommendations.
- Valgrind for runtime memory leak check.
fkYAML is distributed under the MIT License:
Copyright (c) 2023-2025 Kensuke Fukutani
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.