Fundamentos

Módulos

adopt, relay, imports seletivos e detecção de ciclos.

Importar#

dataforge

adopt Arcane.Math as Math          # o módulo inteiro, sob um nome
adopt geometria as geo             # arquivo geometria.df ao lado

out Math.sqrt(16), geo.area_circulo(2)

A resolução segue esta ordem:

módulos já carregados (cache — um arquivo só executa uma vez)
biblioteca padrão (Arcane.* e os nomes curtos)
arquivo .df ao lado do arquivo que importa

Imports seletivos#

dataforge

adopt Arcane.Math.{sqrt, floor}           # forma compacta
adopt {sqrt as raiz} from Arcane.Math     # com apelido

out sqrt(16), raiz(25)

Forma	Boa para
`as geo`	módulo com muitos símbolos; o prefixo documenta a origem
`.{a, b}`	dois ou três símbolos usados o tempo todo
`{a as b} from`	resolver conflito de nomes

O prefixo não é burocracia: Math.sqrt(x) diz de onde sqrt veio. Num arquivo que importa cinco módulos, é o que evita a pergunta "onde é que isso está definido?".

Apelidos resolvem colisões#

dataforge

adopt {formatar as formatar_data} from datas
adopt {formatar as formatar_moeda} from dinheiro

Exportar com relay#

geometria.df

// geometria.df
steady PI := 3.14159265

action area_circulo(raio):
    yield PI * raio ** 2

action _detalhe_interno():
    yield "nao deveria escapar"

relay PI, area_circulo

No módulo	Exporta
nenhum `relay`	tudo do nível superior
pelo menos um `relay`	só o que foi listado

Sem relay, você tem a conveniência de um script. Com relay, tem uma interface pública — e o que ficou de fora é detalhe de implementação que pode ser reescrito sem quebrar ninguém.

dataforge

adopt geometria as geo
out geo._detalhe_interno()
# Vault has no key '_detalhe_interno'

Essa é a diferença entre "por convenção não use isso" (o _ do Python) e "isso não está acessível". A segunda é verificável.

Erros com mensagem útil#

text

Module 'Arcane.NaoExiste' not found.
Available: Analytics, Arcane.Analytics, Arcane.Async, …

Module 'geometria' does not export: nao_existe.
It exports: PI, area_circulo

As mensagens listam o que existe. Quase sempre o problema é um nome digitado errado, e ver a lista resolve sem abrir o outro arquivo.

Ciclos#

Importes circulares são detectados, com a cadeia na mensagem:

text

Circular import: ciclo_a.df → ciclo_b.df → ciclo_a.df.
Break the cycle by moving the shared part into a third module.

Organizando um projeto#

text

src/
  modelo.df          record Produto, enum Situacao
  regras.df          decisões de negócio — puras
  apresentacao.df    como virar texto
  main.df            junta tudo
tests/
  regras_test.df
forge.toml

Cada camada depende só das de cima. O critério prático é o que muda junto: trocar o limite de estoque mexe só em regras.df; trocar o terminal por uma página web mexe só em apresentacao.df.

Mais sobre isso em Estrutura de projeto.