toml++ para C++: guia completo com exemplos práticos

1. O que é e para que serve

TOML (Tom's Obvious Minimal Language) é um formato de arquivos de configuração criado como alternativa ao INI, YAML e JSON. Ele foi projetado para ser altamente legível para humanos, mapear diretamente para tabelas hash e ser simples de fazer parsing. Ao contrário do YAML, o TOML não permite ambiguidades (como indentação ou tipos de dados), e ao contrário do JSON, não exige aspas nas chaves e suporta comentários.

toml++ (também conhecido como tomlplusplus) é uma biblioteca moderna, header-only (somente cabeçalhos) para parsing e geração de arquivos TOML em C++17 ou superior. Ela não requer compilação separada: basta incluir o arquivo de cabeçalho e você tem acesso a todas as funcionalidades. Isso a torna ideal para projetos que priorizam simplicidade de integração, performance e tipagem forte.

Por que usar toml++? Primeiro, ela oferece suporte completo à especificação TOML v1.0, incluindo tabelas inline, arrays de tabelas, datas, horários e datas locais. Segundo, ela foi desenvolvida com foco em segurança de tipos: você obtém valores fortemente tipados (std::string, int64_t, double, bool, toml::date, etc.), e não um objeto genérico estilo JSON. Terceiro, ela é extremamente rápida e tem dependências mínimas (apenas a biblioteca padrão do C++17).

2. Instalação

toml++ é uma biblioteca header-only. Isso significa que você não precisa compilá-la separadamente. Basta copiar os arquivos de cabeçalho para o seu projeto e incluí-los.

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

# Instalação via vcpkg
vcpkg install tomlplusplus

# Inclusão no CMakeLists.txt
find_package(tomlplusplus CONFIG REQUIRED)
target_link_libraries(meu_projeto PRIVATE tomlplusplus::tomlplusplus)

Método 2: Conan

# Instalação via Conan
conan install tomlplusplus/3.4.0@

# No conanfile.txt
[requires]
tomlplusplus/3.4.0

[generators]
CMakeDeps

Método 3: Instalação manual (mais simples)

# Baixe a versão mais recente do GitHub
wget https://github.com/marzer/tomlplusplus/archive/refs/tags/v3.4.0.tar.gz
tar -xzf v3.4.0.tar.gz

# Copie a pasta include/toml++ para o seu projeto
cp -r tomlplusplus-3.4.0/include/toml++ /caminho/do/seu/projeto/include/

# No seu código, basta incluir:
#include <toml++/toml.h>

Método 4: CMake FetchContent (para projetos 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(meu_projeto PRIVATE tomlplusplus::tomlplusplus)

3. Primeiros passos — exemplo mínimo funcional

Crie um arquivo config.toml:

# config.toml
titulo = "Exemplo de configuração"

[servidor]
host = "localhost"
porta = 8080
debug = true

[banco]
nome = "meubd"
usuario = "admin"
senha = "segredo123"

Agora, escreva o código C++ para ler o arquivo:

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

int main() {
    // 1. Faz o parsing do arquivo
    auto config = toml::parse_file("config.toml");

    // 2. Lê valores simples
    std::string titulo = config["titulo"].value_or("padrao");
    std::cout << "Título: " << titulo << std::endl;

    // 3. Lê tabelas aninhadas
    auto servidor = config["servidor"];
    std::string host = servidor["host"].value_or("localhost");
    int porta = servidor["porta"].value_or(3000);
    bool debug = servidor["debug"].value_or(false);

    std::cout << "Servidor: " << host << ":" << porta << std::endl;
    std::cout << "Debug: " << (debug ? "ativado" : "desativado") << std::endl;

    return 0;
}