ZON em Zig — O que é e Como Usar

Definição

ZON (Zig Object Notation) é o formato de dados nativo do Zig, inspirado na sintaxe de literais anônimos da linguagem. ZON é usado principalmente no arquivo build.zig.zon para declarar metadados e dependências de pacotes. Ele oferece uma alternativa ao JSON e TOML que é nativa do ecossistema Zig, com sintaxe familiar para programadores Zig.

Por que ZON Importa

1. Nativo do Zig: Usa a mesma sintaxe de structs anônimas e literais do Zig.
2. Manifesto de pacotes: O build.zig.zon é o arquivo de configuração central de qualquer projeto Zig.
3. Tipagem: Diferente de JSON, suporta tipos como enums e multiline strings.
4. Sem ambiguidade: Sintaxe clara e consistente, sem as armadilhas do JSON (trailing commas, comentários).

Exemplo Prático

Sintaxe ZON Básica

// Arquivo: build.zig.zon
.{
    .name = "meu-projeto",
    .version = "1.0.0",

    .dependencies = .{
        .minha_lib = .{
            .url = "https://example.com/lib.tar.gz",
            .hash = "1220abcdef1234567890abcdef1234567890abcdef1234567890abcdef12345678",
        },
    },

    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
    },
}

Comparação com JSON

// ZON
.{
    .nome = "Zig Brasil",
    .versao = "0.1.0",
    .tags = .{ "zig", "brasil", "programação" },
    .ativo = true,
}

// JSON equivalente
{
    "nome": "Zig Brasil",
    "versao": "0.1.0",
    "tags": ["zig", "brasil", "programação"],
    "ativo": true
}

Lendo ZON em Código Zig

const std = @import("std");

// @embedFile pode incluir um arquivo ZON em comptime
// Mas para build.zig.zon, o sistema de build faz o parsing automaticamente

const config = .{
    .porta = 8080,
    .host = "0.0.0.0",
    .max_conexoes = 1000,
    .debug = false,
};

pub fn main() void {
    std.debug.print("Servidor em {s}:{}\n", .{ config.host, config.porta });
    std.debug.print("Max conexões: {}\n", .{config.max_conexoes});
}

Tipos de Dados em ZON

Armadilhas Comuns

• Não é JSON: ZON usa .campo = com ponto, não "campo": com aspas. Não tente usar JSON no lugar de ZON.
• Trailing comma: ZON permite vírgula após o último item (como Zig). JSON não.
• Comentários: ZON atualmente não suporta comentários, apesar de Zig (a linguagem) suportar.
• Parsing em runtime: ZON é primariamente usado em comptime. Para dados em runtime, considere JSON com std.json.

Termos Relacionados

• build.zig.zon — Arquivo principal em formato ZON
• build.zig — Consome dados do build.zig.zon
• zig fetch — Gera hashes para dependências ZON
• Comptime — ZON é avaliado em comptime

ZON em Profundidade

Strings Multiline

ZON suporta strings multiline usando a sintaxe de string delimitada por \\:

.{
    .descricao =
        \\Este é um projeto de exemplo para demonstrar
        \\o uso de ZON como formato de configuração.
        \\Cada linha começa com \\.
    ,
    .versao = "1.0.0",
}

Valores Enum

ZON permite usar valores enum com o prefixo ., o que não tem equivalente direto em JSON:

.{
    .nivel_log = .debug,      // enum
    .modo = .producao,        // enum
    .compressao = .nenhuma,   // enum
}

Parsing em Runtime com std.zig.Ast

Embora ZON seja principalmente um formato comptime, é possível fazer parsing em runtime usando a API do compilador exposta pela biblioteca padrão:

const std = @import("std");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Ler arquivo ZON em runtime
    const conteudo = try std.fs.cwd().readFileAlloc(allocator, "config.zon", 1024 * 1024);
    defer allocator.free(conteudo);

    // Parsear como AST do Zig
    var ast = try std.zig.Ast.parse(allocator, conteudo, .zon);
    defer ast.deinit(allocator);

    // Verificar erros de parse
    if (ast.errors.len > 0) {
        std.debug.print("Erros no arquivo ZON\n", .{});
        return error.ParseError;
    }
}

Para casos de uso em runtime, std.json costuma ser mais prático, pois tem APIs de serialização/deserialização completas. ZON é ideal quando os dados são conhecidos em tempo de compilação.

Boas Práticas

• Prefira ZON para configuração de build: O formato é a escolha natural para build.zig.zon e outros arquivos de configuração do ecossistema Zig.
• Use JSON para dados em runtime: Se você precisa ler/escrever dados em runtime que serão consumidos por outras linguagens ou ferramentas, prefira std.json.
• Nomes de campos descritivos: Como ZON usa .campo =, nomes longos e descritivos são preferíveis a abreviações.
• Não misture com JSON: Não tente editar um arquivo ZON com uma ferramenta JSON — a sintaxe é diferente o suficiente para causar erros silenciosos.

Tutoriais Relacionados

• Zig Packaging
• Zig Build System
• Introdução ao Zig