fkYAML

The serialize function follows specific structural rules for different node types:

Scalars

{[anchor] [tag] value | alias}

Sequences

As a sequence value:

<scalar>: [anchor] [tag]
  - <sequence scalar value>
  - [anchor] [tag]
    - <child sequence value>

Note: 2 spaces are inserted before - indicators.

As an explicit key node:

? - <sequence value>
  - <another sequence value>
: <scalar>

Mappings

Value is a scalar: <scalar>: <scalar>

Value is a container (mapping or sequence):

<scalar>: [anchor] [tag]
  <mapping scalar key>: <mapping scalar value>
  <mapping scalar key>: [anchor] [tag]
    <child mapping scalar key>: <child mapping scalar value>

Note: 2 spaces are inserted before the value to indicate indentation.

As an explicit key node:

? <mapping>
: <scalar>

What is fkyaml::ordered_map?

fkyaml::ordered_map is a minimal map-like container that preserves the order of insertion. It inherits from std::vector<std::pair<Key, Value>>.

When to use it

In YAML, mapping nodes are technically defined as unordered sets of key-value pairs. However, when working with YAML deserialization, you often need to preserve the original order of keys to ensure that re-serializing the data produces a file that matches the input.

Using ordered_map allows you to:

1. Maintain the exact sequence of keys as they appeared in the YAML source.
2. Avoid the overhead and complexity of representing mappings as sequences of key-value pairs at the application layer.
3. Ensure consistent serialization behavior.

You can extend fkyaml to support your own custom types by implementing a (partial) specialization of the to_node() function. This allows basic_node to accept your custom objects during construction or assignment.

Critical Requirement: The specialization must be implemented in the same namespace as your user-defined type. This ensures that the specialization is correctly located via Argument-Dependent Lookup (ADL).

Implementation Pattern

1. Define your custom type in a namespace.
2. Implement the to_node specialization within that same namespace.

You can extend from_node to support your own custom types by implementing a (partial) specialization of the ::fkyaml::from_node() function.

Critical Implementation Rule: To ensure the specialization is found via Argument Dependent Lookup (ADL), you must implement the specialization in the same namespace as your user-defined type (or in the global namespace if the type is global).

You can specialize serialization and deserialization for your own custom types by using from_node() and to_node().

Requirements:

• User-defined types must be default-constructible to use these specializations.
• STL types (like std::vector or std::string) are already supported by default and do not require manual specialization.

When extracting data from a fkyaml::basic_node, choose the method based on your performance and type requirements:

• get_value<T>(): Use when you want a copy of the value in a standard C++ type (e.g., int, std::string, std::vector).
• get_value_inplace<T>(): Use when you need to convert into a C-style array or want to avoid unnecessary copies by writing directly into existing memory.
• as_seq(), as_map(), as_bool(), as_int(), as_float(), as_str(): Use these specialized methods if you want to avoid the overhead of template instantiation or if you need to access the underlying node structure/address directly rather than a copy.

fkYAML is a header-only library, making integration straightforward. You can incorporate it by simply including the header files in your project.

Options for integration:

• Standard Header-only: Copy the headers to your project and include them.
• Single-header version: Use the single-header file located at single_include/fkYAML/node.hpp for even simpler setup.
• Forward Declarations: Use fkyaml_fwd.hpp to provide forward declarations of the APIs, which helps reduce compilation times by avoiding unnecessary full definitions in header files.
• CMake: The project supports CMake and provides specific documentation for CMake integration.

To ensure that the order in which key-value pairs are inserted is maintained (overriding the default std::map behavior), define a node type using fkyaml::ordered_map as the second template parameter of fkyaml::basic_node.

#include <fkYAML/node.hpp>

// Define a node that preserves insertion order
using ordered_node = fkyaml::basic_node<std::vector, fkyaml::ordered_map>;

To install fkYAML on your system, clone the repository and use CMake to configure and install it. You can optionally specify a custom installation path or choose to install the single-header version.

Default Installation Paths:

• UNIX: /usr/local
• Windows: C:\Program Files\fkYAML

Options:

• -DCMAKE_INSTALL_PREFIX=<path-to-install>: Overrides the default installation path.
• -DFK_YAML_USE_SINGLE_HEADER=ON: Installs the single-header version of fkYAML.

$ cd /path/to/fkYAML
$ cmake -B build -S . [-DCMAKE_INSTALL_PREFIX=<path-to-install>] [-DFK_YAML_USE_SINGLE_HEADER=ON]
$ cmake --build build --target install