Estrutura de uma biblioteca
O esqueleto que o init cria, o que cada campo do forge.toml significa, e onde pôr cada coisa.
dataforge init minha-lib
cd minha-libminha-lib/
forge.toml o manifesto (versionado)
src/main.df a entrada (versionado)
tests/principal_test.df os testes (versionado)
forge.lock o que foi instalado (versionado)
forge_modules/ as dependências (NÃO versionado)
dist/ os tarballs gerados (NÃO versionado)O manifesto, campo a campo#
[package]
name = "validador"
version = "1.0.0"
description = "Validação de dados: e-mail, CPF, CNPJ, CEP, telefone e senha."
authors = ["Seu Nome"]
license = "MIT"
entry = "src/main.df"
dataforge = ">=1.0"
keywords = ["validacao", "formulario", "cpf", "brasil"]
[dependencies]
texto = "^1.0"
[lint]
ignore = ["magic-number"]
[scripts]
test = "test tests/"
| Campo | Para quê |
|---|---|
name | o nome do adopt. Minúsculas, sem espaço — e não se muda depois |
version | semver. Ver versão |
description | a linha que aparece no dataforge search |
entry | o arquivo que adopt minha-lib carrega |
dataforge | de qual versão da linguagem ela precisa |
keywords | como alguém acha a sua biblioteca sem saber o nome |
[dependencies] | o que ela pede, com faixa semver |
[lint] | as regras que este projeto silencia, com o porquê em comentário |
[scripts] | atalhos: dataforge test vira o que estiver aqui |
Uma entrada, e o resto interno#
O entry é a porta. Tudo o que não passa por ela é detalhe de implementação, e é assim que se consegue mudar o interior sem quebrar ninguém:
src/
main.df a porta — só 'adopt' e 'relay'
cpf.df a regra do CPF
cnpj.df a do CNPJ
comum.df o que os dois usamadopt ./cpf as Cpf
adopt ./cnpj as Cnpj
action cpf(texto):
yield Cpf.validar(texto)
action cnpj(texto):
yield Cnpj.validar(texto)
relay cpf, cnpjQuem usa escreve V.cpf("..."). Que exista um comum.df, e o que tem dentro, não é problema de ninguém — e pode mudar numa versão de correção.
Nada de efeito no topo#
O corpo de um módulo roda no adopt de quem importa. Numa biblioteca, isso significa: na hora em que a aplicação da outra pessoa inicia.
// NÃO: isto abre conexão quando alguém te importa
conexao := Banco.abrir("dados.db")
action buscar(id):
yield Banco.query(conexao, "SELECT …", [id])// SIM: quem usa decide quando, e com qual banco
action buscar(conexao, id):
yield Banco.query(conexao, "SELECT …", [id])
relay buscarO sintoma do primeiro caso é caro e indireto: o teste de quem te usa fica lento, ou abre arquivo, ou falha em CI sem disco — e a causa está numa biblioteca que ele nem chamou ainda.
O README é parte do pacote#
Três coisas que quem chega procura, nesta ordem: o que isto faz (uma frase), como instalo (uma linha), um exemplo que roda (cinco linhas). O resto pode esperar.