Técnicas

Serialização

JSON, CSV, TOML, XML e a fronteira entre o programa e o mundo.

Por que importa#

Todo programa que não é um exercício conversa com o mundo: lê um arquivo, chama uma API, grava um relatório. Serialização é essa fronteira.

dataforge

adopt Arcane.Serialization as Serde

JSON#

dataforge

Serde.to_json(dados)                  # compacto
Serde.json_pretty(dados, 2)           # indentado
Serde.from_json(texto)                # pode disparar
Serde.from_json_safe(texto, padrao)   # nunca dispara

A variante _safe#

dataforge

r := Serde.from_json_safe("{isso nao e json")
# {ok: no, value: void, error: "Expecting property name..."}

r := Serde.from_json_safe(corpo)
given r.ok:
    processar(r.value)
otherwise:
    responder_erro(r.error)

Dado que veio de fora vai estar malformado alguma hora. A variante _safe transforma isso num valor que você examina, em vez de uma exceção que precisa envolver em monitor.

json_path — navegar sem quebrar#

dataforge

Serde.json_path(dados, "autor.nome")
Serde.json_path(dados, "tags.0")                       # índice de lista
Serde.json_path(dados, "autor.telefone", "ausente")    # com padrão

Sem isso, chegar num campo aninhado exige verificar cada nível. json_path faz o mesmo em uma expressão.

CSV#

dataforge

Serde.records_to_csv(registros)     # lista de vaults → CSV com cabeçalho
Serde.csv_to_records(csv)           # CSV → lista de vaults
Serde.to_csv(linhas, ",", cabecalho)
Serde.from_csv(texto, ",", yes)

As duas primeiras assumem que a primeira linha é cabeçalho e que cada linha vira um vault — o formato natural para dados tabulares.

TOML#

Legível para humanos, ideal para configuração:

dataforge

config := {"servidor": {"host": "localhost", "porta": 8080}}
out Serde.to_toml(config)

saída

[servidor]
host = "localhost"
porta = 8080

Achatar e desachatar#

dataforge

Serde.flatten({"a": {"b": 1}})      # {"a.b": 1}
Serde.unflatten({"a.b": 1})         # {"a": {"b": 1}}

flatten é o que transforma um JSON aninhado em colunas de CSV. unflatten reconstrói.

JSON Lines#

dataforge

Serde.json_lines(registros)         # um objeto JSON por linha
Serde.from_json_lines(texto)

O formato de log e de exportação em lote: cada linha é independente, então dá para processar em stream sem carregar o arquivo inteiro.

Outros formatos#

Formato	Funções
INI	`to_ini` `from_ini`
XML	`to_xml` `from_xml`
Binário	`to_bytes` `from_bytes`
Base64	`to_base64` `from_base64`

A lista completa está em Arcane.Serialization.