toml++ para C++: guía completa con ejemplos prácticos

1. ¿Qué es y para qué sirve?

TOML (Tom's Obvious Minimal Language) es un formato de archivos de configuración creado como alternativa a INI, YAML y JSON. Está diseñado para ser máximamente legible para humanos, mapearse sin ambigüedades en tablas hash y ser sencillo de analizar. A diferencia de YAML, TOML no permite ambigüedades (como con sangrías o tipos de datos), y a diferencia de JSON, no requiere comillas para las claves y admite comentarios.

toml++ (también conocido como tomlplusplus) es una biblioteca moderna, header-only (solo cabeceras) para analizar y generar archivos TOML en C++17 y superior. No requiere compilación: simplemente incluyes el archivo de cabecera y obtienes toda la funcionalidad. Esto la convierte en la opción ideal para proyectos donde importan la facilidad de integración, el rendimiento y el tipado estricto.

¿Por qué usar toml++? Primero, ofrece soporte completo de la especificación TOML v1.0, incluyendo tablas inline, arrays de tablas, fechas, horas y fechas locales. Segundo, está escrita con énfasis en la seguridad de tipos: obtienes valores fuertemente tipados (std::string, int64_t, double, bool, toml::date, etc.) en lugar de un objeto JSON genérico. Tercero, es increíblemente rápida y tiene dependencias mínimas (solo la biblioteca estándar de C++17).

2. Instalación

toml++ es una biblioteca header-only. Esto significa que no necesitas compilarla por separado. Basta con copiar los archivos de cabecera a tu proyecto e incluirlos.

Método 1: Vcpkg (recomendado para Windows y Linux)

# Instalación mediante vcpkg
vcpkg install tomlplusplus

# Inclusión en CMakeLists.txt
find_package(tomlplusplus CONFIG REQUIRED)
target_link_libraries(mi_proyecto PRIVATE tomlplusplus::tomlplusplus)

Método 2: Conan

# Instalación mediante Conan
conan install tomlplusplus/3.4.0@

# En conanfile.txt
[requires]
tomlplusplus/3.4.0

[generators]
CMakeDeps

Método 3: Instalación manual (la más sencilla)

# Descarga la última versión desde GitHub
wget https://github.com/marzer/tomlplusplus/archive/refs/tags/v3.4.0.tar.gz
tar -xzf v3.4.0.tar.gz

# Copia la carpeta include/toml++ a tu proyecto
cp -r tomlplusplus-3.4.0/include/toml++ /ruta/a/tu/proyecto/include/

# En tu código, simplemente incluye:
#include <toml++/toml.h>

Método 4: CMake FetchContent (para proyectos CMake)

include(FetchContent)
FetchContent_Declare(
    tomlplusplus
    GIT_REPOSITORY https://github.com/marzer/tomlplusplus.git
    GIT_TAG v3.4.0
)
FetchContent_MakeAvailable(tomlplusplus)

target_link_libraries(mi_proyecto PRIVATE tomlplusplus::tomlplusplus)

3. Inicio rápido — ejemplo mínimo funcional

Creemos un archivo config.toml:

# config.toml
title = "Ejemplo de configuración"

[server]
host = "localhost"
port = 8080
debug = true

[database]
name = "mibd"
user = "admin"
password = "secreto123"

Ahora escribamos el código C++ para leerlo:

#include <toml++/toml.h>
#include <iostream>
#include <filesystem>

int main() {
    // 1. Analizamos el archivo
    auto config = toml::parse_file("config.toml");

    // 2. Leemos valores simples
    std::string title = config["title"].value_or("default");
    std::cout << "Título: " << title << std::endl;

    // 3. Leemos tablas anidadas
    auto server = config["server"];
    std::string host = server["host"].value_or("localhost");
    int port = server["port"].value_or(3000);
    bool debug = server["debug"].value_or(false);

    std::cout << "Servidor: " << host << ":" << port << std::endl;
    std::cout << "Modo debug: " << (debug ? "activado" : "desactivado") << std::endl;

    // 4. Leemos otra tabla
    auto database = config["database"];
    std::string db_name = database["name"].value_or("default_db");
    std::string db_user = database["user"].value_or("root");

    std::cout << "Base de datos: " << db_name << " (usuario: " << db_user << ")" << std::endl;

    return 0;
}

¡Y eso es todo! Con solo incluir toml++/toml.h ya tienes acceso a todas las funcionalidades de la biblioteca.