fkYAML

fkYAML is a C++ header-only YAML library.
If you want portability & development speed-up, fkYAML is the way to go.
No need to build a library only for a third party project.
You can add YAML support into your projects by just including header files where it's needed.

Table of contents

• Design goals
• Community Support
• How to use fkYAML
• How to test fkYAML
• Supported compilers
• License
• Used third-party tools

Design Goals

There are a lot of YAML libraries out there, and each may have its reason to exist.
fkYAML has been developed with these design goals:

:briefcase: Portable

The whole code 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-project, or no additional compiler flags are required.
Although fkYAML is a library with multiple header files by default, you can use the single-header version located in the single_include directory.
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.

:memo: Well Documented

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 fkYAML to handle YAML documents while creating a simple C++ project using CMake.
More detailed, exclusive descriptions with example usages for each fkYAML API are available in the API reference pages.

:mag: Heavily Tested

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 and CodeQL.
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 and C++ standards.
See the supported compilers section for more details.

Community Support

:question: Questions

If you have questions regarding the fkYAML library, feel free to open a Q&A discussion at GitHub.

:zap: Feature Requests

If you have feature requests for the fkYAML library, 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.

:bug: Bug Reports

If you encounter a 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 to this library to collabolate.

:closed_lock_with_key: Private Reports

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 [email protected].

How to use fkYAML

The documentation is available 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

How to test fkYAML

You can execute the unit tests with the following commands.
Make sure the CMake executable has been registered to your PATH.

$ cd path/to/fkYAML
$ cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug -DFK_YAML_BUILD_TEST=ON
$ cmake --build build --config Debug
$ ctest -C Debug --test-dir build --output-on-failure

Supported compilers

Currently, the following compilers are known to work and used in GitHub Actions workflows:

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 situation can be reproduced.

License

This project is distributed under the MIT License:

Copyright (c) 2023 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.

How to contribute

See the CONTRIBUTING.md file for detailed information.

Used third-party tools

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.
• 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.
• Catch2 as a unit-test 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.