fktn-k/fkyaml

A C++ header-only YAML library

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
• Benchmarking
• 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:

💼 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.

📝 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.

🔍 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

❓ Questions

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

⚡ 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 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.

🔐 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

Benchmarking

Though experimental, benchmarking scores are now available with the dedicated benchmarking tool for the parsing.
On an AMD Ryzen 7 5800H @3.20GHz with g++11.4.0 in Ubuntu22.04 (WSL2), fkYAML parses the YAML source at a competitive speed compared against other existing YAML libraries for C/C++:

Benchmark	Release (MB/s)
fkYAML	40.491
libfyaml	31.110
rapidyaml (with mutable buff)	147.221
rapidyaml (with immutable buff)	144.904
yaml-cpp	7.397

Although rapidyaml is in general 4x faster than fkYAML as it focuses on high performance, fkYAML is 30% faster than libfyaml and also 5.4x 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 real use cases.

Supported compilers

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

Compiler	Operating System
AppleClang 13.0.0.13000029	macOS 12
AppleClang 13.1.6.13160021	macOS 12
AppleClang 14.0.0.14000029	macOS 12
AppleClang 14.0.0.14000029	macOS 13
AppleClang 14.0.3.14030022	macOS 13
AppleClang 14.0.3.14030022	macOS 14
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
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
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.1.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 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.
• 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's Issues

support clang format & clang tidy

add (static) assert checks

support YAML version derectives

add unit test cases for Exception class

added code coverage job on local & CI

add sanitizers to unit test app

add self-hosted runner

add CircleCI config file

fix GIT_TAG value for FetchContent_Declare

fix bug in iterator-based for-loops

Currently, fkYAML with MSVC debug build ends produces an infinite loop after running an iterator based for loop.
Expanded for loops do not seem to raise such an issue though.
The other compilers with the debug/release build does not produce such an issue.

run clang sanitizer test only on self-hosted runners

Output stream conversion of nodes lacks quoting/escape of string values

Description

While testing fkYAML, I noticed the output stream conversion of fkyaml::node string values lack quoting, which can change the YAML doc's semantics.

Example: a string value of "1" should be output with quoting or else it becomes an integral value in the output, which changes the semantics.

Reproduction steps

Parse and then output the following YAML doc:

Input doc:

stuff:
  - id: '1'
    name: Foo

fkYAML output representation (string scalar value becomes an integer)

stuff:
  -
    id: 1
    name: Foo

Expected vs. actual results

Expected: output representation retains semantic equality of input doc.
Actual: output representation changes semantic equality of input doc.

Minimal code example

std::ifstream ifs("test.yaml");
fkyaml::node root = fkyaml::node::deserialize(ifs);
std::cout << root << std::endl;

Error messages

No response

Compiler and operating system

Clang on MacOS 13.6

Library version

develop HEAD

Validation

• The bug also occurs if the latest version from the develop branch is used.
• I can successfully compile and run the unit tests.

support custom Node value data types

organize CMake scripts

add main_page.md for doxygen

support doxygen

add feature of checking key existence to BasicNode class

support include-what-you-use

support keeping insertion order for mapping nodes

add unit test cases for Deserializer class

Misc Parse Errors

Description

While evaluating fkYAML for a project, I ran into several different parse errors on relatively simple YAML structures.

Reproduction steps

Run a simple parse on the following yaml examples:

1_single_quote.yml:

stuff:
  - id: 'foo'
    name: Foo
    tags:
      - baz
    params:
      key: 1
  - id: 'bar'
    name: Bar

Error: libc++abi: terminating due to uncaught exception of type fkyaml::v0_2_0::exception: multi-line string tokens are unsupported.

Caused by single quoted string values.

2_single_item_in_sequence.yml

stuff:
  - id: "foo"
    name: Foo
    tags:
      - baz
    params:
      key: 1
  - id: "bar"
    name: Bar

Error: libc++abi: terminating due to uncaught exception of type fkyaml::v0_2_0::exception: The node value is not a sequence.

Caused by single item ("baz") in tags sequence. It looks like the parsing expects sequences to always have multiple elements.

3_reordered.yml

stuff:
  - id: "foo"
    name: Foo
    params:
      key: 1
    tags:
      - baz
  - id: "bar"
    name: Bar

