1. O que é e para que serve?

Na linguagem C++, as enumerações (enum e enum class) são ferramentas poderosas para criar constantes nomeadas, mas têm uma desvantagem significativa: a falta de reflexão embutida. O C++ padrão não oferece uma maneira simples de obter a representação em string de um valor de enumeração, iterar sobre todos os seus elementos ou saber a quantidade de variantes. Os desenvolvedores precisam escrever funções auxiliares manualmente, usar macros ou geradores de código de terceiros, o que leva à duplicação de código e erros.

A biblioteca magic_enum resolve esse problema fornecendo um conjunto poderoso e conveniente de ferramentas para trabalhar com enumerações em tempo de compilação e execução. Ela usa a magia dos templates do C++17 e mecanismos internos do compilador (como __PRETTY_FUNCTION__) para extrair automaticamente informações sobre enumerações. Com o magic_enum, você pode obter o nome em string de qualquer valor, converter uma string em valor, iterar sobre todos os elementos da enumeração, saber sua quantidade e muito mais — sem precisar escrever nenhum código auxiliar.

Esta biblioteca é indispensável para logging, serialização/desserialização, criação de arquivos de configuração, análise de entrada do usuário, testes e qualquer outra tarefa que exija trabalho dinâmico com enumerações. Ela torna o código mais limpo, seguro e reduz significativamente a quantidade de código repetitivo. O magic_enum é, sem dúvida, a biblioteca mais popular e madura para reflexão de enums em C++, compatível com todos os principais compiladores (GCC, Clang, MSVC).

2. Instalação

O magic_enum é uma biblioteca header-only, composta por um único arquivo de cabeçalho. Isso torna sua instalação incrivelmente simples. Você não precisa compilá-la como uma biblioteca separada; basta copiar o arquivo magic_enum.hpp para o seu projeto e incluí-lo.

No entanto, para facilitar o gerenciamento de dependências, é recomendável usar sistemas de build como CMake (via FetchContent ou find_package) ou gerenciadores de pacotes como vcpkg ou Conan.

Método 1: Baixar o arquivo manualmente (o mais simples)

1. Acesse a página de releases no GitHub: https://github.com/Neargye/magic_enum/releases
2. Baixe a versão mais recente do arquivo magic_enum.hpp.
3. Coloque-o na pasta do seu projeto (por exemplo, em include/).
4. Inclua-o no código: #include "magic_enum.hpp"

Método 2: Via vcpkg (recomendado para Windows)

vcpkg install magic-enum

Método 3: Via Conan

conan install magic_enum/0.9.5@

Método 4: Via CMake FetchContent (recomendado para novos projetos)

Adicione o seguinte código ao seu CMakeLists.txt:

include(FetchContent)
FetchContent_Declare(
  magic_enum
  GIT_REPOSITORY https://github.com/Neargye/magic_enum.git
  GIT_TAG v0.9.5 # Ou a tag estável mais recente
)
FetchContent_MakeAvailable(magic_enum)

target_link_libraries(seu_projeto PRIVATE magic_enum::magic_enum)

Importante: Para usar o magic_enum, é necessário um compilador com suporte a C++17. Certifique-se de ativar o padrão correspondente no seu projeto (por exemplo, set(CMAKE_CXX_STANDARD 17) ou a flag -std=c++17).

3. Início rápido — exemplo mínimo funcional

Vamos começar com o exemplo mais simples