A extensão do editor

Cores, erros enquanto se digita, autocompletar, depurador com breakpoints, Big-O acima de cada ação, 60 comandos e o painel de bancos. O que cada coisa faz, e por quê.

A extensão não reimplementa nada da linguagem: ela chama a CLI e desenha o resultado. É isso que garante que o sublinhado no editor, a saída do terminal e o que quebra o CI sejam sempre a mesma coisa — a alternativa seria um analisador no editor divergindo do analisador de verdade, e um editor que diz "tudo certo" sobre código que o CI recusa.

O que ela acrescenta é o que só faz sentido dentro do editor: complexidade acima de cada ação, custo ao lado de cada import, breakpoints na margem, e um painel para os bancos do projeto.

Instalar#

dataforge editor

Isso copia a extensão para todos os editores compatíveis que encontrar: VS Code, VS Code Insiders, VSCodium, Cursor e Windsurf. Reinicie o editor e abra um .df.

dataforge editor status     # onde está instalada
dataforge editor remove     # desinstala de todos

Erros enquanto você digita#

O sublinhado vem do mesmo dataforge check que roda no CI, servido pelo servidor de linguagem — que reanalisa a cada tecla, e não só ao salvar.

Autocompletar, hover, ir-para-definição#

O servidor de linguagem (dataforge lsp) é servido do mesmo typechecker. O que ele dá:

Os nomes do próprio arquivo vêm antes dos 1873 símbolos da stdlib — é o que se procura em nove de cada dez vezes.

Depurar: F5#

Clique na margem para pôr um breakpoint e aperte F5. Não é preciso escrever launch.json.

// Pare na linha do 'yield' e escreva no console:
total * 2 + len(nome)
cliente.saldo
[n * n cycle n in itens]

As variáveis embutidas — 228 delas — não aparecem no painel. Elas vivem no escopo global, e despejá-las enterra as três variáveis que você parou para ver.

Depurar no terminal#

O comando Depurar no terminal roda dataforge debug, que é passo a passo em texto. Serve onde interface gráfica nenhuma chega — por ssh, num container, num servidor.

dataforge debug conta.df --parar=42

Dentro dele: p passo, n próximo, f sai da ação, c continua, vars lista o escopo, pilha mostra quem chamou quem, e qualquer expressão é avaliada no quadro onde você parou.

Parar quando um valor muda#

Uma parada por linha responde "o programa passou aqui?". Quem depura um valor errado quer saber outra coisa: quem mudou isto? A vigia responde. Ela é conferida depois de cada instrução, e a parada mostra a linha que mudou o valor, com o antes e o depois.

dataforge debug conta.df --vigiar=total --vigiar='pedido.itens'

# ou, já parado:
w total          vigia no quadro onde você está
vigias           lista, com o valor e quantas mudanças
desvigiar 1      tira a vigia 1

A mutação no lugar conta — xs.append(1) muda a lista sem trocar a referência —, e o campo mudado dentro de um método também, com a parada na linha do método. Uma vigia criada dentro de uma ação olha aquela ação: o mesmo nome lá fora é outra variável.

No editor, clique com o botão direito numa variável do painel e escolha Break on Value Change. É o data breakpoint do protocolo: o painel mostra o motivo data breakpoint e, na descrição, de quanto para quanto o valor foi.

Parar quando um valor é LIDO#

A vigia de mudança responde quem mudou isto?. Há uma pergunta irmã, e ela aparece quando o valor está certo e chega a um lugar errado: quem está consultando isto? Um valor que nunca mudou não dispara nenhuma vigia de mudança.

dataforge debug conta.df --vigiar-leitura=saldo

# ou, ja parado:
r saldo          para quando 'saldo' for LIDO
r self.saldo     para na leitura do campo, de dentro ou de fora
acessos          lista, com quantas leituras cada uma teve

No editor é o mesmo data breakpoint, com Break on Value Read: dataBreakpointInfo passou a anunciar accessTypes: ["write", "read"], e o painel escolhe qual.

Big-O acima de cada ação#

Uma lente sobre a declaração, com a complexidade estimada — e um aviso quando ela passa do limite que você configurou.

// O(n²) — dois laços aninhados sobre a mesma entrada
action duplicados(itens):
    saida := []
    cycle a in itens:
        cycle b in itens:
            given a is b:
                saida.append(a)
    yield saida

Clique na lente para ver por quê: qual laço, qual chamada, e o que domina. dataforge.complexidade.avisarAcimaDe controla o limite (padrão O(n log n)).

