Implement complete Boost.Yaml library with C++11 API, documentation, and CI

[Copilot]

This PR implements a complete C++11 library for parsing and working with YAML documents in the boost::yaml namespace, following the structure and patterns established by Boost.URL.

Overview

The library provides an idiomatic C++ interface for reading YAML files and accessing their structured contents. It supports YAML 1.2 core schema with both flow-style and block-style syntax.

Key Features

Core API

• Value types: value, scalar (string), sequence (vector), mapping (map), and null_t
• Type-safe access: is_null(), is_scalar(), is_sequence(), is_mapping() predicates and corresponding as_*() accessors
• YAML parsing: parse() function with system::result<value> return type for robust error handling
• Error handling: Custom error category integrated with Boost.System

Example Usage

#include <boost/yaml.hpp>

using namespace boost::yaml;

auto result = parse("name: John\nage: 30");
if(result)
{
    auto& map = result->as_mapping();
    std::cout << "Name: " << map["name"].as_scalar() << "\n";
    std::cout << "Age: " << map["age"].as_scalar() << "\n";
}

YAML Support

• ✅ Scalars (quoted and unquoted strings)
• ✅ Sequences (flow style [a, b, c] and block style with -)
• ✅ Mappings (flow style {key: value} and block style)
• ✅ Comments (# syntax)
• ✅ Null values
• ✅ Mixed flow and block styles

Build Systems

CMake

Full CMake support with:

• Standalone and Boost superproject builds
• Optional test and example building
• Dependency management (Boost.Assert, Config, Core, System, Variant2)
• Multi-platform support

B2 (Boost.Build)

Complete Jamfile configuration for library, tests, and examples.

Library Options

• Header-only: Include <boost/yaml/src.hpp> in one translation unit
• Compiled: Link against libboost_yaml

Testing

Comprehensive test suite with 46 assertions across 3 test files:

• value.cpp: Tests for value types and type safety
• parse.cpp: Tests for YAML parsing (scalars, sequences, mappings, comments)
• error.cpp: Tests for error handling and error messages

All tests use the test framework from Boost.URL (test_suite.hpp) for consistency.

Documentation

Antora Documentation

Complete documentation structure following Boost.URL:

• Introduction: Overview and quick examples
• Quick Start: Getting started guide with code examples
• Overview: Architecture and design principles
• Reference: Complete API documentation

API Documentation

All public APIs include comprehensive documentation comments describing:

• Purpose and behavior
• Parameters and return values
• Error conditions
• Usage examples

CI/CD

GitHub Actions workflow configured to test on:

• Platforms: Linux, Windows, macOS
• Compilers: GCC ≥4.8, Clang ≥3.8, MSVC ≥14.20, MinGW, Apple Clang
• Standards: C++11 and newer
• Analysis: ASan, UBSan, coverage reporting

Project Structure

yaml/
├── include/boost/yaml/          # Public headers
│   ├── yaml.hpp                 # Main header
│   ├── value.hpp               # Value types
│   ├── parse.hpp               # Parsing API
│   ├── error.hpp               # Error handling
│   └── impl/                   # Implementation details
├── src/src.cpp                 # Compiled library source
├── test/unit/                  # Unit tests
├── example/simple.cpp          # Example program
├── doc/                        # Antora documentation
├── extra/test_suite/          # Test framework
├── .github/workflows/ci.yml   # CI configuration
├── CMakeLists.txt             # CMake build
└── build.jam                  # B2 build

Dependencies

• Boost.Assert
• Boost.Config
• Boost.Core (for string_view)
• Boost.System (for error handling)
• Boost.Variant2 (for type-safe unions)

Testing Verification

All tests pass successfully:

boost.yaml.error:  0 failures, 6 total assertions
boost.yaml.parse:  0 failures, 21 total assertions
boost.yaml.value:  0 failures, 19 total assertions

Example program output:

Scalar: Hello, World!

Mapping:
  age: 30
  city: New York
  name: John

Sequence:
  - apple
  - banana
  - cherry

Flow-style YAML parsed successfully

Implementation Notes

• Parser implements a recursive descent approach for YAML 1.2 core schema
• Focus on simplicity and ease of use over comprehensive YAML spec coverage
• All code follows Boost Software License 1.0
• Structure mirrors Boost.URL for consistency with other Boost libraries

Closes #1

Original prompt

---

This section details on the original issue you should resolve

<issue_title>implement a complete Boost.Yaml library</issue_title>
<issue_description>Implement a complete C++ library which provides an API to read YAML files and access their structured contents using idiomatic C++11 in the namespace boost::yaml. Use https://github.com/boostorg/url sources as a guide for how to structure the include files, compiled source files, cmake files, Jamfiles, examples, tests, and documentation. Write the documentation using Antora, write the tests using the test_suite.hpp from URL, set up CI through GitHub Actions as in URL targeting all the same platforms, and make sure that every public API has documentation comment. No futher context is provided, good luck.
</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #1

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.