Escrever uma biblioteca

Do esqueleto ao registro, com o que separa uma boa de uma qualquer.

O esqueleto#

meu-pacote/
├── forge.toml
├── README.md
├── src/
│   └── main.df        o ponto de entrada
└── tests/
    └── meu_pacote_test.df

O manifesto#

[package]
name = "texto"
version = "1.0.0"
description = "Texto: slug, truncar, mascarar, distância de edição, similaridade e templates."
authors = ["DataForge"]
license = "MIT"
entry = "src/main.df"
dataforge = ">=4.1"
keywords = ["texto", "string", "slug"]

[dependencies]

[scripts]
test = "test tests/"

A API é o que o relay exporta#

action publica(x):
    yield _interna(x) * 2

action _interna(x):        // detalhe: não sai
    yield x + 1

relay publica

Tudo o que atravessa o relay é promessa. Mudar a assinatura de algo exportado quebra quem depende — e é por isso que a lista deve ser curta e deliberada.

Testar como pacote, não como arquivo#

Rodar os testes de dentro da pasta não exercita a instalação nem o adopt. O jeito de provar que funciona é instalar num projeto limpo:

cd /tmp && mkdir bancada && cd bancada
printf '[project]\nname="bancada"\nversion="0.1.0"\n\n[dependencies]\n' > forge.toml
dataforge add ~/meu-pacote
cp -r ~/meu-pacote/tests .
dataforge test tests/

O repositório do DataForge automatiza isso em scripts/testar_libs.sh, e roda para os 20 pacotes a cada mudança.

O linter guia a estrutura#

dataforge lint src/ aponta ação longa demais, aninhamento profundo, número mágico repetido e parâmetro nunca usado. Vale seguir: as bibliotecas do registro foram divididas exatamente onde ele apontou.

Quando a regra não serve ao seu caso, desligue no manifesto — e diga por quê:

[lint]
# A tabela de pesos do CPF/CNPJ é a especificação do documento: são
# números que não se pode nomear, porque não significam nada sozinhos.
ignore = ["magic-number"]

Publicar#

dataforge pack
dataforge publish --registry=/caminho/do/registro

O tarball é reprodutível: mesma fonte, mesmo sha256. Republicar a mesma versão é recusado — suba a version primeiro, porque um lockfile apontando para conteúdo que mudou é pior que um erro.

Versionar#

Quem depende de você escreveu ^1.0.0. Enquanto o maior não sobe, essa pessoa recebe suas versões automaticamente — e conta com que nada quebre.

Uma biblioteca boa#

• Resolve um problema, não cinco. moeda não formata data.
• Explica por que existe no cabeçalho — o que o código não diz sozinho.
• Falha com mensagem útil. trigger "nao da para operar BRL com USD sem converter" vale mais que um void silencioso.
• Tem teste do caso difícil, não só do fácil: repartir 10 reais em 3 sem perder centavo, arredondar 2,5 para cima.