Custo de cada import#

Ao lado de cada adopt, quantos nomes ele traz ao escopo. O módulo inteiro traz tudo que ele tem; a forma seletiva traz o que você nomeou.

adopt Arcane.Math as Math          // o módulo inteiro
adopt Arcane.Math.{sqrt, floor}    // dois nomes

A barra de status#

Antes havia um botão de rodar, e mais nada. Os 60 comandos viviam na paleta — e a paleta só serve a quem já sabe que o comando existe.

O item principal abre um menu, e não um comando. Ele é o índice do que a extensão faz — o lugar onde se descobre. São seis grupos: Rodar, Conferir, Testar, Entender, Projeto e Ajuda.

A complexidade é a da ação do cursor, e não do arquivo. "Este arquivo tem um O(n²) em algum lugar" não ajuda ninguém; "a ação onde você está é O(n²)" muda o que se escreve na linha seguinte.

Os testes no painel do editor#

O dataforge test já existia e já era bom. O que faltava era ele aparecer onde se olha: o painel de testes, com o triângulo ao lado de cada trial e o erro na linha que falhou.

• Um item por `trial`, e não por arquivo. "1 de 2 falhou" sem dizer qual não serve para nada.
• A descoberta é por leitura, e não por execução. Um painel que precisa rodar a suíte para saber o que existe não serve: rodar é o que se quer decidir depois de ver a lista.
• Um processo por arquivo. O corredor já roda o arquivo inteiro, e subir um processo por teste custaria mais que os testes.

Um arquivo sem nenhum trial não vira item — um painel com trinta arquivos vazios esconde os que importam.

Os 60 comandos#

Aprender — abrir a documentação do símbolo sob o cursor (Shift+F1), as 100 palavras da linguagem com o exemplo que roda, os dois temas de cor e o idioma das mensagens. O hover dizia o que uma palavra faz; o que faltava era o passo seguinte, que é ir ler — e quem precisa sair do editor para isso três vezes para de fazer.

Tudo na paleta (Ctrl+Shift+P) sob DataForge, e na árvore Ferramentas da barra lateral.

Rodar e medir#

Qualidade#

Entender#

Projeto e pacotes#

Vitrine e DevOps#

O painel de bancos de dados#

Na barra lateral, a árvore Bancos de dados lista as conexões do projeto. Cada uma pode ser testada, atualizada, removida — e inserida como código no editor, o que evita escrever a string de conexão à mão.

Ela lê o mesmo lugar de onde o Arcane.Forge lê: não há uma segunda configuração para manter em sincronia.

Os snippets#

Vinte e três atalhos, para as construções em que digitar o esqueleto custa mais que pensar nele:

Cores, ícones e indentação#

A gramática de cores é gerada de tokens.py — as 81 palavras reservadas, os operadores, a interpolação $"…{…}", e a diferença entre // (comentário) e ~/ (divisão inteira).

Junto vêm o tema de ícone de arquivo (o .df com a marca), 4 espaços de indentação forçados (insertSpaces, tabSize: 4, detectIndentation: false — tab é erro de sintaxe na linguagem), dobra de blocos, e os snippets das construções mais longas.

Configuração#

Tarefas e o matcher de problemas#

A extensão registra o tipo de tarefa dataforge e um problem matcher de mesmo nome: a saída de check, lint e test vira item clicável no painel de problemas — inclusive quando você roda por uma tarefa própria.

{
  "version": "2.0.0",
  "tasks": [{
    "type": "dataforge",
    "comando": "check",
    "problemMatcher": ["$dataforge"],
    "group": { "kind": "build", "isDefault": true }
  }]
}

Outros editores#

A gramática é TextMate padrão, em editor/vscode/syntaxes/dataforge.tmLanguage.json — Sublime Text e compatíveis leem o mesmo arquivo, e para Vim, Emacs ou Zed ela serve de referência: a lista de palavras por grupo de cor está toda ali.

O servidor de linguagem e o depurador são processos que falam protocolo padrão, e por isso servem qualquer editor:

dataforge lsp     # Language Server Protocol, no stdio
dataforge dap     # Debug Adapter Protocol, no stdio

É por isso que a máquina dos dois mora na linguagem, e não na extensão: escrevê-la em TypeScript a amarraria ao VS Code. A extensão só diz ao editor qual processo iniciar.

Para pular a instalação da extensão ao instalar a linguagem, defina DATAFORGE_SEM_EDITOR=1.

Onde continuar#