No error but the parsed elements are wrong -- the "bar" item is parsed as another item in the tags sequence preceding it. Relates to the same issue shown in #2 above. Parsed structure:

stuff:
  -
    id: foo
    name: Foo
    params:
      key: 1
    tags:
      -
        baz: bar
        name: Bar
      - id

Expected vs. actual results

I expected each of these to parse correctly, but they all failed in different ways.

Minimal code example

No response

Error messages

No response

Compiler and operating system

clang on Mac 13.6

Library version

develop HEAD

Validation

• The bug also occurs if the latest version from the develop branch is used.
• I can successfully compile and run the unit tests.

add inline namespace for versioning

add feature of deserializing anchors/aliases in YAML docs

define error codes&messages

complete README.md

add test for various c++ versions

create blank project

creates issue templates

configure CI/CD

Cannot parse string which consists of numbers and multiple dots

Description

fkYAML throws an exception while parsing a string scalar which consists of numbers and multiple dots such as semantic versions.
This only occurs if such a scalar is not surrounded with single/double quotes.

Reproduction steps

Try parse the following:

semver: 1.2.3

Expected vs. actual results

Expected: No error.
Actual: An exception is thrown with the following message:

parse_error: Multiple decimal points found in a token. (at line 0, column 11)

Minimal code example

int main()
{
    using namespace fkyaml::literals::yaml_literals;
    fkyaml::node n = "semver: 1.2.3"_yaml;
    return 0;
}

Error messages

parse_error: Multiple decimal points found in a token. (at line 0, column 11)

Compiler and operating system

GCC 11.4.0 on Ubuntu 22.04 LTS

Library version

develop HEAD

Validation

• The bug also occurs if the latest version from the develop branch is used.
• I can successfully compile and run the unit tests.

resolve warnings when building on CI

implement deserialization feature for block style mapping/sequence nodes

add unit test cases for Iterater class

support clang-tidy on CI

regulate packaging workflow trigger events

change integer scalar data type to int64_t only

implement YAML node data structure

add_lacked_node_tests

disable clang-format & clang-tidy by default

add test apps to check if fkYAML library can be successfully used by other projects

add unit test cases for Node class

The result of parsing UTF-16 encoded input lacks the last character

Description

When UTF-16 encoded characters which do not end with a surrogate pair are passed for deserialization, the last character is not parsed.
While digging into the issue, it's turned out this is caused due to inadequate implementation of conversion from UTF-16 to UTF-8 which tries to take care of surrogate pairs.

Reproduction steps

Try parsing any UTF-16 encoded characters which do not end with a surrogate pair, like the following:

fkyaml::node n = fkyaml::node::deserialize(u"foo: bar");
std::cout << n << std::endl;

Expected vs. actual results

Expected output:

foo: bar

Actual output:

foo: ba

Minimal code example

The same as "Reproduction steps".

Error messages

No error messages.

Compiler and operating system

GCC 11.4.0 on Ubuntu 22.04 LTS

Library version

develop HEAD

Validation

• The bug also occurs if the latest version from the develop branch is used.
• I can successfully compile and run the unit tests.

introduce Catch2 v2 test framework

add unit test cases for LexicalAnalyzer class

add more documents

add compiler support for Windows/macOS

implement feature of serializing YAML documents

Parse errors on strings containing a single quote

Description

When parsing a scalar value that contains a ' character within it, fkYAML throws an exception.

Reproduction steps

Try parsing either of the following:

stuff:
  - id: foo
    name: "Bob's stuff"

stuff:
  - id: foo
    name: Bob's stuff

Both should be valid YAML, but the single quote throws off the parser: fkyaml::v0_2_1::exception: Invalid single quotation mark found in a string token.

Expected vs. actual results

Expected: Parse the name field as "Bob's stuff" string.
Actual: Exception thrown: fkyaml::v0_2_1::exception: Invalid single quotation mark found in a string token.

Minimal code example

No response

Error messages

No response

Compiler and operating system

Clang on MacOS 13.6

Library version

develop HEAD

Validation

• The bug also occurs if the latest version from the develop branch is used.
• I can successfully compile and run the unit tests.

implement feature of deserializing YAML documents

change source file newline codes to LF