Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Bem-vindo ao Livro do CGD

Este livro foi escrito para quem quer aprender a programar com o CGD (Compilador Geral Delégua) sem enrolação — desde instalar as ferramentas até criar servidores HTTP, usar SQLite e rodar tarefas em paralelo com rotina.

Antes de tudo: qual é a relação com a Delégua original?

A linguagem Delégua foi criada pela Design Líquido (com sua wiki oficial) e roda originalmente sobre um interpretador em TypeScript/Node.js.

O CGD pega essa mesma base em português e compila seu código para C99 e executável nativo em Linux x86_64, usando um runtime próprio em C com coletor Boehm GC. Por causa disso, várias coisas mudam de comportamento e muitas funcionalidades — como assincrona/aguardar, rotina/Tarefa<T>, Canal, as 24 bibliotecas cgd:* instaladas em ~/.delegua/cgd, o servidor LSP e o formatador — foram construídas do zero no CGD.

Se você já conhece Delégua pelo interpretador, vale ler logo o capítulo Delégua original vs. CGD para não se surpreender com as diferenças.

Por onde começar?

Use a busca no topo (tecla S) ou o menu lateral para pular direto para qualquer assunto.

← Voltar para a página principal do CGD · Abrir referência em página única

Comece aqui: instalar, escrever e executar

Se esta é a sua primeira vez com o CGD, comece por aqui. Em poucos minutos você vai instalar as ferramentas, escrever seu primeiro programa em português e rodar o executável nativo no terminal.

O que você precisa instalar antes

Hoje o CGD é validado em Linux x86_64. Você precisa de Git, DUB, um compilador D (LDC2 ou DMD), um compilador C99 (Clang ou GCC), pkg-config, Python 3, headers do Boehm GC e libcurl (>= 7.86).

O runtime em C fica no submódulo vendor/delegua-runtime. Depois de compilar, o script ./instalar coloca o binário em ~/.local/bin/cgd, o runtime em ~/.local/share/cgd e as 24 bibliotecas padrão em ~/.delegua/cgd.

git clone --branch dev --recurse-submodules https://github.com/FernandoTheDev/cgd.git
cd cgd
./build-runtime
dub build --compiler=ldc2 --build=release
./instalar --no-build

Seu primeiro programa

Crie um arquivo chamado ola.delegua. A extensão .delegua é obrigatória. A função escreva imprime o texto e já pula linha no final — se você passar vários argumentos, eles saem colados na ordem em que foram escritos.

var nome: texto = "Ana"
escreva("Olá, ${nome}!")

Compilar, verificar, otimizar e formatar

Use -s para escolher o nome do executável de saída e -o quando quiser ativar otimizações e avaliação em tempo de compilação (CTFE). Quer só checar se tem erro sem gerar binário? Use --verificar. Quer deixar o arquivo arrumado com 4 espaços? Use --formatar.

cgd ola.delegua --verificar
cgd ola.delegua -s out/ola
./out/ola
cgd ola.delegua -o -s out/ola-otimizado
cgd --formatar ola.delegua
cgd ola.delegua --emitir-c -s out/ola

Por que o CGD funciona diferente do interpretador?

Porque aqui seu código vira C99 e depois um programa nativo independente — sem Node.js e sem interpretador rodando por baixo. No próximo capítulo a gente explica em detalhes o que veio da Delégua original e o que o CGD construiu do zero.

Se ~/.local/bin ainda não estiver no seu PATH, adicione export PATH="$HOME/.local/bin:$PATH" no seu ~/.bashrc ou ~/.zshrc.

Delégua original vs. CGD: o que muda e o que é novo

Muita gente chega aqui já conhecendo a wiki oficial da Delégua (da Design Líquido). Esta página deixa tudo às claras: o que funciona igual, o que muda de comportamento e o que o CGD inventou de forma 100% nativa.

Duas ferramentas com a mesma língua, mas objetivos diferentes

A linguagem Delégua nasceu na Design Líquido (github.com/DesignLiquido/delegua) com foco em ensino, navegador e Node.js, rodando num interpretador escrito em TypeScript. Ela traz múltiplos dialetos, modo interativo LAIR e acesso a pacotes NPM.

O CGD preserva a autoria original e a licença Apache-2.0, mas segue outro caminho: é um compilador próprio escrito em D que traduz Delégua para C99 e vincula com um runtime nativo em C (delegua-runtime) usando Boehm GC. Não existe Node.js nem JavaScript por trás.

O que o CGD criou do zero (não existe no Delégua original)

Vários recursos importantes do CGD foram desenhados do zero pensando em programas nativos, sem equivalente direto na wiki base do interpretador:

RecursoComo funciona
Assincronismo nativo (assincrona / aguardar / Promessa)Máquina de estados stackless gerada pelo compilador, com reactor epoll no Linux, temporizadores, HTTP e TCP não bloqueantes.
Rotinas paralelas (rotina / Tarefa / Canal / GrupoTarefas)Execução paralela real em pool de threads C com TLS por thread, registro no Boehm GC e transferência segura de valores.
Bibliotecas cgd:* em ~/.delegua/cgd24 módulos padrão (servidor HTTP, SQLite, Cripto/OpenSSL, Compressão/zlib, Bytes, Sockets, Processos, JSON, Rede, Tempo...) carregados diretamente de ~/.delegua/cgd — sem lista hardcoded e sem NPM.
Runtime próprio em C (delegua-runtime)Valores tipados, UTF-8, Boehm GC, diagnósticos visuais R0001 com trecho do arquivo, epoll e pool de threads.
Segurança estática (E3101–E3112) e CTFE (@puro)Detecta erros antes de rodar (divisão por zero, overflow, membro inexistente, mutação de tupla/texto, operações em nulo) e calcula funções e métodos estáticos @puro ainda na compilação com -o.
Extensão VS Code, LSP próprio e formatador nativoAutocomplete direto de ~/.delegua/cgd em importar("cgd:"), dicas virtuais de tipo, prévia de CTFE no hover e formatador próprio de 4 espaços.

Onde a semântica do CGD difere da wiki oficial

Se você copiar um código pronto da wiki oficial da Design Líquido, alguns detalhes funcionam diferente aqui — quase sempre para evitar armadilhas em código nativo:

RecursoComo funciona
Sem capturas implícitas (closures / upvalues)Na wiki original, funções internas podem ler variáveis de fora. No CGD isso é bloqueado (W4001/E4001): passe os dados como parâmetro ou use um objeto.
Importação estática em vez de NPMEm vez de importar pacotes NPM ou nomes calculados em runtime, o CGD usa caminhos literais .delegua ou importar("cgd:nome") vindo de ~/.delegua/cgd.
Herança simples + mescla + interfacesA wiki oficial tem herança múltipla. No CGD uma classe herda de uma única base (herda), pode misturar comportamentos com mescla e cumprir vários contratos com implementa.
Limpeza explícita (finalmente / destruir)Em vez de tendo ... como com finalizar(), use tente/finalmente e destrutor() chamado por destruir(objeto).
FFI C estática no binárioNa wiki, @definicao usa um despachador dinâmico como Koffi ou classes TS do host. No CGD, classe estrangeira gera chamada C direta no executável.
Tipos mais rígidos e sem dialetosNão existem dialetos extras (Portugol, Mapler...) nem compatibilidade com JavaScript. Inteiros são 64 bits verificados e variáveis tipadas começam com defaults previsíveis.

Sempre que quiser consultar a especificação da linguagem original, visite https://github.com/DesignLiquido/delegua/wiki. Quando quiser saber exatamente como o CGD compila e executa, este livro é a referência fiel.

Editor VS Code: cores, autocomplete e formatador

Programar fica bem mais leve quando o editor mostra os tipos, sugere métodos certos e avisa erros enquanto você digita. O servidor LSP do CGD roda 100% na sua máquina e nunca compila nem executa código só porque você digitou.

Como instalar a extensão

Depois de compilar o CGD e o runtime, instale as dependências da extensão e rode o script de empacotamento. Ele já sincroniza as bibliotecas em ~/.delegua/cgd, associa arquivos .delegua e ativa o ícone oficial da linguagem.

npm ci --prefix extensao-vscode --ignore-scripts
python3 scripts/instalar_extensao.py --associate

Autocomplete de bibliotecas cgd: e de membros

Comece a digitar importar("cgd: e o editor abre na hora a lista de todos os arquivos .delegua disponíveis em ~/.delegua/cgd — incluindo bibliotecas que você mesmo criou e salvou lá. Depois do ponto (objeto.), o LSP só mostra membros reais daquele tipo, classe, herança ou mescla, sem poluir a lista com funções soltas.

const JSON: qualquer = importar("cgd:json").JSON
const dados: dicionario = JSON.analisar('{"ok": true}')

Dicas virtuais de tipo e prévia de funções puras

Se você escrever const lista = [1, 2, 3] ou const t = rotina fib(10), o VS Code exibe os tipos inferidos (: numero[], : Tarefa) como dicas visuais cinzentas, sem alterar o seu arquivo. Se você já anotou o tipo, a dica não aparece repetida.

Ao passar o mouse sobre uma função ou método estático marcado explicitamente com @puro (ou o legado //>puro), o hover mostra a confirmação de pureza e a prévia do valor calculado (substituído no binário com -o). Funções comuns não poluem o hover com avisos de CTFE.

const lista = [1, 2, 3]
const primeiro = lista[0]
var explicito: inteiro = 3

Formatação com Ctrl+Shift+I

Pressionar Ctrl+Shift+I no VS Code roda exatamente o mesmo formatador da CLI (cgd --formatar): 4 espaços de indentação, genéricos limpos (Promessa), fatias sem espaços extras (valores[::-1]), preservação de coleções multilinha, comentários e strings interpoladas.

F5 no VS Code compila e executa o arquivo no terminal — ainda não é um depurador passo a passo (DAP). Sempre que reinstalar a extensão, recarregue a janela do VS Code.

Valores, tipos e variáveis

Variáveis guardam valores que podem mudar; constantes travam o nome naquele valor inicial. Você pode anotar o tipo explicitamente com dois-pontos ou deixar o compilador inferir para você.

var, const e inferência

Use var quando o valor vai mudar ao longo do programa, e const quando quiser garantir que aquele nome não seja reatribuído. Para deixar o contrato bem claro (especialmente em bibliotecas e funções), anote o tipo logo após o nome com dois-pontos.

var contador: inteiro = 0
var titulo = "CGD"
const limite: inteiro = 10

Tipos disponíveis e valores iniciais padrão

Se você declarar uma variável tipada sem valor inicial, tipos primitivos e coleções já nascem prontos para uso — já objetos, funções e tuplas começam como nulo para não rodar código escondido.

RecursoComo funciona
numero / númeroAceita inteiro e real; começa em 0.
inteiro / longoInteiro de 64 bits com sinal. Se estourar o limite (overflow), lança erro tratável.
real / decimalNúmero decimal de ponto flutuante (64 bits); começa em 0.0.
logico / booleano / binarioverdadeiro ou falso; começa em falso.
textoTexto UTF-8 imutável; começa vazio (""). Índices contam caracteres Unicode.
T[]Vetor tipado (ex.: inteiro[], texto[]); começa como um vetor vazio novo.
dicionario / dicionárioMapa de chave e valor; começa como um dicionário vazio novo.
Promessa e TarefaTipos nativos do CGD para funções assincrona e rotinas paralelas.
qualquer, classe, interface, funcao, tuplaComeçam como nulo quando declarados sem valor inicial.

Literais numéricos e comentários

Inteiros podem ser escritos em decimal, hexadecimal (0x / 0X), binário (0b / 0B) ou octal (0o / 0O), com separadores opcionais _ entre dígitos. Números reais aceitam separadores _, notação científica decimal (e / E) e ponto flutuante hexadecimal IEEE-754 (0x...p...). Comentários podem ser de linha (//) ou de bloco (/* ... */).

/* Literais inteiros e reais com separadores e bases */
const mascara: inteiro = 0xFFFF_FFFF
const flags: inteiro = 0b1111_0000
const permissao: inteiro = 0o755
const populacao: inteiro = 1_000_000
const pequeno: real = 1.25e-8
const piAprox: real = 3_141.592_653
const hexReal: real = 0x1.fp+3

Experimente: 01_tipos

// Declaração, valores primitivos e tipo de em execução.
var vazio: qualquer
const ativo: logico = verdadeiro
var idade: inteiro = 20
var medida: real = 2.5
escreva(vazio, ativo)
escreva(tipo de idade, " ", tipo de medida, " ", tipo de "olá", " ", tipo de ativo)

Ver exemplo completo e contrato de teste no GitHub

Experimente: 03_atribuicoes

var a: numero, b: numero = 1, 2
a, b = b, a // Os valores da direita são avaliados antes das escritas.
var contador: numero = 2
contador += 5
escreva(a, b, contador)
var destino: numero = 0
escreva(destino = 5)

Ver exemplo completo e contrato de teste no GitHub

Experimente: 25_escopos

var x: numero = 1
se verdadeiro {
    var x: numero = 2;
    escreva(x)
}

escreva(x)
funcao criar(): qualquer {
    retorna auxiliar
    funcao auxiliar(x: qualquer): qualquer {
        retorna x * 2
    }
}

escreva(criar()(4))

Ver exemplo completo e contrato de teste no GitHub

const impede reatribuir a variável, mas se ela guardar um vetor ou dicionário, você ainda pode alterar os itens lá dentro. Inteiros têm 64 bits verificados e reais usam ponto flutuante de 64 bits (não existe BigInt).

Operadores e ordem de avaliação

Contas matemáticas, comparações, lógica e operadores bit a bit funcionam do jeito que você espera — e sempre avaliam da esquerda para a direita, sem surpresas quando você ativa otimizações.

Comparando textos

Os operadores <, <=, > e >= funcionam também com textos, comparando pela ordem dos pontos de código Unicode em UTF-8. Textos menores que são prefixo vêm primeiro ("a" < "ab"). Misturar texto com número em comparações não faz conversão mágica escondida.

var letra: texto = '5'
se letra >= '0' e letra <= '9' {
    escreva('É um dígito')
}

Curto-circuito e efeitos previsíveis

e, ou e ?: só avaliam o lado direito quando realmente precisam, e retornam o próprio valor escolhido. Atribuições compostas (+=, -=, *=, /=, %=) e incrementos (++ / --) avaliam o destino uma única vez.

Experimente: 02_operadores

// Potência, divisão inteira, bits, comparação e curto-circuito.
escreva(2 ** 5, 100 \ 3, 5 & 3, 1 << 0)
escreva(3 != 4, falso e (1 / 0), nulo ?: 10)

Ver exemplo completo e contrato de teste no GitHub

Experimente: 35_bits_e_atribuicoes

var n: numero = 8
escreva(n | 1, n >> 3)
escreva(3 ^ 2, ~1, 5 & 3)
var a: numero = 9
a -= 1
a *= 2
a /= 4
a %= 3
escreva(++a + 1)

Ver exemplo completo e contrato de teste no GitHub

No CGD, apenas falso e nulo contam como falsos em condições; 0, "" e [] contam como verdadeiros. O operador ?: substitui apenas nulo. Divisão por zero e overflow lançam exceção (e quando são constantes, o compilador já avisa antes de rodar).

Condições, escolha e laços

Para tomar decisões no seu programa, use se/senao, ternário ? : ou escolha/caso. Para repetir tarefas, use enquanto, faca/enquanto, para ou para cada.

Decisões limpas com se, ternário e escolha

Blocos sempre usam chaves { }. No se e no enquanto, os parênteses em volta da condição são opcionais. No escolha, você pode empilhar vários casos que executam o mesmo bloco e usar padrao para o resto.

var idade: inteiro = 20
escreva(idade >= 18 ? "adulto" : "menor")

Percorrendo coleções com para cada

O para cada percorre vetores (elemento por elemento), textos (caractere Unicode por caractere) e dicionários (pares chave/valor). Você pode anotar o tipo do elemento direto no laço — e se não anotar, o compilador infere automaticamente quando conhece o tipo da coleção.

var numeros: inteiro[] = [10, 20, 30]
para cada n: inteiro em numeros {
    escreva(n)
}

Experimente: 04_condicionais

var idade: numero = 20
escreva(idade >= 18 ? "adulto" : "menor")
escolha 2 {
    caso 1: escreva("um")
    caso 2:
    caso 3: escreva("dois ou tres")
    padrao: escreva("outro")
}

Ver exemplo completo e contrato de teste no GitHub

Experimente: 05_lacos

para (var i: numero = 0; i < 4; i++) {
    se i == 1 {
        continua
    }

    se i == 3 {
        sustar
    }

    escreva(i)
}

fazer {
    escreva("feito")
}

enquanto falso
var soma: numero = 0
para cada item: inteiro em [1, 2, 3] {
    soma += item
}

escreva(soma)

Ver exemplo completo e contrato de teste no GitHub

Experimente: 34_lacos_variantes

var i: numero = 0
var primeiro: qualquer[] = fazer {
    i++;
    retorna i
}

enquanto i < 2
var segundo: qualquer[] = para cada valor: inteiro em [1, 2] {
    retorna valor * 2
}

var terceiro: qualquer[] = enquanto i > 0 {
    retorna i--
}

escreva(primeiro)
escreva(segundo)
escreva(terceiro)

Ver exemplo completo e contrato de teste no GitHub

sustar sai do laço ou do escolha; continua pula para a próxima volta. Mesmo quando você usa sustar, continua ou retorna, qualquer bloco finalmente no caminho continua sendo executado.

Laços como expressões

Em vez de criar um vetor vazio antes e ficar chamando .adicionar() dentro de um laço, você pode usar o próprio laço como expressão para montar o resultado.

Montando vetores direto no laço

Qualquer laço (para, enquanto, para cada) pode devolver um vetor se for usado do lado direito de uma atribuição ou dentro de uma expressão. Cada retorna dentro do corpo empurra mais um valor para o vetor final.

var quadrados = para (var i: inteiro = 0; i < 4; i++) {
    retorna i * i
}
escreva(quadrados) // [0, 1, 4, 9]

Experimente: 06_lacos_resultado

// Retornos dentro de uma expressão de laço acumulam os valores.
var quadrados: qualquer[] = para (var i: numero = 0; i < 4; i++) {
    retorna i * i
}

var i: numero = 0
var pares: qualquer[] = enquanto i < 3 {
    i++;
    retorna i * 2
}

escreva(quadrados)
escreva(pares)

Ver exemplo completo e contrato de teste no GitHub

Dentro de um laço usado como expressão, retorna adiciona um item ao vetor resultante em vez de encerrar a função externa.

Funções, assincronismo e rotinas paralelas

Funções organizam e reaproveitam lógica. No CGD você escreve funções normais, funções seta (=>), funções assíncronas (assincrona/aguardar) e tarefas paralelas em threads (rotina).

Funções normais, valores padrão e arrows (=>)

Declare funções com funcao (ou função), parâmetros opcionais com = valor e argumentos variáveis no final com ...nome. Se uma função terminar sem retorna, ela devolve nulo. Funções anônimas e arrows (=>) funcionam como callbacks sem captura.

funcao somar(a: inteiro, b: inteiro = 1): inteiro {
    retorna a + b
}
const dobrar: funcao = (x: inteiro): inteiro => x * 2

Funções assíncronas: assincrona, aguardar e Promessa

Uma funcao marcada como assincrona devolve automaticamente uma Promessa. Dentro dela, você usa aguardar para esperar temporizadores, requisições HTTP, sockets TCP ou outras promessas sem travar o resto do programa — tudo coordenado por um reactor epoll no runtime C.

Promessa também traz combinadores estáticos prontos: Promessa.resolvida, Promessa.rejeitada, Promessa.todas, Promessa.corrida, Promessa.qualquer e Promessa.todasResolvidas, além de cancelamento cooperativo (.cancelar()).

assincrona funcao buscarDados(): texto {
    const Tempo: qualquer = importar("cgd:assincrono").Tempo
    aguardar Tempo.dormir(10)
    retorna "pronto"
}

Paralelismo real: rotina, Tarefa e Canal

Quando você quer fazer trabalho pesado de CPU em paralelo em outro núcleo, use rotina minhaFuncao(args). Ela dispara a função num pool de threads nativo e devolve uma Tarefa, que você espera com aguardar.

Para evitar condições de corrida e bugs difíceis de rastrear, o compilador audita a função em tempo de compilação (E3401–E3404): rotinas só aceitam argumentos e retornos transferíveis (nulo, lógico, inteiro, real ou texto copiado) e não podem mexer em estado global mutável. Para trocar mensagens entre tarefas, use Canal e GrupoTarefas em cgd:assincrono.

const t1: Tarefa<inteiro> = rotina fib(12)
const t2: Tarefa<inteiro> = rotina fib(14)
escreva(aguardar t1, aguardar t2)

Experimente: 07_funcoes

funcao soma(a: inteiro, b: inteiro = a + 2): inteiro {
    retorna a + b
}

funcao reunir(primeiro: qualquer, ...resto: qualquer): qualquer {
    retorna [primeiro, ...resto]
}

escreva(soma(3))
escreva(reunir(1, ...[2, 3]))

Ver exemplo completo e contrato de teste no GitHub

Experimente: 08_funcoes_valores

funcao dobro(x: qualquer): qualquer {
    retorna x * 2
}

var operacao: funcao = dobro
funcao criar(): qualquer {
    // Esta função não captura nenhuma variável de criar().
    retorna funcao(x: qualquer): qualquer {
        retorna x + 4
    }
}

escreva(operacao(3))
escreva(criar()(5))
escreva(mapear([1, 2, 3], funcao(x: qualquer): qualquer {
    retorna x * 3
}))

Ver exemplo completo e contrato de teste no GitHub

Experimente: 41_assincronismo

assincrona funcao maisUm(valor: inteiro): inteiro {
    retorna valor + 1
}

assincrona funcao mostrar(): vazio {
    escreva("início")
    const futuro: Promessa<inteiro> = maisUm(10)
    const resultado = aguardar futuro
    escreva(resultado)
}

escreva("raiz")
mostrar()
escreva("continua")

Ver exemplo completo e contrato de teste no GitHub

Experimente: 42_rotinas

funcao fib(n: inteiro): inteiro {
    se n <= 1 {
        retorna n
    }

    retorna fib(n - 1) + fib(n - 2)
}

assincrona funcao produtor(canal: qualquer): vazio {
    para var i: inteiro = 1; i <= 5; i++ {
        aguardar canal.enviar(i * 10)
    }

    canal.fechar()
}

assincrona funcao principal(): vazio {
    const Async: qualquer = importar("cgd:assincrono")
    const t1: Tarefa<inteiro> = rotina fib(10)
    const t2: Tarefa<inteiro> = rotina fib(12)
    escreva(aguardar t1)
    escreva(aguardar t2)

    const ch: qualquer = Async.Canal(2)
    const envio: Promessa<vazio> = produtor(ch)
    var soma: inteiro = 0
    enquanto verdadeiro {
        tente {
            soma = soma + aguardar ch.receber()
        } pegue (erro: Excecao) {
            sustar
        }
    }

    aguardar envio
    escreva(soma)
    escreva(ch.fechado())
}

principal()

Ver exemplo completo e contrato de teste no GitHub

No CGD, funções nunca capturam variáveis externas (upvalues). Passe tudo por parâmetro ou use métodos de classe. Assincronismo e rotinas são recursos nativos do CGD, distintos da wiki base da Delégua.

Vetores, compreensão e fatias

Vetores guardam listas ordenadas de valores. Você pode tipar o vetor (inteiro[]), recortar fatias com passo (valores[::-1]), espalhar elementos (...lista) e criar listas filtradas em uma linha.

Literais, espalhamento (...) e compreensão

Use colchetes [1, 2, 3] para criar um vetor e ... para espalhar elementos dentro de outro vetor. Compreensões criam um vetor novo filtrando e transformando sem alterar o original.

var base: inteiro[] = [1, 2, 3]
var maior: inteiro[] = [...base, 4]
var pares = [x * 2 para cada x: inteiro em maior se x % 2 == 0]

Fatias com [inicio:fim:passo]

O fim da fatia é exclusivo. Você pode omitir início ou fim, e usar passo negativo para inverter rapidamente (valores[::-1]). Passo zero é bloqueado já na compilação (E3108).

Experimente: 09_vetores

var valores: qualquer[] = [3, 1, 2]
valores.ordenar()
escreva(valores, valores.somar())
var removidos: qualquer = valores.encaixar(1, 1, 7, 8)
escreva(removidos, valores)

Ver exemplo completo e contrato de teste no GitHub

Experimente: 10_compreensao_fatias

var valores: qualquer[] = [1, 2, 3, 4, 5]
escreva([x * 3 para cada x: inteiro em valores se x % 2 == 0])
escreva(valores[::-1], valores[::2])

Ver exemplo completo e contrato de teste no GitHub

Experimente: 22_contratos_aliases

var numeros: inteiro[] = [1]
var alias: qualquer = numeros
tente {
    alias.adicionar("texto")
}
pegue {
    escreva("bloqueado")
}

escreva(numeros)

Ver exemplo completo e contrato de teste no GitHub

Experimente: 30_metodos_vetor

var v: qualquer[] = [1, 2]
v.empilhar(3)
escreva(v.concatenar([4]).ordenar(funcao(a: qualquer, b: qualquer): qualquer {
    retorna b - a
}))
v.adicionar(4)
escreva(v.removerPrimeiro(), v.removerUltimo())
escreva(v.removerUltimo())
escreva(v.removerPrimeiro())
escreva([1, 2, 3].filtrarPor(funcao(x: qualquer): qualquer {
    retorna x < 3
}).mapear(funcao(x: qualquer): qualquer {
    retorna x * 3
}))

Ver exemplo completo e contrato de teste no GitHub

Métodos de vetor: adicionar, empilhar, tamanho, inclui/contem/contém, fatiar, mapear, filtrarPor, remover, removerPrimeiro, removerUltimo, inverter, somar, juntar, concatenar, encaixar e ordenar. Em vetores tipados (ex.: inteiro[]), o compilador já rejeita inserções de tipo errado estaticamente.

Dicionários, tuplas e clonagem

Dicionários associam chaves a valores; tuplas agrupam valores fixos que não podem ser alterados depois de criados. E quando você precisar de uma cópia independente, existe clonar().

Trabalhando com dicionários

Chaves podem ser texto, número, lógico ou nulo. Use .obter(chave, padrao) para ler com segurança e .contemChave(chave) para saber se a chave existe (mesmo quando o valor guardado for nulo). Outros métodos úteis: definir, remover, chaves, valores, itens, tamanho e limpar.

var perfil: dicionario = { nome: "Ana", pontos: 10 }
escreva(perfil.obter("nome", "Visitante"))
escreva(perfil.contemChave("pontos"))

Tuplas imutáveis e clonagem profunda

Crie tuplas com (1, "a") ou tupla(vetor) (de 2 a 10 itens). Além do índice [0], tuplas aceitam propriedades ordinais como .primeiro, .segundo até .decimo. Para copiar coleções aninhadas (inclusive com ciclos) sem compartilhar referências, use clonar(valor).

Experimente: 11_dicionarios

var original: dicionario = { a: 1 }

var dados: dicionario = { ...original, b: 2 }
// dados.obter("b")

const { a: qualquer, b: qualquer } = dados
escreva(a, b)

para cada { chave: texto, valor: inteiro } em { x: 7 } {
    escreva(chave, valor)
}

escreva("a" em dados)

Ver exemplo completo e contrato de teste no GitHub

Experimente: 12_tuplas

// Tuplas possuem acesso por índice e por propriedades ordinais.
var tuplaLiteral: tupla = [(1, "texto")]
var tipada: (numero, texto) = tupla([2, "outro"])
escreva(tuplaLiteral[0], tuplaLiteral.segundo)
escreva(tipada)

Ver exemplo completo e contrato de teste no GitHub

Experimente: 20_clonagem

var original: dicionario = { dados: [1] }

var copia: qualquer = clonar(original)
copia.dados.adicionar(2)
escreva(original.dados, copia.dados)
var ciclo: qualquer[] = []
ciclo.adicionar(ciclo)
var clonado: qualquer = clonar(ciclo)
escreva(clonado[0] == clonado)

Ver exemplo completo e contrato de teste no GitHub

Experimente: 31_metodos_dicionario

var d: dicionario = { b: 2, a: 1 }

escreva(d.chaves().ordenar().juntar("-"), d.valores().ordenar())
escreva(d.contém("a"), d.remover("a"), d.tamanho())
escreva(d.obter("a"))

Ver exemplo completo e contrato de teste no GitHub

Experimente: 37_dicionario_obter

var dados: dicionario = { "presente": nulo }
escreva(dados.obter("ausente", 42))
escreva(dados.obter("presente", 42))
escreva(dados.contemChave("presente"))
dados.definir("nome", "CGD")
var itens: qualquer[] = dados.itens()
dados.limpar()
escreva(tamanho(itens))
escreva(tamanho(dados))

Ver exemplo completo e contrato de teste no GitHub

Dicionários não garantem ordem de inserção ao iterar. Tentar modificar um item de uma tupla (t[0] = 3) agora é pego em tempo de compilação com o erro E3110.

Texto, Unicode e interpolação

Acentos, emojis e caracteres especiais funcionam nativamente em UTF-8. Os índices e .tamanho() contam caracteres (pontos de código Unicode), não bytes soltos.

Interpolação com $

Qualquer expressão dentro de ${...} em uma string é avaliada na ordem em que aparece e convertida para texto — inclusive expressões com aspas internas, como "valor=${mapa["chave"]}".

var cidade: texto = "São Paulo"
escreva("Bem-vindo a ${cidade}!")
escreva("ação"[1]) // ç

Experimente: 13_texto_unicode

escreva(tamanho("ação"), "ação"[1], "ação"[1:3])
escreva("  Olá árvore  ".aparar().maiusculo())
var n: numero = 2
escreva("valor ${n + 1}")

Ver exemplo completo e contrato de teste no GitHub

Experimente: 28_metodos_texto

// Busca, divisão, substituição e testes de caixa.
escreva("  a".apararInicio(), "á  ".apararFim())
escreva("a,b".dividir(","), "ação".substituir("ç", "s"))
escreva("ABC".tudoMaiusculo(), "abc".tudoMinusculo())

Ver exemplo completo e contrato de teste no GitHub

Textos são imutáveis — tentar fazer s[0] = "a" gera erro estático E3110. Métodos disponíveis: tamanho, inclui/contem/contém, fatiar/subtexto, aparar, apararInicio, apararFim, maiusculo, minusculo, tudoMaiusculo, tudoMinusculo, encontrar, dividir, substituir e concatenar.

Classes, herança, mescla e estáticos

Classes juntam dados e comportamento num só lugar. No CGD você conta com inicializadores por instância, herança (herda), composição por mixins (mescla), campos e métodos estáticos, privacidade e destrutores explícitos.

Atributos, defaults e inicializadores por objeto

Você pode dar valores iniciais direto nos campos da classe. Cada instância nova recebe sua própria avaliação — então um campo historico: inteiro[] = [] nunca é compartilhado por acidente entre dois objetos. Os campos da classe base inicializam primeiro, depois os da derivada e por fim roda o construtor.

classe Contador {
    estatico totalCriados: inteiro = 0
    valor: inteiro = 1
    historico: inteiro[]

    construtor() {
        Contador.totalCriados++
    }
}

Herança (herda) e composição (mescla)

Use herda para especializar uma classe base (chamando super quando quiser reaproveitar a implementação do pai). Quando quiser reutilizar métodos e campos de várias classes sem cair em herança múltipla, use classe MinhaClasse mescla MixinA, MixinB.

Cada mixin mantém sua própria privacidade, seus inicializadores de campo funcionam automaticamente e eInstanciaDe reconhece tanto a hierarquia de herança quanto os mixins e interfaces.

Privacidade, acessores e destrutor explícito

Agrupe membros em publico { }, protegido { } ou privado { }. Propriedades aceitam acessores personalizados obter() e definir(valor). Para liberar recursos determinísticos, declare destrutor(): vazio e chame destruir(objeto) dentro de um bloco finalmente — o Boehm GC cuida da memória, não de destrutores Delégua.

Experimente: 14_classes

classe Ponto {
    x: numero

    construtor(x: numero) {
        isto.x = x
    }

    dobro(): qualquer {
        retorna isto.x * 2
    }
}

var ponto: Ponto = Ponto(3)
escreva(ponto.x, ponto.dobro())
ponto.x = 4
escreva(ponto.dobro())

Ver exemplo completo e contrato de teste no GitHub

Experimente: 15_heranca

classe Base {
    protegido {
        x: numero
    }

    construtor(x: qualquer) {
        isto.x = x
    }

    valor(): qualquer {
        retorna isto.x
    }
}

classe Filha herda Base {
    construtor(x: qualquer) {
        super(x + 1)
    }

    valor(): qualquer {
        retorna super.valor() * 2
    }

    dado(): qualquer {
        retorna isto.x
    }
}

var filha: Filha = Filha(3)
var metodo: funcao = filha.valor // Receptor explícito, gerenciado pelo GC.
escreva(metodo(), filha.dado())
escreva(filha.eInstanciaDe(Base))

Ver exemplo completo e contrato de teste no GitHub

Experimente: 16_privacidade_acessores

classe Conta {
    privado {
        _saldo: numero
    }

    saldo: numero {
        obter() {
            retorna isto._saldo
        }
        definir(valor: qualquer) {
            isto._saldo = valor * 2
        }
    }

    construtor() {
        isto._saldo = 0
    }
}

var conta: Conta = Conta()
conta.saldo = 3
escreva(conta.saldo)

Ver exemplo completo e contrato de teste no GitHub

Experimente: 32_objeto_e_metodos

classe Pessoa {
    nome: texto

    construtor(nome: qualquer) {
        isto.nome = nome
    }

    paraTexto(): qualquer {
        retorna "Pessoa: ${isto.nome}"
    }
}

var p: Pessoa = Pessoa("Ada")
escreva(p.tipo())
escreva(p.respondeA("paraTexto"), p.eInstanciaDe(Objeto))
escreva(p)

Ver exemplo completo e contrato de teste no GitHub

Experimente: 36_destrutores

classe Base {
    destrutor(): vazio {
        escreva("base")
    }
}

classe Filha herda Base {
    destrutor(): vazio {
        escreva("filha")
    }
}

var recurso: Filha = Filha()
tente {
    assercao(verdadeiro)
} finalmente {
    destruir(recurso)
}

destruir(recurso)
escreva("fim")

Ver exemplo completo e contrato de teste no GitHub

Experimente: 39_inicializacao

var n: numero
var texto: texto
var logico: logico
escreva(n, texto, logico)
classe Base {
    valor: inteiro = 7
    itens: inteiro[]
}

classe Filha herda Base {
    copia: inteiro = isto.valor
}

var primeira: Filha = Filha()
var segunda: Filha = Filha()
primeira.itens.adicionar(1)
escreva(primeira.copia)
escreva(tamanho(segunda.itens), tamanho(primeira.itens))
var ch: texto = "5"
escreva(ch >= '0' e ch <= '9', "ação" > "a")

Ver exemplo completo e contrato de teste no GitHub

Experimente: 43_estaticos_mescla

funcao de decorador triplicar(original: funcao): funcao {
    retorna funcao(alvo: qualquer, x: inteiro): inteiro {
        retorna x * 3
    }
}

classe Etiquetavel {
    prefixo: texto = "Etiqueta:"

    rotulo(nome: texto): texto {
        retorna isto.prefixo + nome
    }
}

classe Registro mescla Etiquetavel {
    estatico criados: inteiro = 0
    nome: texto

    construtor(nome: texto) {
        isto.nome = nome
        Registro.criados = Registro.criados + 1
    }

    @triplicar
    escalar(x: inteiro): inteiro {
        retorna x
    }
}

const a: Registro = Registro("Ana")
const b: Registro = Registro("Bia")
escreva(Registro.criados)
escreva(a.rotulo(a.nome))
escreva(b.eInstanciaDe(Etiquetavel))
escreva(a.escalar(10))

Ver exemplo completo e contrato de teste no GitHub

Classes são declaradas no nível do módulo. Campos precisam ser declarados na classe; acessar um campo ou método que não existe gera erro estático E3109 com sugestão do nome mais parecido (preservando acesso polimórfico a subclasses).

Exceções e limpeza

Erros acontecem — arquivo que não existe, JSON inválido, divisão por zero. Use tente e pegue para lidar com eles sem derrubar o programa, e finalmente para garantir a limpeza.

tente, pegue tipado e finalmente

Use falhar para lançar um erro (texto ou instância de Excecao/subclasse). Você pode ter vários blocos pegue filtrando por tipo de exceção. O bloco finalmente sempre roda — tenha dado certo, dado erro ou executado um retorna.

tente {
    falhar "entrada inválida"
} pegue (erro: Excecao) {
    escreva(erro.mensagem)
} finalmente {
    escreva("limpeza garantida")
}

Erros estáticos dentro de tente/pegue

Quando o compilador prova que uma operação sempre vai falhar (como 1 / 0), ele barra a compilação com E3101. Mas se essa linha estiver dentro de um tente/pegue, ele rebaixa para aviso (W3101) — assim seus testes de tratamento de erro continuam compilando normalmente.

Experimente: 17_excecoes

tente {
    falhar "proposital"
} pegue (erro: Excecao) {
    escreva(erro.mensagem)
} finalmente {
    escreva("limpeza")
}

tente {
    escreva(1 / 0)
} pegue (erro) {
    escreva(erro)
}

Ver exemplo completo e contrato de teste no GitHub

Experimente: 18_finalmente_retorno

funcao obter(): qualquer {
    tente {
        retorna 3
    } finalmente {
        escreva("fim")
    }
}

escreva(obter())
para (var i: numero = 0; i < 2; i++) {
    tente {
        continua
    } finalmente {
        escreva("loop")
    }
}

Ver exemplo completo e contrato de teste no GitHub

Experimente: 19_excecoes_tipadas

classe MeuErro herda Excecao {
}

tente {
    falhar MeuErro("meu erro")
}
pegue (erro: MeuErro) {
    escreva(erro)
}
pegue {
    escreva("outro erro")
}

Ver exemplo completo e contrato de teste no GitHub

Se uma exceção não for capturada por nenhum pegue, o programa encerra com código 1 e exibe o diagnóstico visual R0001 apontando arquivo, linha e coluna.

Módulos estáticos e ~/.delegua/cgd

Divida projetos maiores em vários arquivos .delegua ou importe bibliotecas prontas com importar("cgd:nome"). Tudo é resolvido estaticamente na compilação, com detecção de ciclos e cache automático.

Módulos locais e bibliotecas em ~/.delegua/cgd

Para importar um arquivo do seu projeto, passe o caminho relativo terminado em .delegua: importar("util.delegua").

Para bibliotecas cgd:, o CGD NÃO usa uma lista fixa no compilador: ele procura diretamente .delegua dentro de ~/.delegua/cgd (ou na pasta definida pela variável de ambiente CGD_LIBS_DIR), usando bibliotecas/ ao lado do executável apenas como fallback. Se você salvar ~/.delegua/cgd/minhalib.delegua, importar("cgd:minhalib") funciona na hora — e já aparece no autocomplete do VS Code!

const JSON: qualquer = importar("cgd:json").JSON
const util: qualquer = importar("./util.delegua")

Namespaces, ciclos e identidade de classes

Cada módulo é inicializado uma única vez e expõe suas funções, variáveis e classes como namespace. O compilador detecta ciclos (E2001), verifica se o membro importado realmente existe (E3109) e garante que duas classes com o mesmo nome em módulos diferentes nunca sejam confundidas.

Experimente: 01_importacao

var calculos: qualquer = importar("lib/calculos.delegua")
var outraReferencia: qualquer = importar("./lib/calculos.delegua")
escreva(calculos.soma(3), outraReferencia.versao, calculos.Valor(4).dado)

Ver exemplo completo e contrato de teste no GitHub

Experimente: 08_otimizacao_modulos

// As duas importações compartilham o módulo, sem repetir inicialização.
var primeiro: qualquer = importar("biblioteca.delegua")
var segundo: qualquer = importar("biblioteca.delegua")
escreva(primeiro.dobro(2 + 2))

Ver exemplo completo e contrato de teste no GitHub

Caminhos em importar() precisam ser literais conhecidos na compilação. Tentativas de travessia em cgd: (como cgd:../segredo) são bloqueadas com E2003.

Funções nativas e entrada/saída

Mesmo sem importar nenhum módulo, você já tem funções básicas prontas para ler do teclado, escrever no terminal, converter tipos e transformar listas.

escreva, leia e conversões

escreva imprime valores e pula linha; leia lê uma linha da entrada padrão (com pergunta opcional). Para converter entre tipos, use texto(x), inteiro(x), real(x) e numero(x) — se o texto não for um número válido, a conversão lança uma exceção tratável.

var entrada: texto = leia("Digite um número: ")
tente {
    escreva(inteiro(entrada) * 2)
} pegue {
    escreva("Isso não é um inteiro válido")
}

Funções globais de apoio

Você também conta com tamanho, clonar, mapear, filtrar, paraCada, todosEmCondicao, ordenar, aleatorio, aleatorioEntre, decoradores, destruir e a expressão tipo de.

Experimente: 21_biblioteca

escreva(inteiro("12"), real(".5"), 1234.5689.formatar())
funcao par(x: qualquer): qualquer {
    retorna x % 2 == 0
}

escreva(filtrar([1, 2, 3, 4], par), todosEmCondicao([2, 4], par))
paraCada([1, 2], funcao(x: qualquer): qualquer {
    escreva(x * 2)
})

Ver exemplo completo e contrato de teste no GitHub

Experimente: 27_entrada

var nome: texto = leia("Nome: ")
escreva("Olá, ${nome}")

Ver exemplo completo e contrato de teste no GitHub

Experimente: 29_metodos_numero

escreva((-3).absoluto(), (2.3).arredondarParaCima(), 2.5.formatar(2))
escreva(1234.5689.formatar({ minimoCasasDecimais: 2, maximoCasasDecimais: 3 }))

Ver exemplo completo e contrato de teste no GitHub

Experimente: 33_aleatoriedade

// A saída é determinística: verificamos os intervalos, não um valor sorteado.
para (var i: numero = 0; i < 100; i++) {
    var real: real = aleatorio()
    var inteiro: numero = aleatorioEntre(-3, 4)
    assercao real >= 0 e real < 1
    assercao inteiro >= -3 e inteiro < 4
}

escreva("intervalos validados")

Ver exemplo completo e contrato de teste no GitHub

Números também oferecem os métodos .absoluto(), .arredondarParaBaixo(), .arredondarParaCima() e .formatar().

Decoradores e asserções

Use @decoradores para anexar metadados ou envolver funções e métodos com comportamento extra (como logs ou validações), e assercao() para checar condições importantes em execução.

Metadados declarativos e envelopes

Um decorador simples como @rota(caminho="/usuarios") guarda dados constantes que podem ser consultados com decoradores(alvo). Se você declarar uma funcao de decorador, ela envolve automaticamente a função ou método decorado — recebendo a função original e devolvendo a nova versão.

funcao de decorador dobrarResultado(original: funcao): funcao {
    retorna funcao(alvo: qualquer, x: inteiro): inteiro {
        retorna original(alvo, x) * 2
    }
}

Asserções em runtime

assercao(condicao, "mensagem opcional") verifica uma garantia do seu código e lança uma exceção tratável caso falhe.

assercao(2 + 2 == 4, "a aritmética falhou")

Experimente: 23_decoradores

@minimo(valor = 0)
classe Medida {
    lado: numero
}

escreva(decoradores(Medida).classe[0].nome)
funcao alternativa(): qualquer {
    retorna 9
}

funcao de decorador trocar(original: qualquer): qualquer {
    retorna alternativa
}

@trocar
funcao obter(): qualquer {
    retorna 1
}

escreva(obter())

Ver exemplo completo e contrato de teste no GitHub

Experimente: 24_assercoes

assercao 2 + 2 == 4
escreva("validado")
tente {
    asserção(falso, "mensagem personalizada")
}
pegue (erro) {
    escreva(erro)
}

Ver exemplo completo e contrato de teste no GitHub

Experimente: 43_estaticos_mescla

funcao de decorador triplicar(original: funcao): funcao {
    retorna funcao(alvo: qualquer, x: inteiro): inteiro {
        retorna x * 3
    }
}

classe Etiquetavel {
    prefixo: texto = "Etiqueta:"

    rotulo(nome: texto): texto {
        retorna isto.prefixo + nome
    }
}

classe Registro mescla Etiquetavel {
    estatico criados: inteiro = 0
    nome: texto

    construtor(nome: texto) {
        isto.nome = nome
        Registro.criados = Registro.criados + 1
    }

    @triplicar
    escalar(x: inteiro): inteiro {
        retorna x
    }
}

const a: Registro = Registro("Ana")
const b: Registro = Registro("Bia")
escreva(Registro.criados)
escreva(a.rotulo(a.nome))
escreva(b.eInstanciaDe(Etiquetavel))
escreva(a.escalar(10))

Ver exemplo completo e contrato de teste no GitHub

Envelopes de decoradores funcionam em funções livres, métodos de instância e métodos estáticos (sem captura de ambiente). Asserções nunca são apagadas pelo -o.

Otimização (-o) e CTFE (@puro)

Passar -o ativa otimizações do compilador e -O2 no Clang/GCC. Regra de ouro do CGD: otimizar nunca pode mudar o comportamento observável, apagar efeitos ou esconder exceções.

Calculando resultados na compilação com @puro

Coloque o decorador @puro acima de uma função livre ou de um método estático que só depende dos próprios parâmetros. Com -o, quando ela for chamada com valores constantes, a VM interna do CGD calcula o resultado durante a compilação e substitui direto no código C gerado. A sintaxe antiga //>puro segue aceita por compatibilidade, mas @puro é a forma recomendada.

@puro
funcao fatorial(n: inteiro): inteiro {
    se n <= 1 { retorna 1 }
    retorna n * fatorial(n - 1)
}
const resultado: inteiro = fatorial(6) // já vira 720 com -o

O que o otimizador simplifica com segurança

O gerenciador de passes roda até atingir ponto fixo: dobra operações constantes (aritmética, unários, comparações, textos), propaga constantes tipadas com segurança, simplifica curto-circuito (verdadeiro e x, falso ou x) e remove caudas comprovadamente inalcançáveis — preservando blocos finalmente e efeitos colaterais.

Experimente: 26_ctfe

// A VM é usada na compilação, não na execução do binário final.
//>puro
funcao fibonacci(n: inteiro): inteiro {
    se n < 2 {
        retorna n
    }

    retorna fibonacci(n - 1) + fibonacci(n - 2)
}

escreva(fibonacci(10))

Ver exemplo completo e contrato de teste no GitHub

Experimente: 01_constantes_escopos

// A propagação usa a declaração resolvida, preservando o sombreamento.
const valor: numero = 2
se verdadeiro {
    const valor: numero = 9
    escreva(valor + 1)
}

escreva(valor + 1)

Ver exemplo completo e contrato de teste no GitHub

Experimente: 02_efeitos

// Mesmo com -o, multiplicar por zero não elimina a avaliação da função.
funcao calcular(): qualquer {
    escreva("efeito")
    retorna 7
}

escreva(calcular() * 0)

Ver exemplo completo e contrato de teste no GitHub

Experimente: 03_fluxo

// --verificar avisa sobre a cauda inalcançável; finalmente permanece em -o.
funcao resultado(): qualquer {
    tente {
        retorna (2 + 3) * 4
        escreva("inalcançável")
    } finalmente {
        escreva("limpeza")
    }
}

escreva(resultado())

Ver exemplo completo e contrato de teste no GitHub

Experimente: 04_curto_circuito

funcao proibida(): qualquer {
    falhar "Não deveria executar"
}

escreva(verdadeiro ? 7 : proibida(), falso e proibida(), verdadeiro ou proibida(), nulo ?: 8)

Ver exemplo completo e contrato de teste no GitHub

Experimente: 07_metodos_e_padroes

// Os passes também visitam métodos, valores padrão e funções anônimas.
classe Medida {
    dobro(valor: qualquer = 1 + 1): qualquer {
        retorna valor * 2
    }
}

var calcular: funcao = funcao(valor: qualquer = 3 + 4): qualquer {
    retorna valor
}

escreva(Medida().dobro(), calcular())

Ver exemplo completo e contrato de teste no GitHub

Experimente: 09_ctfe_fluxo_escopos

// A VM preserva senão, slots locais, parâmetros mutáveis e ordem de argumentos.
//>puro
funcao escolher(condicao: qualquer): qualquer {
    se condicao {
        retorna 1
    } senao {
        retorna 2
    }
}

//>puro
funcao combinar(a: qualquer, b: qualquer): qualquer {
    retorna a * 10 + b
}

//>puro
funcao calcular(): qualquer {
    var valor: numero = 1
    se verdadeiro {
        var valor: numero = 99
    }

    retorna combinar(valor++, valor++)
}

escreva(escolher(falso), calcular())

Ver exemplo completo e contrato de teste no GitHub

Experimente: 10_ctfe_excecao

// Uma falha da CTFE preserva a chamada para permitir tratamento em execução.
//>puro
funcao dividir(valor: qualquer): qualquer {
    retorna 1 / valor
}

tente {
    dividir(0)
} pegue (erro) {
    escreva("tratado")
}

Ver exemplo completo e contrato de teste no GitHub

Experimente: 11_ctfe_contrato

// A otimização não pode remover a validação de inteiro, nem em funções puras.
//>puro
funcao incrementar(valor: inteiro) {
    retorna valor + 1
}

escreva(incrementar(2.5))

Ver exemplo completo e contrato de teste no GitHub

Se uma função @puro ultrapassar o limite de passos na compilação ou lançar erro, o CGD simplesmente mantém a chamada normal em runtime. A sintaxe antiga //>puro continua funcionando por compatibilidade.

Diagnósticos, códigos de erro e CLI

Quando algo dá errado, o CGD mostra exatamente onde está o problema, dá um código estável (como E3109) e muitas vezes já sugere o nome certo. Você ainda pode pedir explicação detalhada direto no terminal.

Consultando um código de erro

Viu um erro como E3109 ou E3403 e não entendeu de primeira? Rode cgd --explicar CODIGO no terminal para ler o motivo e como corrigir. Para scripts e editores, --diagnosticos=json devolve tudo estruturado em JSON Lines.

cgd programa.delegua --verificar
cgd --explicar E3109
cgd programa.delegua --verificar --diagnosticos=json

Experimente: 05_diagnosticos

// Dois erros independentes: o parser recupera e reporta os dois.
var primeiro: qualquer =;
var segundo: qualquer =;

Ver exemplo completo e contrato de teste no GitHub

Experimente: 06_sugestao

var mensagem: texto = "Olá"
escreva(mensage)

Ver exemplo completo e contrato de teste no GitHub

Experimente: 12_divisao_estatica

const zero: inteiro = 3 - 3
escreva(10 / zero)

Ver exemplo completo e contrato de teste no GitHub

Experimente: 13_indice_unicode

// 'ação' tem quatro pontos de código; o maior índice positivo é 3.
escreva("ação"[4])

Ver exemplo completo e contrato de teste no GitHub

Experimente: 14_falha_tratada

// Uma operação deliberadamente inválida dentro de pegue recebe aviso W3101.
// A exceção continua tratável, e a localização não exige chamada por linha.
tente {
    escreva(1 / 0)
} pegue (erro) {
    escreva("tratado")
}

Ver exemplo completo e contrato de teste no GitHub

Códigos de diagnóstico

CódigoMensagemO que fazer
R0001%sFalha dinâmica do runtime; consulte a operação e a localização informadas. Tipos dinâmicos, aliases e entrada externa continuam validados em execução.
E0001%sDiagnóstico legado; consulte a mensagem e a posição.
W0001%sAviso legado; consulte a mensagem e a posição.
H0001%sInformação complementar de um diagnóstico.
E0002Limite de diagnósticos atingido; corrija os erros anteriores.O limite protege contra uma cascata de erros.
E9001%sVerifique arquivos, opções, dependências e a toolchain configurada.
E2001Ciclo de importação detectado: %sQuebre a dependência circular mostrada pela cadeia de importação.
E2002Limite de recursos de carregamento de módulos excedido.Divida o grafo; os limites de tamanho e quantidade são documentados.
E2003%s
Importado por: %sConfira o caminho literal relativo ao módulo que importa.
W4002Carregamento dinâmico/NPM/FFI não é suportado por segurança.Use fontes .delegua conhecidas na compilação.
E4002Importe um módulo fonte .delegua.Importação de código nativo ou carregado dinamicamente é excluída.
E1000Fim inesperado do arquivo; verifique delimitadores e expressões incompletas.Feche os delimitadores e complete a última expressão.
E1001%sA mensagem descreve o token ou expressão esperado; o parser tenta recuperar em outro comando.
E3002Incompatibilidade de tipo: era esperado '%s' mas foi recebido '%s'.Use um tipo compatível com o contrato declarado.
W4001Captura externa de '%s' detectada: exigiria upvalues, recurso desabilitado por segurança.Passe estado por parâmetros ou receptor explícito.
E4001A captura foi bloqueada; passe o valor como parâmetro explícito.Capturas de ambiente são excluídas deliberadamente do perfil compilado.
E1002Arquivo fonte não contém UTF-8 válido.Salve a fonte como UTF-8.
E1003Limite de aninhamento sintático excedido.Divida expressões ou blocos profundamente aninhados.
E1005Literal numérico inválido ou fora do intervalo.Literais inteiros exigem 64 bits; literais reais precisam ser finitos e representáveis em 64 bits.
E1004Limite estrutural da AST excedido; divida a expressão ou o módulo.O frontend limita profundidade e quantidade de nós antes dos passes recursivos.
E3001O símbolo '%s' não foi declarado.Verifique escopo e grafia; funções não capturam ambientes externos.
E3011Campos estáticos ainda não são suportados; declare um método estático.Esta versão oferece campos de instância e métodos estáticos; a ausência de campos estáticos não é uma exclusão de segurança.
E3012Construtor não pode ser estático.O construtor inicializa uma instância gerenciada e recebe isto; use outro nome para uma fábrica estática.
H3001Você quis dizer '%s'?Sugestão determinística de nome visível no escopo.
W3001Código inalcançável após transferência de controle.Remova ou reorganize a cauda que não executa.
W3002Função com retorno tipado pode terminar sem retornar valor; o retorno implícito é nulo.Garanta um retorno nos caminhos relevantes.
E3101Divisão ou módulo por zero demonstrável em compilação.O denominador é uma expressão constante igual a zero.
E3102Resultado inteiro fora do intervalo de 64 bits.Altere o cálculo ou use valores reais quando apropriado.
E3103Índice constante inválido: %s.Índices negativos são aceitos dentro dos limites da coleção.
E3104Incompatibilidade de tipo demonstrável: esperado '%s', recebido '%s'.Contratos explícitos não são removidos pela otimização.
E3105Operação demonstravelmente inválida: %s.Use os tipos e limites aceitos pelo runtime.
E3106Conversão literal inválida para '%s'.Valide o texto de entrada ou trate dados recebidos em execução.
E3107Deslocamento constante fora do intervalo [0, 63].A quantidade de bits precisa estar dentro dos limites de 64 bits.
E3108O passo constante de uma fatia não pode ser zero.Use um passo positivo ou negativo diferente de zero.
E3109Membro '%s' não existe em '%s'.Verifique o nome do método, campo ou exportação disponível para este tipo.
E3110Não é possível modificar elemento de '%s' imutável.Textos e tuplas são imutáveis; crie um novo valor ou utilize um vetor.
E3111Operação '%s' inválida sobre valor comprovadamente nulo.Verifique se o valor não é nulo antes de acessar membros, indexar ou chamar.
E3112O valor do tipo '%s' não pode ser chamado como função.Apenas funções, métodos e classes construtíveis podem ser invocados.
E3014Membro '%s' não é acessível neste contexto.Respeite a visibilidade público, protegido ou privado da declaração que oculta as herdadas.
E3015Membro '%s' exige uma instância.Instancie a classe antes de acessar campos e métodos de instância.
E3016A função '%s' espera entre %s e %s argumentos; recebeu %s.Respeite argumentos obrigatórios, opcionais e variáveis da função ou método.
E3017%sO destino precisa ser modificável; funções, constantes e o receptor isto não podem ser reatribuídos.
E3201Função pura depende do estado externo '%s'.Passe o valor por parâmetro; a CTFE não lê nem modifica variáveis externas à função.
E3013Destrutor deve ser público, de instância, sem parâmetros e retornar vazio.Declare destrutor(): vazio e use destruir(objeto) em finalmente para liberar recursos explicitamente.
E3301Construção assíncrona fora de um contexto permitido.Aguardar exige corpo assincrono. Defaults, inicializadores, acessores, ciclo de vida e assinaturas FFI são síncronos.
E3302Aguardar exige Promessa ou Tarefa; recebeu '%s'.Uma operação síncrona não se torna assíncrona por aguardar. Use uma função assincrona ou rotina.
E3303Função assíncrona não aceita avaliação pura/CTFE.O loop e as continuações só executam no programa nativo, nunca no compilador ou editor.
E3304Método não preserva o efeito assíncrono do contrato.Implementação e override devem manter assincrona e o tipo de resultado declarado.
E3305Construção ainda não suportada no lowering assíncrono: %s.A implementação incremental rejeita esta construção explicitamente; não há fallback bloqueante.
E3306Resultado vazio de aguardar não pode ser usado como valor.Use aguardar como comando quando a Promise é Promessa.
E3307Limite de recursos da IR assíncrona excedido.Divida a função: até 100000 instruções/slots, 2000000 fatos de vivacidade e 50000000 visitas de instrução/fato por análise.
E3401Rotina exige chamada direta a função de topo ou método estático conhecido, sem captura.Chame diretamente uma função declarada no módulo ou método estático de classe gerenciada.
E3402Função '%s' não é segura para execução paralela em rotina: %s.Rotinas não podem acessar globais mutáveis, FFI, I/O síncrono ou chamadas indiretas sem contrato.
E3403Rotina aceita apenas argumentos e retorno transferíveis (nulo, lógico, inteiro, real ou texto); recebeu '%s'.Transfira apenas valores escalares ou textos copiados; coleções e objetos mutáveis não atravessam threads.
E3404Função assíncrona não pode ser iniciada diretamente com rotina; use chamada normal e aguardar.Corrotinas assíncronas executam no loop cooperativo da thread principal, não no pool paralelo.

Os códigos E3101–E3112 cobrem segurança estática (e W3101–W3112 quando estão dentro de tente/pegue). O LSP no VS Code usa exatamente os mesmos diagnósticos e oferece correção rápida (quick-fix) para sugestões H3001.

Exclusões de segurança

Para manter o compilador previsível e livre de comportamento mágico difícil de depurar, alguns recursos ficam bloqueados de propósito. Veja os exemplos de como o CGD responde a cada caso.

O que é recusado por segurança

Capturas de ambiente (upvalues), eval, pacotes NPM, importação com caminho calculado em runtime e travessia de diretórios em cgd: (cgd:../...) são bloqueados. FFI C via @definicao é permitida somente com declaração explícita — nunca por conversão implícita de ponteiros crus.

Experimente: 01_captura_local

funcao criar(x) {
    retorna funcao() {
        retorna x
    }

    // Captura implícita proibida.
}

Ver exemplo completo e contrato de teste no GitHub

Experimente: 02_captura_global

var externo: inteiro = 1
funcao obter() {
    retorna externo
}

Ver exemplo completo e contrato de teste no GitHub

Experimente: 03_ffi

// Uma classe estrangeira sem assinatura/biblioteca explícita é inválida.
classe estrangeira Biblioteca {
}

Ver exemplo completo e contrato de teste no GitHub

Experimente: 04_importacao_dinamica

var caminho: texto = "modulo.delegua"
var modulo: qualquer = importar(caminho)

Ver exemplo completo e contrato de teste no GitHub

Experimente: 07_tupla_imutavel

var t: tupla = tupla([1, 2])
t[0] = 3

Ver exemplo completo e contrato de teste no GitHub

Funções anônimas e arrows sem captura funcionam perfeitamente; o bloqueio é apenas contra captura implícita de variáveis de fora.

Plataformas e toolchain C

O ambiente oficialmente testado hoje é Linux x86_64. O compilador aceita flags para trocar compilador C e preparar outros alvos, mas só declaramos suporte ao que foi validado de verdade.

Escolhendo Clang, GCC ou outro alvo

Por padrão o CGD detecta Clang ou GCC no sistema. Você pode fixar o compilador com CC=gcc ou --cc gcc, além de ajustar --target, --sysroot, --runtime-object, --cflag e --ldflag quando estiver montando um ambiente personalizado.

Windows, macOS e compilação cruzada ainda exigem runtime compilado e validação nativa antes de serem anunciados como suportados.

Bibliotecas cgd:* (Web, Dados, Cripto e Sistema)

O CGD vem com 24 módulos prontos instalados em ~/.delegua/cgd. Você importa apenas o que precisa com importar("cgd:nome") e o LSP já completa os nomes e métodos no VS Code.

Mapa completo dos 24 módulos em ~/.delegua/cgd

RecursoComo funciona
cgd:servidorServidor HTTP/1.1 com rotas, parâmetros, JSON, middlewares e modo concorrente epoll (escutarAsync + keep-alive).
cgd:redeCliente HTTP síncrono e assíncrono sobre libcurl (ClienteHTTP, RespostaHTTP, obter/enviar/enviarJSON).
cgd:socketsSockets TCP/UDP, resolução DNS e suporte a IPv6 (OuvinteTCP, Conexao, SocketUDP, resolverDNS).
cgd:assincronoTempo.dormir, HTTP e TCP assíncronos sobre epoll, Canal limitado e GrupoTarefas.
cgd:jsonParser e serializador JSON em Delégua puro com limites de profundidade e navegação por caminho.
cgd:sqliteBanco SQLite (libsqlite3) com consultas parametrizadas, transações e fechamento explícito.
cgd:bytesBuffer binário nativo (Bytes) para manipular bytes, hex, base64 e fatiamento sem depender de texto UTF-8.
cgd:criptoHashes SHA-256/SHA-512, HMAC e bytes aleatórios criptográficos sobre OpenSSL (libcrypto).
cgd:compressaoCompressão e descompressão gzip/deflate (zlib) com teto contra bombas de descompressão.
cgd:arquivosLeitura, escrita, linhas, JSON, cópia e remoção de arquivos regulares com limite seguro de memória.
cgd:processo / cgd:ambiente / cgd:sistemaExecução de subprocessos sem shell (argv separado + timeout), variáveis de ambiente e dados do sistema.
cgd:tempoRelógios, Duracao, Cronometro, dormirAsync e calendário DataHora.
cgd:io / cgd:cli / cgd:logEntrada/saída estruturada, parser de argumentos de linha de comando e logger estruturado.
cgd:textos / cgd:colecoes / cgd:caminhosUtilitários de string, transformações de vetores (agrupar, reduzir, particionar, blocos) e caminhos POSIX.
cgd:matematica / cgd:estatistica / cgd:algoritmosFunções matemáticas (libm), média/mediana/variância/desvio padrão, busca binária e CRC32.
cgd:nativoPrimitivas da ABI gerenciada usadas internamente para construir as bibliotecas acima.

Experimente: json_classe

var biblioteca: qualquer = importar("../../bibliotecas/json.delegua")
var dados: qualquer = biblioteca.JSON.analisar('{"nome":"CGD","versao":1}')

escreva(biblioteca.JSON.serializar(dados))

var documento: qualquer = biblioteca.JSON(dados)
escreva(documento.obter("nome"))
escreva(documento.definir("versao", 2).texto())

Ver exemplo completo e contrato de teste no GitHub

Experimente: rede

// Não faz requisições externas: introspecção e codificação são locais.
var rede: qualquer = importar("../../bibliotecas/rede.delegua")
escreva(rede.escapar("a b/c"))
escreva(rede.decodificar("a%20b%2Fc"))
escreva(tamanho(rede.opcoes()) > 100)

Ver exemplo completo e contrato de teste no GitHub

Experimente: colecoes

var biblioteca = importar("../../bibliotecas/colecoes.delegua")
escreva(biblioteca.Colecoes.unicos([1, 2, 1, 3, 2]))
escreva(biblioteca.Colecoes.intervalo(5, 0, -2))

var colecoes: qualquer = importar("cgd:colecoes").Colecoes
funcao par(valor: inteiro): logico {
    retorna valor % 2 == 0
}

var grupos: tupla = colecoes.particionar([1, 2, 3, 4], par)
escreva(grupos[0])
escreva(grupos[1])
escreva(colecoes.blocos([1, 2, 3, 4, 5], 2))

Ver exemplo completo e contrato de teste no GitHub

Experimente: json_navegacao

var json: qualquer = importar("cgd:json")
var documento: qualquer = json.JSON.deTexto('{"pessoa":{"nome":"Ana"},"valor":null}')
escreva(documento.caminho(["pessoa", "nome"]))
escreva(documento.obter("ausente", 7))
escreva(documento.obter("valor", 7))
var copia: qualquer = documento.copiar()
copia.definir("novo", verdadeiro)
escreva(documento.contem("novo"))

Ver exemplo completo e contrato de teste no GitHub

Experimente: arquivos

var arquivos: qualquer = importar("cgd:arquivos")
var arquivo: qualquer = arquivos.Arquivo("dados.txt")
// Instanciar não abre nem modifica o arquivo. I/O só acontece por chamada explícita.
escreva(arquivo.caminho())

Ver exemplo completo e contrato de teste no GitHub

Experimente: bytes_cripto_sqlite

const Bytes: qualquer = importar("cgd:bytes").Bytes
const Cripto: qualquer = importar("cgd:cripto").Cripto
const Comp: qualquer = importar("cgd:compressao").Compressao
const SQLite: qualquer = importar("cgd:sqlite").SQLite
const DataHora: qualquer = importar("cgd:tempo").DataHora

escreva(Bytes.deTexto("abc").paraHex())
escreva(Cripto.sha256("abc"))

const gz: texto = Comp.gzipComprimir("delegua-compilador-c99")
escreva(Comp.gzipDescomprimir(gz) == "delegua-compilador-c99")

const db: qualquer = SQLite.abrir(":memory:")
tente {
    db.executar("CREATE TABLE pessoas (id INTEGER PRIMARY KEY, nome TEXT)")
    db.executar("INSERT INTO pessoas (nome) VALUES (?)", ["Ana"])
    const linha: qualquer = db.consultarUm("SELECT nome FROM pessoas WHERE id = ?", [1])
    escreva(linha["nome"])
} finalmente {
    db.fechar()
}

escreva(DataHora.deUTC(2026, 11, 20, 14, 30, 5).formatarISO())

Ver exemplo completo e contrato de teste no GitHub

Experimente: http

// Servidor local: execute e acesse http://127.0.0.1:8080/.
// GET /parar encerra este exemplo; não exponha essa rota em aplicações públicas.
const Servidor: qualquer = importar("cgd:servidor")
var app: qualquer = Servidor.HTTP()
app.get("/", funcao(req: qualquer, res: qualquer): vazio {
    res.enviar("Olá, CGD!\n")
})
app.get("/usuarios/:nome", funcao(req: qualquer, res: qualquer): vazio {
    res.json({ nome: req.parametro("nome"), pagina: req.query("pagina", "1") })
})
app.post("/api/eco", funcao(req: qualquer, res: qualquer): vazio {
    res.status(201).json(req.json())
})
app.head("/", funcao(req: qualquer, res: qualquer): vazio {
    res.enviar("Olá, CGD!\n")
})
app.get("/parar", funcao(req: qualquer, res: qualquer): vazio {
    res.enviar("Até logo!\n").pararServidor()
})
app.escutar("127.0.0.1", 8080)

Ver exemplo completo e contrato de teste no GitHub

As bibliotecas cgd:* são nativas do CGD (não vêm do NPM nem do delegua-node). Para adicionar um módulo seu, basta colocar o .delegua dentro de ~/.delegua/cgd.

Membros estáticos (campos e métodos)

Membros marcados com estatico pertencem à classe inteira, não a um objeto específico. São ótimos para contadores compartilhados, constantes e fábricas de objetos.

Declarando campos e métodos estáticos

Use estatico (ou estático) tanto em campos quanto em métodos. Eles respeitam publico, protegido e privado e podem ser herdados normalmente.

classe Fabrica {
    estatico criados: inteiro = 0

    estatico proximoId(): inteiro {
        Fabrica.criados++
        retorna Fabrica.criados
    }
}
escreva(Fabrica.proximoId())

Experimente: estaticos

classe Calculadora {
    estatico dobro(valor: inteiro): inteiro {
        retorna valor * 2
    }
}

classe Avancada herda Calculadora {
}

escreva(Calculadora.dobro(3))
escreva(Avancada.dobro(4))
var calculadora: Calculadora = Calculadora()
escreva(calculadora.dobro(5))

Ver exemplo completo e contrato de teste no GitHub

Experimente: 43_estaticos_mescla

funcao de decorador triplicar(original: funcao): funcao {
    retorna funcao(alvo: qualquer, x: inteiro): inteiro {
        retorna x * 3
    }
}

classe Etiquetavel {
    prefixo: texto = "Etiqueta:"

    rotulo(nome: texto): texto {
        retorna isto.prefixo + nome
    }
}

classe Registro mescla Etiquetavel {
    estatico criados: inteiro = 0
    nome: texto

    construtor(nome: texto) {
        isto.nome = nome
        Registro.criados = Registro.criados + 1
    }

    @triplicar
    escalar(x: inteiro): inteiro {
        retorna x
    }
}

const a: Registro = Registro("Ana")
const b: Registro = Registro("Bia")
escreva(Registro.criados)
escreva(a.rotulo(a.nome))
escreva(b.eInstanciaDe(Etiquetavel))
escreva(a.escalar(10))

Ver exemplo completo e contrato de teste no GitHub

Métodos estáticos não recebem isto. Campos estáticos suportam anotações de tipo, defaults, visibilidade e validação de escrita — e são bloqueados dentro de rotinas paralelas (E3402) para manter o isolamento entre threads.

Interfaces, classes abstratas, enums e FFI C

Quando o projeto cresce, interfaces ajudam a firmar contratos claros entre classes, enums organizam constantes numéricas e @definicao permite ligar funções C direto no executável.

Interfaces e classes abstratas

Uma interface descreve os campos e métodos públicos que uma classe promete entregar usando implementa. Uma classe abstrata não pode ser instanciada diretamente e pode definir métodos abstrato para as filhas completarem.

interface Nomeavel {
    nome(): texto;
}
classe Pessoa implementa Nomeavel {
    nome(): texto { retorna "Ana" }
}

Enums numéricos em qualquer escopo

Você pode declarar enum no módulo, dentro de funções, blocos ou classes. Os valores incrementam automaticamente a partir de 0 (ou do número que você definir), são imutáveis e funcionam inclusive dentro de funções @puro (CTFE).

enum Estado { Inicio, Rodando, Final = 7 }
var atual: Estado = Estado.Final

FFI C com @definicao e classe estrangeira

Precisa chamar uma função C de uma biblioteca do sistema (como libm)? Declare uma classe estrangeira com @definicao(biblioteca="m") e mapeie cada símbolo. Na ABI C escalar, numero/real viram double, inteiro/longo viram int64_t, logico vira bool e texto vira const char*.

Lembre-se: FFI é uma fronteira de confiança — confira sempre se os tipos declarados batem exatamente com a função C real.

Experimente: 38_contratos

interface Medida {
    valor(): inteiro;
}

classe abstrata Base {
    abstrato valor(): inteiro;
}

classe Concreta herda Base implementa Medida {
    valor(): inteiro {
        retorna 5
    }
}

enum Estado {
    Inicial, Final = 7
}

var objeto: Medida = Concreta()
var duplicar: funcao = (valor: inteiro): inteiro => valor * 2
escreva(objeto.valor())
escreva(Estado.Final)
escreva(duplicar(3))

Ver exemplo completo e contrato de teste no GitHub

Experimente: matematica

var biblioteca: qualquer = importar("cgd:matematica")
escreva(biblioteca.Matematica.cosseno(0))
escreva(biblioteca.Matematica.raizQuadrada(9))

Ver exemplo completo e contrato de teste no GitHub

Experimente: 40_enums_escopos

funcao estado(): inteiro {
    enum Estado {
        Inicio, Final = 7
    }

    var atual: Estado = Estado.Final
    retorna atual
}

classe Maquina {
    enum Estado {
        Inicio, Final = 4
    }

    atual: Estado = isto.Estado.Final
}

var vetor: funcao = (x: inteiro) => [x, x + 1]
escreva(estado())
escreva(Maquina.Estado.Final)
escreva(vetor(2))

Ver exemplo completo e contrato de teste no GitHub

Enums hoje são namespaces congelados com alias para inteiro (ainda não são enums nominais distintos). Structs e callbacks compostos na ABI C ainda estão pendentes.

Decisões de escopo: o que não vai entrar no CGD

Dizer 'não' a certas coisas é o que permite manter o compilador rápido, consistente e testável. Aqui estão as escolhas definitivas do projeto.

Exclusões definitivas

RecursoComo funciona
Compatibilidade com JavaScript e classes de host JSO CGD é compilado para C99 e não depende de Node.js nem de motor JS. Para conversar com bibliotecas externas, use FFI C tipada.
Múltiplos dialetosMantemos uma única sintaxe Delégua clara e bem testada, em vez de emular vários dialetos diferentes.
Herança entre interfacesClasses podem implementar quantas interfaces quiserem diretamente, mantendo a resolução de contratos simples e previsível.
NPM, eval e importação dinâmicaTodo código compilado é conhecido antes de gerar o executável; bibliotecas compartilhadas vivem em ~/.delegua/cgd.

O que ainda pode chegar no futuro

Enums nominais (distintos de inteiro), structs/callbacks compostos na ABI C, suporte a classes locais dentro de funções assincrona, novos alvos (Windows/macOS validados) e depurador passo a passo (DAP) são itens em aberto — não exclusões definitivas.

Delégua original pertence à Design Líquido (licença Apache-2.0). O CGD honra essa origem e documenta com transparência tudo o que estende ou altera.

Lendo erros em tempo de execução (R0001)

Se uma exceção escapar do seu programa enquanto ele roda, o runtime mostra um diagnóstico colorido/visual apontando o arquivo, a linha, a coluna e o trecho exato do código.

Como ler a mensagem

O cabeçalho mostra error[R0001] seguido do motivo, o caminho do arquivo com linha:coluna e a linha marcada com ^. Caracteres de controle são escapados e arquivos indisponíveis nunca travam nem escondem o erro.

error[R0001]: Divisão por zero.
 --> { programa.delegua:2:10 }
   2 | retorna a / b
     |          ^

O código R0001 identifica erros dinâmicos do runtime. A localização usa metadados estáticos no C gerado e só lê o arquivo do disco no momento da falha.

Na prática: textos, estatística, caminhos e coleções

Exemplos rápidos de quatro módulos muito usados no dia a dia: manipulação avançada de texto, resumo estatístico, normalização de caminhos e transformações de coleções.

Textos — cgd:textos

comecaCom, terminaCom, repetir, preencherInicio, preencherFim, linhas, digitos, juntar, inverter e contar resolvem as tarefas mais chatas de formatação de strings com suporte a Unicode.

const Textos: qualquer = importar("cgd:textos").Textos
escreva(Textos.preencherInicio("7", 3, "0")) // 007

Estatistica — cgd:estatistica

Calcula soma, media, minimo, maximo, mediana, variancia (populacional ou amostral), desvioPadrao e resumo sem alterar o vetor original.

const Est: qualquer = importar("cgd:estatistica").Estatistica
escreva(Est.mediana([4, 1, 2, 3]))

Caminhos — cgd:caminhos

juntar, normalizar, absoluto, nome, diretorio, extensao e semExtensao manipulam caminhos POSIX de forma pura e previsível, sem encostar no disco.

const Caminhos: qualquer = importar("cgd:caminhos").Caminhos
escreva(Caminhos.juntar(["dados", "..", "saida", "a.json"]))

Colecoes — cgd:colecoes

unicos, intervalo, reduzir, agrupar, achatar, primeiro, ultimo, encontrar, contar, particionar, combinar, blocos e frequencias deixam transformações de listas bem mais curtas e legíveis.

Experimente: textos

var textos: qualquer = importar("cgd:textos").Textos
// Preencha códigos sem perder o zero à esquerda.
escreva(textos.preencherInicio("7", 3, "0"))
escreva(textos.digitos("012345"))
// A inversão trabalha com pontos de código Unicode.
escreva(textos.inverter("aç💚"))

Ver exemplo completo e contrato de teste no GitHub

Experimente: estatistica

var estatistica: qualquer = importar("cgd:estatistica").Estatistica
var medidas: numero[] = [4, 1, 2, 3]
escreva(estatistica.media(medidas))
escreva(estatistica.mediana(medidas))
escreva(estatistica.variancia([2, 4, 6, 8]))
// Calcular a mediana não muda a ordem do vetor recebido.
assercao(medidas[0] == 4)

Ver exemplo completo e contrato de teste no GitHub

Experimente: caminhos

var caminhos: qualquer = importar("cgd:caminhos").Caminhos
var destino: texto = caminhos.juntar(["dados", "temporario", "..", "saida.json"])
escreva(destino)
escreva(caminhos.extensao(destino))
escreva(caminhos.nome(destino))
// Normalizar um caminho não consulta o disco nem resolve links simbólicos.

Ver exemplo completo e contrato de teste no GitHub

Experimente: colecoes

var biblioteca = importar("../../bibliotecas/colecoes.delegua")
escreva(biblioteca.Colecoes.unicos([1, 2, 1, 3, 2]))
escreva(biblioteca.Colecoes.intervalo(5, 0, -2))

var colecoes: qualquer = importar("cgd:colecoes").Colecoes
funcao par(valor: inteiro): logico {
    retorna valor % 2 == 0
}

var grupos: tupla = colecoes.particionar([1, 2, 3, 4], par)
escreva(grupos[0])
escreva(grupos[1])
escreva(colecoes.blocos([1, 2, 3, 4, 5], 2))

Ver exemplo completo e contrato de teste no GitHub

Todos esses módulos já ficam instalados automaticamente em ~/.delegua/cgd quando você roda ./instalar.

Desenvolvimento do compilador

Leia AGENTS.md antes de alterar o pipeline. A linguagem original é Delégua, da Design Líquido.

Pipeline e contratos

A ordem é: UTF-8/tokens → parsing recuperável → loading estático → validação da estrutura → declaração de símbolos/tipos → resolução semântica → segurança estática → pureza → análise de fluxo → otimizações opcionais → lowering → C99 → toolchain externa.

--verificar encerra após a análise, sem exigir runtime nem compilador C. --emitir-c gera somente o C, inclusive com -o, sem vincular bibliotecas. O backend não executa código da linguagem para descobrir tipos.

AstRewriter percorre os slots mutáveis da AST em pós-ordem e visita referências compartilhadas a módulos/funções uma vez. Não segue links de resolução para símbolos, superclasses ou donos de métodos. Nomes de propriedades e destinos de atribuição não são expressões substituíveis.

O gerenciador de passes mede alterações e encerra ao atingir ponto fixo, com teto defensivo de oito iterações. Uma árvore já estável passa apenas uma vez, em vez das vinte repetições fixas anteriores. -d -o mostra os contadores.

OtimizaçãoGarantia
Dobra de literaisAritmética, comparações, concatenação, módulo inteiro e negação; overflow, divisão por zero e resultados reais não finitos ficam no runtime
Propagação de constantesIdentidade da declaração resolvida, não busca pelo nome; somente constantes literais sem anotação que possa converter o valor
Curto-circuito/coalescência/ternárioElimina só lados que comprovadamente não executam; preserva os valores retornados pelos operadores
Ramos e laços mortosRemove ramos literais e enquanto falso; não antecipa condições nem efeitos de laços
Caudas inalcançáveisRetorno, falha, sustar/continua e ambos os ramos terminantes; mantém funções/classes declaradas adiante e os blocos finalmente
CTFEFunção resolvida precisa ser exatamente a função registrada como pura, com aridade exata e argumentos literais; limites, falhas e contratos preservam execução nativa

A VM usa slots distintos por declaração e por parâmetro, restaura vínculos ao sair de blocos, implementa senão, atribuições compostas e incrementos e avalia argumentos da esquerda para a direita. Contratos primitivos de parâmetros, variáveis locais e retorno são validados antes de aceitar um resultado CTFE. Não se substituem chamadas que falham, retornam nulo implicitamente, dependem de conversão textual mista ou usam valores que a VM não representa: a chamada nativa permanece e sua exceção pode ser tratada normalmente. Chamadas indiretas e funções locais dentro de funções marcadas puras recebem diagnóstico de limitação da CTFE.

Não use identidades algébricas como x * 0 → 0: avaliar x pode lançar exceção ou ter efeitos. Não remova variáveis apenas por contagem de usos. Não propague coleções mutáveis ou remova validações de contratos.

Diagnósticos e limites

--diagnosticos=json escreve um objeto JSON por linha em stderr. Cada objeto tem severity, code, message e, quando existe posição, file e range com start/end, line/column. Linhas e colunas começam em 1; as colunas contam pontos de código Unicode, e o final é exclusivo. Falhas gerais usam E9001 e podem não ter intervalo. Mensagens permanecem em português.

Códigos: E1001 sintaxe, E1002 UTF-8, E1003 aninhamento sintático, E1004 estrutura, E2001 ciclo de módulos, E2002 orçamento de loading, E2003 importação, E3001/H3001 símbolo ausente/sugestão, W3001 código inalcançável e W3002 possível retorno implícito em função tipada. Diagnósticos legados conservam E0001/W0001/H0001. Os códigos são mais estáveis que o texto; o LSP usa os mesmos diagnósticos; não há fix-its automáticos gerais.

O parser sincroniza em declarações, comandos, ponto e vírgula e fechamento de bloco. Ele não envia uma AST com erros para a semântica. Há limite de 256 níveis sintáticos e de 512 níveis/500 mil nós antes dos passes recursivos; fontes têm limite de 4 MiB, módulos têm orçamento acumulado de 64 MiB/1024 unidades e 64 níveis. O renderer limita o trecho a cinco linhas e evita repetir diagnósticos.

Os codificadores de nomes e textos C reservam buffers e escrevem dígitos hexadecimais/ octais diretamente, mantendo exatamente os bytes da versão anterior. O teste em D compara ambas as codificações para Unicode, aspas, barra, newline e byte nulo. O microbenchmark rdmd -O -release -Isrc scripts/benchmark_codegen.d mediu 362 ms antes e 51 ms depois nesta máquina. É uma medição desses codificadores, não da compilação completa; o script não impõe limiares frágeis de tempo.

A análise de fluxo é conservadora: avisa sobre caudas inalcançáveis e possível retorno implícito; não pretende provar terminação de laços ou ausência de falhas. Os avisos não dependem de -o e não tornam uma compilação válida inválida.

Toolchain e compilação cruzada

./cgd programa.delegua --verificar --diagnosticos=json
./cgd programa.delegua --emitir-c -o -s out/programa
./cgd programa.delegua --cc clang --target aarch64-linux-gnu \
  --sysroot /sdk --runtime-object /sdk/lib/libdelegua_rt.o \
  --runtime-root /sdk/cgd --pkg-config aarch64-linux-gnu-pkg-config \
  --cflag=-g --ldflag=-static -s out/programa

O último comando é um modelo de configuração, não um SDK fornecido pelo CGD. O runtime, Boehm GC e todas as bibliotecas precisam ter sido compilados para o mesmo alvo. --target usa a opção de Clang; para GCC cruzado selecione o executável apropriado em --cc e omita essa opção. PKG_CONFIG_LIBDIR e PKG_CONFIG_SYSROOT_DIR são herdados. Bibliotecas Linux não são injetadas em triplas Windows. Nenhum executável cruzado foi validado nesta etapa.

A canonicalização POSIX mantém realpath e cache por identidade. A alternativa Windows usa caminhos absolutos normalizados e comparação sem distinção de caixa; junctions/symlinks e o runtime ainda exigem validação nativa. Os instaladores shell continuam sendo destinados ao ambiente Linux validado.

Formatação reproduzível

Instale dfmt, clang-format, Ruff, Prettier e shfmt e Taplo para TOML. As configurações estão na raiz.

python3 scripts/formatar.py
python3 scripts/formatar.py --check

Ferramentas usadas nesta revisão: dfmt c65d1c8, clang-format 22, Ruff 0.17.5, Prettier 3.8.1, shfmt 3.12.0 e Taplo 0.9.0. O script também aceita ferramentas locais em out/tools/, sem adicioná-las ao Git. Não baixa executáveis automaticamente.

Arquivos .delegua usam o formatador próprio frontend/formatter.d, com quatro espaços, preservando strings e contratos; não se usa um parser JavaScript no lugar dele. Tabelas Unicode geradas são reproduzidas pelo gerador e não reformatadas. Licenças e binários não são entradas de formatadores de código.

Verificar mudanças

Além da matriz e dos sanitizadores documentados no README, execute python3 testes/driver.py, python3 scripts/gerar_referencia.py --check e os testes do website. A referência web incorpora os próprios exemplos versionados; edite os fontes e regenere com python3 scripts/gerar_referencia.py.

Segurança estática e catálogo de mensagens

frontend/semantic/static_safety.d prova falhas locais antes do backend e funciona também sem -o. Ele avalia expressões literais e constantes imutáveis, sem executar funções ou presumir o conteúdo de vetores compartilhados. Divisão/módulo por zero, overflow de 64 bits, índices de literais, passos zero, deslocamentos, conversões textuais, contratos primitivos demonstravelmente incompatíveis, membros inexistentes em tipos/classes/módulos conhecidos, mutação de coleções imutáveis, operações sobre nulo e chamadas de valores não invocáveis recebem E3101–E3112. Anotações de vetores/tuplas também verificam literais e inserções.

Ramos constantes descartados por se, ternário, curto-circuito e laços falsos não recebem falsos erros dessa etapa. Em um corpo protegido por pegue, a falha conhecida gera W31xx: o tratamento deliberado de exceções é preservado. Isso não prova que um pegue tipado específico capturará a falha. Não há prova global de programas: aliases mutáveis, entrada externa, chamadas indiretas e condições não conhecidas continuam protegidos pelo runtime. A avaliação de constantes tem limite de profundidade para não esgotar a pilha através de cadeias de símbolos.

O catálogo está em src/diagnostics/catalog.d: código, modelo da mensagem e explicação ficam juntos. Lexer, fluxo, tipos, capturas e o novo passe usam esse catálogo. O parser compartilha um modelo contextual para tokens esperados; diagnósticos ainda não migrados conservam códigos genéricos. O renderer humano, o JSON e --explicar consomem as mesmas referências. A tabela da referência web é gerada diretamente desse catálogo, sem copiar as mensagens manualmente.

./cgd --explicar E3101
./cgd --explicar R0001
./cgd fonte.delegua --verificar --diagnosticos=json

Localização sem chamadas no caminho normal

O C gerado contém uma tabela static const delegua_local cgd_source_sites[]. Antes das operações que podem falhar, o compilador emite uma atribuição a delegua_local_atual; não emite delegua_localizar() por expressão ou linha. Literais numéricos, leitura simples de variáveis e declarações não falíveis não fazem essa atualização. Há custo de uma escrita de ponteiro nos pontos falíveis; a localização não é gratuita nem exige uma chamada adicional.

Formatação e impressão da localização ocorrem somente no caminho de erro do runtime. O código R0001 identifica a categoria dinâmica genérica; ainda não há um código distinto para cada mensagem nativa. A API C antiga delegua_localizar continua compatível para consumidores nativos. Não há uma pilha completa de chamadas ou reconstrução precisa de todos os auxiliares de coleções.

Editar o runtime a partir deste checkout

O vendor já é um submódulo com seu próprio Git e remote; não execute git init. Os commits de fonte pertencem primeiro ao repositório do runtime, e o CGD registra o commit utilizado.

git -C vendor/delegua-runtime status
git -C vendor/delegua-runtime remote -v
# Edite vendor/delegua-runtime/src/...
(cd vendor/delegua-runtime && ./tests/run.sh)
git -C vendor/delegua-runtime add src tests
git -C vendor/delegua-runtime commit -m "fix(runtime): descrever a mudança"
git -C vendor/delegua-runtime push origin dev
./build-runtime
git add vendor/delegua-runtime
git commit -m "build: atualizar referencia do runtime"

Remote original: https://github.com/FernandoTheDev/delegua-runtime. Atualizações explícitas usam git -C vendor/delegua-runtime pull --ff-only origin dev; preserve alterações locais antes disso. Stashes existentes não são descartados.

Estilo de tipos e formatador Delégua

Declare tipos concretos em D e não introduza auto, foreach inferido ou argumentos de lambdas sem tipo. Nas bibliotecas e exemplos Delégua, mantenha argumentos, retornos e vínculos explícitos; use qualquer para o domínio dinâmico. Fixtures que exercitam inferência ou erros deliberados conservam sua finalidade de teste. python3 scripts/verificar_tipos.py verifica a política nos fontes/testes D e nas bibliotecas Delégua. scripts/formatar.py usa o próprio CGD para .delegua; faça build do CGD antes. Ctrl+Shift+I no editor aciona o mesmo formatador via LSP.

Organização da análise e emissão (revisão de 16/11/2026)

frontend/semantic/pipeline.d define a sequência compartilhada entre CLI e LSP. declarations.d registra símbolos e nomes de tipos na mesma passagem; não existe mais um passe numérico separado apenas para cadastrar classes. analyzer.d resolve expressões e escopos; assignments.d concentra a mutabilidade de destinos para atribuições e incrementos; members.d compartilha busca/visibilidade de membros com o editor. native_methods.d fornece as assinaturas dos métodos nativos. Dicionários mantêm propriedades dinâmicas que podem ocultar métodos.

semantic/flow.d, semantic/static_safety.d e semantic/purity.d são análises, sem reescrever o programa. Os módulos antigos de fluxo/segurança reexportam essas APIs para preservar consumidores. semantic/constants.d avalia operações primitivas sem alterar a AST; segurança, otimização e hover compartilham essa implementação. O frontend não importa o gerador C nem passes de otimização.

A preparação do bytecode em ctfe/prepare.d é separada da validação. Chamadas da VM usam a identidade resolvida da função, inclusive entre módulos homônimos. A VM descarta resultados de comandos, limita textos a 1.048.576 pontos de código, operandos por chamada a 16.384 e slots locais ativos a 100.000, além dos limites de instruções e recursão. Exceder limites conserva a chamada nativa.

O lowering traduz expressões já verificadas; não decide se um destino é modificável. O gerador C omite rótulos que não recebem saltos e resultados intermediários de atribuições/incrementos usados só como comando. Vínculos locais continuam inicializados; (void)&vinculo evita avisos de uso sem ler um valor volatile. Essas mudanças não autorizam descartar inicializadores ou contratos.

Os novos diagnósticos E3013–E3017 cobrem destrutores, acesso a membros, uso da classe como instância, aridade e destinos imutáveis. E3201 protege a análise de pureza contra vínculos externos. As mensagens e explicações permanecem no catálogo.

Validação: a suspensão de testes foi revogada em 17/11/2026. A matriz e os resultados efetivamente executados estão em CONTINUIDADE.md e out/. Regressões novas incluem testes/stdlib.py, testes/runtime_diagnosticos.py, testes/expansao.py e testes/unit/expansion.d.

Defaults e diagnósticos do runtime

semantic/defaults.d determina os defaults de variáveis e atributos tipados. Inicializadores de atributo são funções de instância internas, avaliadas por objeto em ordem de declaração, primeiro nas bases. O runtime armazena a lista de inicializadores sem expor métodos internos à linguagem. Strings/literais de coleção são avaliados no inicializador; nunca se guarda um vetor mutável de atributo no descritor estático da classe. O carregador percorre os valores dos campos antes da semântica, e os passes seguintes percorrem as funções sintetizadas.

vendor/delegua-runtime/src/diagnosticos.c renderiza erros não capturados sem alocar valores gerenciados ou gerar novas exceções. O cabeçalho segue error[R0001], com localização, trecho e marcador quando disponíveis. Leitura de fonte é limitada e aceita só arquivos regulares, abertos sem bloquear em FIFO. Controles são escapados, tabs expandidas e a janela é limitada. A fonte vem do disco no momento do erro; mudanças após compilação podem alterar o trecho. A API antiga de localização e o custo normal de uma escrita de ponteiro são preservados. Tratadores recebem a exceção sem renderização automática.

Publicar o livro

O guia de leitura usa mdBook 0.4.52. O gerador prepara os capítulos a partir de docs/linguagem.json, dos guias Markdown e dos exemplos; o mdBook escreve a saída em docs/livro. O GitHub Pages continua servindo dev/docs.

python3 scripts/gerar_referencia.py
python3 scripts/gerar_livro.py
python3 scripts/gerar_livro.py --check
python3 testes/livro.py
python3 testes/site.py

Edite o conteúdo nas fontes e o tema em livro/tema. Não edite nem formate docs/livro à mão: ali também estão os recursos que o mdBook fornece. O destaque de Delégua é registrado em livro/tema/delegua.js; não usa a gramática JavaScript.

Lowering assíncrono experimental

A especificação e o estado real ficam em assincronismo.md. frontend/semantic/async_validation.d mantém as limitações temporárias visíveis para CLI/LSP. middle/async_ir.d normaliza avaliações e analisa vivacidade; o backend C emite wrapper/step e slots persistentes. O runtime assincrono.c separa Promessas, tarefas e filas; não mantém setjmp de ativações suspensas. O código síncrono conserva seu caminho. Registre novos opcodes nas travessias/verificador e teste efeitos/aliasing com e sem otimização antes de ampliar o subconjunto.

python3 testes/assincronismo.py
python3 testes/async_linguagem.py
CC=gcc python3 testes/async_linguagem.py
python3 testes/async_linguagem.py --sanitizadores

Os runners isolam objetos em out/, sem instalar o compilador/extensão. A suíte sanitizada usa detect_stack_use_after_return=0 e detect_leaks=0 conforme o contrato Boehm. A matriz GCC do núcleo mantém fontes antigas em O0 devido aos avisos de fluxo documentados; o núcleo/teste novo é O2. Isso não substitui a matriz completa DMD/LDC2 × debug/release × Clang/GCC.

Arquitetura do CGD

O CGD gera um executável nativo a partir de uma unidade fonte Delégua e de seu grafo de módulos. O frontend é escrito em D; o runtime e a saída intermediária usam C99. DMD e LDC2 compilam o mesmo frontend.

Passes

  1. Lexer — valida UTF-8 e reconhece palavras-chave, operadores, literais, escapes e posições. Tabelas imutáveis são compartilhadas entre lexers.
  2. Parser — produz a AST e recupera erros independentes por sincronização. Limita o aninhamento para evitar esgotar a pilha.
  3. Módulos — resolve caminhos literais, canonicaliza, reutiliza unidades, impõe orçamento de loading e mostra cadeias de importação em ciclos.
  4. Validação estrutural — percorre a AST iterativamente antes dos passes recursivos, limitando profundidade e quantidade de nós.
  5. Semântica — registra símbolos, resolve tipos e herança, valida chamadas, retornos, constantes e escopos; bloqueia capturas. Identificadores mantêm a identidade da declaração resolvida.
  6. Segurança estática — antecipa falhas locais provadas de operadores, contratos e índices antes do backend, preservando tratamento de exceções com avisos.
  7. Pureza e fluxo — valida funções //>puro e emite avisos de código inalcançável/possível retorno implícito, independentemente de otimização.
  8. Otimização opcional — passa até ponto fixo, contabilizando mudanças. Dobra literais, propaga constantes por identidade, simplifica ramos e preserva efeitos/exceções. A CTFE tem orçamento e fallback nativo.
  9. Lowering — converte operações em chamadas explícitas do runtime.
  10. Backend C — emite callbacks, descritores, classes, inicializadores de módulos e delegua_main. Nomes/textos C usam codificação direta em buffers reservados.
  11. Toolchain — separa descoberta e argv do pipeline, configura alvo/sysroot/runtime e executa o compilador C sem shell.

--verificar encerra após a análise; --emitir-c encerra após a emissão. Nenhum desses modos exige linker ou runtime instalado. A configuração de cross compilation não equivale a suporte validado a Windows/macOS.

Mapa do repositório

CaminhoResponsabilidade
src/frontend/lexer/Tokens e posições
src/frontend/parser/AST, expressões, declarações e tipos
src/frontend/semantic/Símbolos, escopos e análise semântica
src/frontend/modules.dGrafo de importação de fontes
src/ctfe/Análise de pureza, bytecode e VM de compilação
src/frontend/validation.dLimites estruturais antes da semântica
src/frontend/flow.dAvisos de fluxo conservadores
src/middle/rewrite.dReescrita de slots com cache por execução
src/driver/toolchain.dDescoberta, argv e configuração de alvo
src/opt/Otimizações da AST
src/middle/Lowering
src/backend/c/Emissão C99 e destinos de atribuição
src/driver/CLI, arquivos, tempos e chamada ao compilador C
src/errors.dDiagnósticos com severidade e posição
vendor/delegua-runtime/Runtime C e seus próprios testes
testes/unit/Testes unitários de D
testes/integracao.pySemântica observável, erros e segurança
testes/exemplos.pyValidação de todo o catálogo de exemplos
scripts/validar.pyMatriz de compiladores e modos de build
docs/Documentação e website estático

ABI dos valores e chamadas

Um delegua_value contém uma etiqueta de tipo e os dados correspondentes. Valores de texto, coleções, instâncias e funções referenciam memória gerenciada pelo GC. A linguagem não permite fabricar etiquetas, ponteiros ou callbacks C.

Funções são callbacks com quantidade de argumentos e um vetor de valores. O runtime verifica a faixa de aridade antes de chamar o callback. Parâmetros padrão são avaliados no chamado, após os parâmetros anteriores. Parâmetros variáveis recebem um vetor próprio. Métodos ligados guardam um receptor explícito; não apontam para variáveis da pilha de uma função encerrada.

Nomes internos de funções e módulos são separados dos identificadores que o programa pode declarar. Textos e caminhos são escapados na emissão C. Os argumentos são materializados na ordem da fonte para preservar efeitos colaterais, inclusive em chamadas aninhadas e índices modificáveis.

Tipos e objetos

Descritores preservam a identidade das classes, inclusive quando duas classes com o mesmo nome vêm de módulos distintos. Contratos estruturais de vetores e tuplas validam seus elementos. Vetores tipados conservam restrições de escrita através de aliases; um alias qualquer não remove uma restrição já instalada.

Classes possuem um estágio de criação das identidades e outro de registro dos campos/métodos. Isso permite campos que referenciam classes declaradas depois. Acessos privados/protegidos usam a classe lexical do método como identidade, e não o nome textual da classe. Getters e setters executam callbacks validados.

Exceções e limpeza

O runtime mantém frames de exceção gerenciados pelo GC. O C gerado usa setjmp e longjmp com variáveis do programa preservadas conforme as regras de C. retorna, sustar e continua emitem a limpeza dos frames que abandonam e os blocos finalmente correspondentes. Uma exceção disparada por um finalmente substitui a transferência de controle anterior.

O estado de recursão de chamadas também é restaurado ao tratar uma exceção. Erros de operações do runtime tornam-se exceções Excecao, com a propriedade mensagem. Sem tratador, o processo termina com status 1 e diagnóstico.

Módulos e metadados

Cada módulo é compilado em seu próprio contexto de símbolos. Seu inicializador é executado uma vez, expõe uma tabela de exportações e detecta reentrada. Se a inicialização falhar, o estado permite uma nova tentativa posterior. A tabela de exportações é protegida contra substituição; objetos exportados continuam possuindo sua própria mutabilidade.

Decoradores de dados ficam registrados como metadados. Envelopes de funções livres são aplicados na inicialização das funções do programa. Envelopes que exigem capturar o parâmetro recebido em uma função interna são bloqueados pela mesma regra de upvalues. A extensão decoradores(valor) consulta cópias dos metadados de funções, classes e propriedades.

Os contratos detalhados de passes, códigos de diagnóstico e configuração da toolchain estão em Desenvolvimento. O guia web Delégua no CGD descreve a linguagem pelo ponto de vista do usuário.

Os pontos de erro do C usam descritores estáticos e escritas de ponteiro, sem chamadas de localização por linha. O catálogo central também alimenta a referência web e a opção --explicar. Veja os limites em Desenvolvimento.

Análise persistente e formatação

frontend/analysis.d devolve AST, contexto, tokens e diagnósticos sem chamar o driver de compilação nem executar CTFE. O LSP (src/lsp/) mantém documentos e versões em memória, overlays de importações e dependências; consulta índices da revisão analisada para hover, referências e completion. Uma edição invalida o documento e os dependentes abertos. O protocolo usa stdio e posições UTF-16.

frontend/formatter.d preserva os lexemas de strings/comentários e organiza espaçamento, blocos e listas com quatro espaços. Sua idempotência e preservação dos contratos são verificadas sobre cópias de todo o catálogo. Não se deve usar Prettier de JavaScript sobre fontes Delégua. Os metadados em lsp/builtins.d precisam acompanhar a lista de métodos permitidos por tipo no runtime; campos privados e membros sombreados não podem aparecer como membros públicos herdados.

As primitivas cgdCurl* usam assinaturas explícitas em frontend/natives.d; arrays paralelos possuem contratos estáticos de comprimento/aridade. O runtime possui handles opacos gerenciados, buffers com limites e callbacks internos. Bibliotecas Delégua recebem esses valores sem acesso aos endereços C.

Compatibilidade com Delégua

Referência: wiki oficial, revisão 54eb4ae0b1489bbdef74dca4e2e9dc73c47855a0. O CGD implementa um perfil compilado com runtime gerenciado. A tabela descreve o código desta branch, não uma promessa de equivalência com todos os ambientes, dialetos e extensões do interpretador.

ÁreaRecursos disponíveis
ValoresNulo, lógicos, inteiros de 64 bits, reais de 64 bits, textos UTF-8, vetores, tuplas, dicionários, funções e objetos
VariáveisInferência, anotações, constantes, inicialização nula, atribuição múltipla e desestruturação de propriedades
OperadoresAritmética, potência, divisão inteira, bits, comparações, curto-circuito, coalescência, pertencimento e atribuições compostas
ControleSe/senão, ternário, escolha/caso, enquanto, fazer/enquanto, para, para cada, sustar e continua
ColeçõesLiterais, índices negativos, espalhamento, compreensão, fatiamento com passo e laços como expressões de vetores
FunçõesNomeadas/anônimas sem captura, funções como valores, callbacks, recursão, padrões dependentes de parâmetros anteriores e parâmetros variáveis
ClassesCampos tipados, construtores, herança, super, isto, métodos ligados/estáticos, público/privado/protegido e acessores automáticos/customizados
ExceçõesTente, pegue com/sem tipo, finalmente, falhar, Excecao e subclasses; limpeza em retornos e controles de laço
MódulosImportação de fontes .delegua por caminho literal, cache, ciclos diagnosticados, inicialização única e exportações protegidas
TextoInterpolação, escapes, tamanho/indexação por pontos de código, divisão, substituição, busca, caixa Unicode e aparar
Biblioteca globalEscreva, leia, conversões, tamanho, tupla, aleatório, aleatório entre, clonar, filtrar, mapear, ordenar, paraCada e todosEmCondicao
MétodosMétodos de texto/número/vetor/dicionário listados na referência local e propriedades ordinais das tuplas
MetadadosDecoradores de dados em funções/classes/campos/métodos e envelopes de funções livres sem captura
AsserçõesAsserção/assercao como declaração e função, com mensagem opcional e exceção tratável
CompilaçãoC99, Clang/GCC/TCC, diagnósticos com códigos/JSON, análise sem geração de executável, emissão C isolada, CTFE limitada e otimizações até ponto fixo

Veja os exemplos executáveis e o contrato de segurança.

Exclusões deliberadas

Upvalues e closures que capturam estado são bloqueados com aviso e erro. Ponteiros arbitrários, importação dinâmica, NPM e execução dinâmica de código não são expostos. Bibliotecas do ambiente delegua-node não são automaticamente bibliotecas do CGD.

Limites atuais

  • O ambiente validado é Linux x86_64. Windows/macOS e compilação cruzada não são garantidos.
  • longo usa o limite inteiro de 64 bits do runtime; não implementa a precisão arbitrária do interpretador. decimal é um alias do perfil real.
  • Importações precisam ser caminhos literais de fontes. Herança por alias dinâmico de uma classe importada não é resolvida pelo frontend.
  • Envelopes de decoradores em métodos ainda são rejeitados; metadados em métodos são suportados. Os envelopes de funções livres executam na inicialização das funções.
  • Declarações de classes devem ser feitas no nível do módulo. O suporte a tipos locais e a sombreamento de nomes de tipos não é completo.
  • A CTFE aceita um subconjunto da linguagem. Recursos sem bytecode equivalente recebem diagnóstico em funções //>puro, em vez de serem executados incorretamente.
  • Não há backends próprios LLVM/assembly, protocolo de depuração ou dialetos adicionais. O modo -d mostra a AST e o C intermediário.
  • Iteração de dicionários não promete ordem de inserção. Modificar uma coleção durante sua própria iteração não oferece semântica de snapshot.
  • Contratos de vetores compartilhados são monotônicos: novos vínculos tipados podem restringir as escritas possíveis por aliases anteriores.
  • A localização de erro pode refletir a operação auxiliar mais recente; não há uma pilha completa de chamadas em Delégua.

Esses limites são separados das exclusões de segurança: não se deve classificar um recurso ausente como inseguro apenas por ainda não estar implementado.

Ferramentas e limites de compilação

--verificar faz análise sem toolchain C. --emitir-c gera somente o C99. --diagnosticos=json produz diagnósticos estruturados em stderr. O parser recupera erros independentes e o frontend avisa sobre código inalcançável. Os limites de tamanho/aninhamento e os códigos são descritos em Desenvolvimento. Opções de alvo, sysroot e runtime preparam compilações cruzadas, mas executáveis Windows/macOS ainda não foram validados.

A referência web reúne a sintaxe e exemplos testados de cada área, com filtros por suporte, limitação e exclusão deliberada.

O frontend antecipa falhas locais comprovadas de operadores, índices e contratos antes da emissão C; em regiões com pegue emite avisos para preservar tratamento. Dados dinâmicos continuam validados pelo runtime. A localização usa metadados estáticos em pontos falíveis, sem chamadas adicionais a cada linha.

Bibliotecas e editor próprios

Os namespaces cgd:json, cgd:rede, cgd:colecoes e cgd:arquivos oferecem bibliotecas Delégua tipadas. JSON tem métodos estáticos e instâncias; rede usa libcurl gerenciada sem ponteiros/callbacks arbitrários. A API C completa de libcurl não é exposta. Métodos estáticos são herdados, mas campos estáticos não estão implementados. Iterações, compreensões e desestruturações aceitam anotações de tipo explícitas.

O formatador próprio usa quatro espaços, via CLI ou LSP. O servidor stdio local oferece completion por tipo/escopo/namespace, hover, referências, definição, rename, signature help, símbolos e semantic tokens. Não compila por edição; não há DAP ou indexação irrestrita do disco. Consulte Ferramentas para APIs, instalação, limites e comandos de teste.

Recursos acrescentados em 16/11/2026: destrutores explícitos via destruir, novos métodos de dicionário, JSON navegável e classes ClienteHTTP/RespostaHTTP/Arquivo. O hover tem prévia CTFE limitada sob demanda. Esses recursos e seus contratos estão em Ferramentas; a liberação de recursos não depende da execução de código Delégua pelo GC.

A revisão 0.4.0 acrescenta classes abstratas, interfaces, enums numéricos, arrows e FFI C/gerenciada. Veja diferenças e motivos, incluindo a lista de recursos da wiki que ainda não estão implementados. A validação atual está registrada em CONTINUIDADE.md.

Em 17/11/2026 o usuário excluiu definitivamente compatibilidade JavaScript, classes de host JS, herança de interfaces e múltiplos dialetos. Esses recursos não são planos futuros. Os testes da implementação foram autorizados nessa data; resultados reais estão em CONTINUIDADE.md.

A revisão 0.5.0 acrescenta defaults tipados, inicialização de atributos por instância, comparação textual ordenada, dicas de inferência e diagnósticos visuais do runtime. A stdlib inclui Textos, Estatistica e Caminhos, além das expansões de Colecoes, Arquivo e Matematica.

A expansão de sistema acrescenta Processo, Ambiente, Sistema, Tempo, IO, Algoritmos, CLI e Logger. Processos são síncronos com captura e limites; não há handle assíncrono. As primitivas novas dependem de Linux/glibc >= 2.34. Consulte stdlib de sistema para as assinaturas e limites.

Servidor nativo

cgd:servidor e cgd:sockets acrescentam servidor HTTP/1.1 sequencial e TCP IPv4 numérico no Linux. Rotas dos sete métodos, middleware sem captura, parâmetros, JSON e shutdown explícito estão disponíveis. Uma requisição por conexão, prazos absolutos e limites fixos/configuráveis: consulte o contrato. UDP, sockets locais, DNS/IPv6, keep-alive, TLS, HTTP/2 e atendimento concorrente ainda não foram implementados. Cliente libcurl e sua API anterior permanecem.

Assincronismo, rotinas paralelas e revisão 0.9.0

assincrona/aguardar, Promessa<T>, rotina e Tarefa<T> possuem lowering C99 stackless com vivacidade, handlers suspensos, pegue/finalmente, fluxo, coleções e pool de workers nativos com TLS por thread e auditoria transitiva de efeitos (E3401–E3404). E3305 restringe-se a classes locais em corpos assíncronos. Capturas continuam proibidas; construtores, destrutores, acessores, defaults e inicializadores não admitem aguardar.

Microtasks, entao/capturar/cancelar/concluida/cancelada, combinadores estáticos de Promessa, Canal limitado e GrupoTarefas estão disponíveis em cgd:assincrono, junto a timers, HTTP com curl multi e TCP não bloqueante sobre epoll. Hostnames HTTP exigem c-ares e libcurl >= 8.8; não há fallback bloqueante.

A revisão 0.9.0 acrescenta ainda:

  • Linguagem: campos estáticos tipados (estatico campo: Tipo = valor), composição por mixins (classe C mescla M1, M2), envelopes de decoradores em métodos de instância e estáticos, além de propagação de constantes tipadas e dobras unárias/curto-circuito adicionais.
  • Bibliotecas: cgd:bytes (Bytes), cgd:cripto (Cripto sobre OpenSSL libcrypto), cgd:compressao (Compressao gzip/deflate sobre zlib com limite de descompressão), cgd:sqlite (SQLite/BancoSQLite com consultas parametrizadas), DataHora em cgd:tempo, SocketUDP/resolverDNS/IPv6 em cgd:sockets e HTTP.escutarAsync com atendimento concorrente e HTTP/1.1 keep-alive em cgd:servidor.

Veja assincronismo, rotinas e servidor HTTP.

Perfil de segurança

O perfil compilado mantém os valores em memória gerenciada e verifica operações que dependem de tipos conhecidos apenas em execução. Ele não oferece uma prova formal de segurança nem isolamento de processos.

Sem captura de ambientes

funcao criar(valor) {
    retorna funcao() { retorna valor } // Aviso sobre upvalues e erro.
}

Passe o estado por parâmetro ou mantenha-o em uma instância explícita:

funcao somar(valor, incremento) { retorna valor + incremento }
var operacao = somar
escreva(operacao(10, 2))

Funções nomeadas sem captura, funções anônimas sem captura, callbacks e métodos ligados a instâncias são permitidos. Capturas de variáveis locais, parâmetros, variáveis globais e de isto por funções internas são bloqueadas. Isso também vale para variáveis que contêm referências a outras funções.

Capacidades ausentes por decisão de segurança

  • Ponteiros crus, structs e callbacks arbitrários na ABI C ainda não têm representação na linguagem.
  • Importação de .so, .dll, pacotes NPM e caminhos calculados em execução.
  • Ponteiros arbitrários, acesso à representação interna dos valores e avaliação dinâmica de código.
  • Ambientes capturados implicitamente por closures/upvalues.

A revisão 0.4.0 autoriza classes estrangeiras C por pedido explícito do usuário. A FFI exige assinatura correta e código nativo confiável; não é sandbox. Veja evolução e ABIs. O contrato anterior de exclusão de FFI foi substituído. O vendor também conserva a API C de FFI para consumidores nativos. Essa API não é exposta aos programas Delégua compilados pelo CGD.

Verificações

Aridade e contratos de parâmetros/retornos são verificados também em chamadas indiretas. Tipos nominais de classes não se confundem por terem o mesmo nome em módulos distintos. Visibilidade, propriedades declaradas, getters/setters, índices, imutabilidade de tuplas e overflow inteiro possuem verificações no runtime; elas continuam ativas com NDEBUG.

Vetores tipados mantêm contratos de escrita no heap. Obter um alias qualquer não permite inserir um texto em um vetor já validado como inteiro[]. Esses contratos são conservados e podem ser estreitados por novos vínculos tipados; não são enfraquecidos por aliases.

O driver não interpola nomes de arquivos em comandos de shell e usa símbolos internos inacessíveis pela sintaxe dos identificadores do usuário. Módulos fonte são canonicalizados e seus ciclos são rejeitados.

Recursos e limites

A VM de CTFE limita a profundidade a 128 chamadas e o trabalho a 10 milhões de instruções por tentativa. Ao atingir esses limites, a otimização preserva a chamada nativa. A execução nativa limita chamadas encadeadas a 1024 níveis e restaura esse contador ao desenrolar exceções.

Inteiros usam 64 bits assinados e operações verificadas. longo não fornece inteiros arbitrariamente grandes neste perfil. Reais usam precisão dupla. Textos são UTF-8; operações por caracteres validam as sequências. As tabelas de conversão de caixa são estáticas e podem ser regeneradas pelo utilitário do runtime, sem depender do locale da máquina.

O runtime é projetado para execução em uma thread. Não há sincronização para compartilhar seus estados globais de exceção, inicialização e GC entre threads. Não há suporte de sandbox para executar programas não confiáveis: permissões do processo e limites de recursos devem ser definidos pelo ambiente hospedeiro.

Reproduzir verificações

Os exemplos em exemplos/seguranca/ declaram tanto a fase da falha quanto o texto do diagnóstico esperado. testes/integracao.py acrescenta casos de aliases, nominalidade, capturas, acesso a membros, importação e limpeza de exceções.

O README do runtime documenta a execução de ASan/UBSan. Com o GC conservativo, a pilha falsa de ASan e seu detector de vazamentos precisam ser desabilitados; isso não desativa os demais diagnósticos de acesso inválido e UB.

Bibliotecas e editor CGD

O CGD usa o frontend de D no servidor cgd --lsp --stdio, um processo local persistente. Alterar um documento atualiza sua análise e os dependentes abertos; hover, completion e tokens usam a revisão já analisada. Nenhum build, linker ou código do programa é executado por edição. O editor não precisa de conexão de rede.

VS Code e formatação

Após construir o CGD uma vez:

cd extensao-vscode
npm ci
cd ..
python3 scripts/instalar_extensao.py --associate

A extensão usa o CGD configurado, o do workspace confiável ou o binário incluído no VSIX. CGD: Reiniciar servidor de linguagem reinicia o processo; após reinstalar, use Developer: Reload Window para carregar a nova extensão. Os botões compilam, verificam ou executam o documento salvo. F5 executa sem depuração; DAP foi adiado.

Ctrl+Shift+I e Format Document chamam o formatador do LSP. O estilo usa quatro espaços, espaços entre operadores, separação de blocos e métodos e continuidade de listas longas. Strings, comentários e contratos são preservados; literais longos não são partidos. O formatador é lexical, não renomeia símbolos nem inventa tipos. Na CLI, cgd --formatar arquivo.delegua grava o arquivo; cgd --verificar-formatacao arquivo.delegua retorna 1 se houver divergência.

Completion diferencia métodos e campos, respeita o tipo conhecido, membros públicos herdados e namespaces de módulos. Receptores qualquer sem informação suficiente não recebem sugestões de métodos específicos inventados. Há hover, definição, referências, rename, símbolos, signature help com parâmetro ativo, semantic tokens, dobramento e hints opcionais. O índice abrange documentos abertos mais suas importações estáticas; não indexa automaticamente todos os arquivos do disco. Não existe garantia de inferência completa sobre dados dinâmicos.

JSON em Delégua puro

var biblioteca: qualquer = importar("cgd:json")
var dados: qualquer = biblioteca.JSON.analisar('{"nome":"CGD"}')
var documento: qualquer = biblioteca.JSON(dados)
documento.definir("versao", 1)
escreva(documento.texto())

JSON.analisar(fonte, limite=128, maxNos=100000) implementa gramática estrita, escapes e pares substitutos Unicode. O limite máximo de entrada é 1048576 pontos de código. JSON.serializar(valor) rejeita ciclos e reais não finitos. Inteiros fora de 64 bits e expoentes fora da representação nativa são preservados como NumeroJSON; lexema() devolve sua grafia. As funções soltas permanecem para compatibilidade. O construtor JSON recebe o valor já analisado. valor(), obter(chave), definir(chave,valor) e texto() são métodos de instância.

estatico/estático declara métodos sem isto; eles são herdados e podem ser chamados pela classe ou pela instância. Campos estáticos não estão implementados.

Rede sobre libcurl

importar("cgd:rede") oferece Sessao, obter, enviar, requisitar, lote, versao, detalhes, opcoes, escape/decodificação, URL API e datas/erros. Sessao.opcao(nome,valor) aceita opções gerenciáveis anunciadas pela libcurl instalada. Use Sessao.info(nome) para getinfo escalar, multipart(partes) para partes em memória e upload(dados) para upload explícito. A sessão também oferece reset/close, streams connect-only e espera de leitura/escrita. Feche sessões em finalmente. Lotes usam curl_multi. As respostas trazem codigo (CURLcode, zero no sucesso), status HTTP, corpo, cabecalhos, url, segundos e erro. Falhas de transporte ficam nesses campos; configurações inválidas lançam exceções. HTTP 404 não é sucesso HTTP, mas pode ter CURLcode zero. O corpo da resposta e os headers têm limite padrão de 64 MiB cada, ajustável com CGD_MAX_BYTES.

Os defaults usam HTTP/HTTPS, TLS verificado, conexão de 10 segundos e tempo total de 30 segundos. Os programas podem escolher outras opções/protocolos disponíveis. A API não expõe ponteiros C, FILE*, callbacks arbitrários, sockets crus nem opções que substituam callbacks internos ou desliguem suas proteções. POSTFIELDSIZE direto é recusado: o tamanho acompanha o corpo copiado. O upload nunca lê stdin implicitamente. As opções dependem da libcurl instalada; detalhes() distingue versão dos headers e versão carregada. Entry points WebSocket exigem uma libcurl com os protocolos necessários; o ambiente validado não anuncia ws/wss.

A API controlada não replica toda a API C de libcurl. Consulte a lista real em opcoes() e os testes de loopback em testes/bibliotecas.py.

Coleções

importar("cgd:colecoes") expõe Colecoes.unicos(valores) e Colecoes.intervalo(inicio,fim,passo=1). O intervalo exclui o fim, aceita passo negativo, recusa zero e limita a criação a um milhão de elementos. Comparação de coleções/objetos segue a identidade do runtime. As operações nativas de vetores continuam disponíveis, incluindo mapear e filtrar com callbacks sem captura.

Validação de desenvolvimento

testes/lsp.py verifica protocolo, escopos, UTF-16, buffers em memória, completion, assinaturas e cache. testes/formatador.py exige idempotência e executa os contratos de todos os exemplos formatados, com/sem otimização. testes/bibliotecas.py usa HTTP em loopback e verifica JSON, limites e opções recusadas. scripts/verificar_tipos.py impede auto/foreach inferido em D e variáveis sem anotação nas bibliotecas. python3 scripts/testar_extensao.py abre um Extension Host com perfil temporário para testar a integração real, incluindo formatação e ausência de build por edição.

APIs ampliadas em 16/11/2026

As mudanças desta seção foram incluídas nas suítes autorizadas em 17/11/2026. Consulte CONTINUIDADE.md para os resultados efetivamente concluídos.

JSON e HTTP por classes

var json: qualquer = importar("cgd:json")
var documento: qualquer = json.JSON.deTexto('{"pessoa":{"nome":"Ana"}}')
escreva(documento.caminho(["pessoa", "nome"], "sem nome"))
escreva(documento.obter("ausente", "padrão"))

JSON.contem distingue ausência de um valor nulo. obter aceita chave ou índice, inclusive índice negativo de vetor; caminho percorre uma lista de chaves/índices. definir aceita chave ou índice para escrita. copiar cria um documento independente por serialização e nova análise JSON. chaves exige objeto JSON. Chaves como "chaves", "obter" e "itens" não impedem a serialização; ela usa a enumeração controlada do runtime, sem despacho de propriedades. As funções soltas e JSON.analisar/serializar continuam disponíveis. Profundidade: 1..512; orçamento de nós: 1..1.000.000.

var rede: qualquer = importar("cgd:rede")
var cliente: qualquer = rede.ClienteHTTP("https://exemplo.com")
cliente.cabecalho("Accept", "application/json")
var resposta: qualquer = cliente.obter("/dados").exigirSucesso()
escreva(resposta.status())
escreva(resposta.json())

ClienteHTTP copia cabeçalhos/opções recebidos, oferece obter/enviar/enviarJSON/ atualizar/remover e cria uma sessão isolada por requisição. RespostaHTTP oferece status/sucesso/texto/json/cabecalhos/url/erro/dados/exigirSucesso. dados retorna uma cópia do dicionário. sucesso exige libcurl sem erro e status 200..299; falhas HTTP continuam inspecionáveis até chamar exigirSucesso. As APIs anteriores de sessão, streaming, multipart e lote permanecem disponíveis.

Arquivos e dicionários

var arquivos: qualquer = importar("cgd:arquivos")
var arquivo: qualquer = arquivos.Arquivo("dados.txt")
arquivo.escrever("primeira linha\n").anexar("segunda linha\n")
escreva(arquivo.ler())

Arquivo oferece caminho/existe/informacoes/tamanho/ler/linhas/escrever/anexar/ remover. Cada chamada abre e fecha seu descritor; nenhum ponteiro ou descritor é exposto. Leitura padrão: 16 MiB, configurável até 64 MiB; escrita: até 64 MiB por chamada. Tamanhos/limites contam bytes. Textos de I/O preservam bytes nulos; operações Unicode sobre dados que não são UTF-8 continuam sujeitas à validação usual do runtime. linhas normaliza CRLF e preserva linhas vazias/quebra final. remover devolve falso se ausente. Diretórios/dispositivos/FIFOs não servem para ler/escrever; erros de I/O são exceções tratáveis. Escrita pode ser parcial se o sistema falhar; não é transação nem gravação atômica. Implementação POSIX/Linux.

Dicionários oferecem obter(chave, padrao = nulo), definir(chave, valor) (retorna o valor), contemChave(chave), itens() (snapshot de tuplas chave/valor) e limpar() (muta a mesma coleção e retorna o dicionário). obter usa o padrão somente quando a chave não existe; nulo armazenado permanece nulo. itens faz cópia rasa, sem prometer ordem. Uma chave textual com o nome de um método continua ocultando esse método; use índices para acessar esses dados.

Ciclo de vida explícito

classe Recurso {
    construtor() {}
    destrutor(): vazio {
        escreva("liberado")
    }
}
var recurso: Recurso = Recurso()
tente {
    escreva("usando")
} finalmente {
    destruir(recurso)
}

construtor, destrutor e estatico/estático são palavras-chave. Destrutores são públicos, de instância, sem argumentos e com retorno vazio. Use destruir(instancia) para acionar a cadeia da classe derivada até as bases, uma vez por identidade; reentrada e chamadas repetidas são ignoradas. As bases ainda executam se uma classe falhar; a primeira exceção é relançada ao final. A cadeia é automática: não chame super.destrutor() dentro dela. Chamadas diretas ao método não substituem esse protocolo. A memória continua gerenciada pelo GC; não há execução de destrutores Delégua pelo coletor nem ao sair de escopos. Sessao implementa destrutor que fecha sua sessão nativa; fechar continua disponível.

Editor e prévia CTFE

A extensão 0.3.0 inclui gramática lexical para coloração antes de o LSP responder, snippets e reconhecimento de executáveis com shebang cgd/delegua. Tokens semânticos continuam prevalecendo. Completion usa o catálogo de palavras-chave do lexer e membros do receptor respeitando escopo, herança, estáticos e visibilidade; isto. incompleto preserva o contexto da classe. Não há sugestões de nomes aleatórios do arquivo como fallback depois de ponto.

O hover pode exibir o resultado de chamadas puras com argumentos constantes e de operações primitivas. A prévia trabalha sobre cópias, apenas sob demanda, com cache por revisão, até 100.000 instruções de VM por documento e limites de nós/ profundidade. Constantes primitivas tipadas são aceitas se seu contrato passar. Não executa rede, I/O, funções comuns ou código arbitrário, nem invoca compilador C/linker. Falhas e limites omitem a prévia; variáveis mutáveis e recursos fora do subconjunto CTFE não recebem valores presumidos. Isso não constitui depuração.

Biblioteca padrão ampliada e erros visuais (0.5.0)

A referência principal de uso é o guia web próprio, do início às APIs e decisões de escopo. Ela inclui os capítulos específicos de Textos, Estatistica, Caminhos e diagnósticos do runtime, com exemplos e contratos.

cgd:textos oferece comecaCom, terminaCom, repetir, preencherInicio/preencherFim, linhas, digitos, juntar, inverter e contar. Texto é Unicode; digitos é ASCII explícito e inverter usa pontos de código, sem normalizar grafemas.

cgd:estatistica oferece soma, media, minimo, maximo, mediana, variancia, desvioPadrao e resumo. A mediana copia antes de ordenar; a variância é incremental, populacional por padrão, com opção amostral. Entradas insuficientes falham.

cgd:caminhos oferece absoluto, normalizar, juntar, nome, diretorio, extensao e semExtensao. São operações POSIX lexicais, sem acessar disco ou resolver links. Não use normalizar como garantia de confinamento de arquivos.

Colecoes ganhou primeiro, ultimo, encontrar, contar, particionar, combinar, blocos e frequencias. Resultados novos preservam referências rasas aos elementos; callbacks não capturam ambiente. Arquivo ganhou lerJSON, escreverJSON e copiarPara. Matematica expõe funções trigonométricas inversas, logaritmos, arredondar/truncar, hipotenusa e resto via libm.

Erros não capturados do runtime mostram error[R0001], arquivo/linha/coluna, linha de fonte e marcador ^. Sem o arquivo, a localização permanece. O trecho é lido do disco apenas ao reportar falha e pode divergir se o fonte foi modificado. Controles são escapados; leitura/janela são limitadas e FIFO não bloqueia o renderer. Exceções capturadas não são impressas automaticamente.

Evolução do perfil CGD — 16/11/2026

Referência: wiki oficial Delégua, orientação a objetos e FFI. A cópia consultada está em out/wiki-oficial, revisão 54eb4ae0b1489bbdef74dca4e2e9dc73c47855a0; sua revisão pode ser obtida com git -C out/wiki-oficial rev-parse HEAD. Autoria da linguagem original e licença Apache-2.0 permanecem preservadas. Não se afirma equivalência completa.

Recursos implementados nesta revisão

  • classe abstrata Nome: não instanciável, inclusive através de referências dinâmicas. abstrato metodo(...): Tipo; declara obrigação a ser implementada pela classe concreta. Métodos abstratos privados/estáticos e de ciclo de vida são rejeitados. A classe derivada mantém a assinatura e a visibilidade exigidas.
  • interface Nome { campo: Tipo; metodo(...): Retorno; } e classe Nome implementa I, J: resolução de contratos públicos e validação de campos, parâmetros, retornos e métodos herdados. Interfaces são tipos de contratos, reconhecidos nos descritores do runtime e em eInstanciaDe. Assinaturas de implementações são explícitas: diferentemente de exemplos inferidos do interpretador, o CGD exige correspondência com o contrato para manter o vínculo C verificável. Herança entre interfaces é excluída definitivamente por decisão do usuário.
  • enum Estado { Inicial, Final = 7 }: constantes inteiras em namespace congelado. Incremento implícito, valores explícitos, duplicatas e overflow diagnosticados. Estado em anotações é alias de inteiro; não constitui enum nominal isolado, não restringe uma variável exclusivamente aos membros e não é união algébrica. Enums podem ser declarados em módulos, funções, métodos, blocos de controle e classes/interfaces. O alias tem escopo lexical. Na classe, Classe.Enum e isto.Enum respeitam visibilidade e herança, sem introduzir campos estáticos mutáveis. Membros escalares são constantes aptas a CTFE; capturas de valores continuam com as restrições anteriores. Mutar o namespace por aliases é bloqueado.
  • x => expressão, (x: T, y: U): R => expressão e corpos { ... }: reutilizam funções anônimas e suas regras de escopo. Capturas continuam diagnosticadas; arrow não concede acesso implícito a ambientes externos.
  • para cada elem: T em coleção já existia e permanece disponível, incluindo contratos em runtime. Não é necessário remover a anotação para iterar.

Enums numéricos, arrows e destrutores explícitos são extensões do perfil CGD solicitadas pelo usuário; não são apresentados como sintaxe comprovada dos capítulos consultados da wiki. O objetivo é oferecer contratos e conveniência sem exigir capturas, avaliação dinâmica ou mudanças no runtime de memória.

FFI C e bibliotecas

A wiki define classes estrangeiras com @definicao e deixa o despachador a cargo do ambiente. CGD implementa ligação C estática na geração do executável:

@definicao(biblioteca="m", prefixo="")
classe estrangeira LibM {
    @definicao(simbolo="cos")
    cosseno(x: numero): numero;
}
escreva(LibM.cosseno(0))

numero/real correspondem a double; inteiro/longo a int64_t; logico a bool; texto a cadeia C terminada em zero; retorno vazio a void. Textos com zero interno são rejeitados nessa ABI. Valores retornados de texto são copiados imediatamente; ponteiros nulos provocam falha tratável. Não há inferência de assinatura a partir de símbolos: a declaração precisa corresponder à biblioteca C. Declarações erradas e código nativo podem corromper o processo; FFI não é sandbox. Isso substitui a exclusão anterior de FFI por decisão explícita do usuário. Não há carregamento dinâmico por edição, avaliação no LSP ou CTFE.

@definicao(biblioteca="cgd-runtime", abi="delegua") usa a ABI gerenciada: delegua_value funcao(sz argc, delegua_value *argv). Ela representa coleções, textos binários e handles gerenciados sem expor ponteiros na linguagem. O retorno passa pelo descritor do contrato. bibliotecas/nativo.delegua define as assinaturas dessa ponte; JSON, rede e arquivos usam a classe Primitivas. As entradas cgd* anteriores permanecem como compatibilidade, não como requisito sintático das bibliotecas novas. Removê-las antes de validar a migração quebraria consumidores existentes. pontes.c é o ponto de exportação da ABI gerenciada.

cgd:matematica fornece Matematica sobre libm; Colecoes ganhou reduzir, agrupar e achatar. JSON, ClienteHTTP/RespostaHTTP e Arquivo mantêm as APIs documentadas em ferramentas. As bibliotecas não devem substituir diretamente libcurl por uma assinatura variádica presumida: adaptadores C precisam conservar callbacks internos, ciclo de vida e buffers. Por isso a camada gerenciada continua necessária mesmo com FFI.

Diferenças e trabalho ainda necessário

A wiki descreve diversos ambientes, dialetos, tradução e integração JavaScript. Esses capítulos não são suporte automático em um compilador C99. Na revisão 0.9.0 foram acrescentados composição mescla, campos estáticos, envelopes de decoradores em métodos e rotinas paralelas (rotina/Tarefa<T>). Permanecem pendentes enums nominais, structs/variádicos/callbacks compostos na ABI C e equivalência integral de bibliotecas externas. Capturas/upvalues, eval e importação dinâmica continuam excluídos pelo contrato de segurança; não são habilitados por arrows ou FFI. DAP continua adiado. Linux x86_64 é o único alvo previamente validado.

Na etapa de 16/11 as suítes estavam suspensas por solicitação do usuário. A autorização de 17/11 revogou essa suspensão: resultados reais, incluindo regressões funcionais, ficam em CONTINUIDADE.md.

Em 17/11/2026 o usuário excluiu definitivamente compatibilidade JavaScript, classes de host JS, herança de interfaces e múltiplos dialetos. Esses recursos não são planos futuros. Os testes da implementação foram autorizados nessa data; resultados reais estão em CONTINUIDADE.md.

Programas que conversam com o sistema

Você já pode receber argumentos, chamar outro programa, ler stdin, escrever em stderr e medir quanto uma tarefa levou. Estas bibliotecas usam a mesma sintaxe das demais: importe um módulo cgd: e use suas classes.

A implementação desta etapa é para Linux x86_64 com glibc >= 2.34. Ela usa posix_spawn, grupos de processos, poll, waitid e waitpid. Não foi validada em Windows, macOS ou musl. Os exemplos também usam /bin/printf e os testes usam Python 3. Não há dependência nova de execução para além da libc do sistema.

Processo: argumentos reais

var P: qualquer = importar("cgd:processo").Processo
escreva(P.argc())
escreva(P.argv())
escreva(P.argumentos())
Método estáticoRetorno e significado
argv(): texto[]Cópia nova do argv original, incluindo argv[0]. Preserva ordem, espaços, argumento vazio e Unicode.
argc(): inteiroQuantidade de itens de argv, incluindo argv[0].
argumentos(): texto[]Cópia dos argumentos da aplicação, sem argv[0].
quantidadeArgumentos(): inteiroQuantidade de argumentos da aplicação.
executavel(): textoargv[0] como foi recebido: pode ser relativo ou só um nome. Não promete caminho canônico.
identificador(): inteiroPID do processo atual.

Esses dados vêm de program_context, preenchido pelo main do runtime. Não há uma variável Delégua global que o programa possa alterar para falsificar argv. Mudar o vetor devolvido não altera as chamadas seguintes. O contexto C pode ser vazio em consumidores que não usem o ponto de entrada padrão; nesse caso argv é vazio, argc é zero e executavel devolve texto vazio.

Executar outro programa

var P: qualquer = importar("cgd:processo").Processo
var resultado: qualquer = P.executar("git", ["--version"])
resultado.exigirSucesso()
escreva(resultado.saidaPadrao())

A assinatura completa é:

Processo.executar(
    programa: texto,
    argumentos: texto[] = [],
    diretorio: texto = "",
    ambiente: dicionario = {},
    timeout: inteiro = 30000,
    limite: inteiro = 16777216,
    entrada: texto = ""
): ResultadoProcesso

Cada item de argumentos vira um argumento, sem separar por espaços, expandir *, substituir $HOME ou interpretar ;. O programa é executado diretamente. Arquivos sem formato executável e sem shebang falham; não há fallback para shell. Isso evita interpretação de comandos, mas não torna os argumentos seguros para qualquer programa: o programa chamado ainda interpreta suas próprias opções.

diretorio vazio herda o diretório atual. Outro caminho muda apenas o filho. O ambiente é herdado, com sobrescritas do dicionário: valores precisam ser texto; nulo remove a variável no filho. O pai não é alterado. O PATH utilizado na procura de programa é o do pai, conforme posix_spawnp. Para escolher um executável sem depender dessa procura, passe seu caminho absoluto.

timeout é em milissegundos, de 1 a 86400000. Ele inclui inicialização e espera por EOF dos pipes, mesmo quando o filho terminou mas algum descendente manteve uma saída aberta. limite é a soma dos bytes capturados de stdout e stderr, de 1 a 67108864. Quando ultrapassado, o resultado contém o prefixo capturado até o limite. As duas saídas não têm uma ordem global preservada entre si.

entrada é enviada ao stdin do filho e fechada ao terminar; o limite é 64 MiB. Se o filho fechar stdin antes, o pai continua e coleta o resultado. Sem entrada, o filho recebe EOF, em vez de ler acidentalmente o terminal do chamador.

ResultadoProcesso

Método de instânciaContrato
codigoSaida(): qualquerInteiro quando terminou normalmente; nulo quando terminou por sinal. Zero não é presumido para falhas.
sinal(): qualquerNúmero do sinal ou nulo se terminou normalmente.
saidaPadrao(): textoBytes capturados de stdout, preservando NUL.
saidaErro(): textoBytes capturados de stderr, preservando NUL.
expirou(): logicoO prazo foi atingido.
excedeuLimite(): logicoA captura ultrapassou o limite configurado.
sucesso(): logicoCódigo zero, sem timeout nem excesso de saída.
exigirSucesso(): ResultadoProcessoDevolve o mesmo resultado ou lança com código, sinal, flags e stderr.

As saídas usam o tipo texto existente, que armazena bytes e tamanho. Não há conversão de encoding nem validação automática de UTF-8. Operações Unicode sobre saídas binárias, ou sobre um prefixo cortado no meio de um caractere, não devem ser usadas como se os dados fossem texto UTF-8 válido. Um buffer binário próprio é uma etapa posterior, não um vetor de números apresentado como equivalente.

Falhas ao iniciar, caminhos inválidos, permissões e erros de sistema lançam exceção com errno e mensagem nativa. Código de saída diferente de zero é um resultado; use exigirSucesso se quiser tratá-lo como exceção. Argumentos, nomes de ambiente e caminhos com NUL são rejeitados antes da aquisição de recursos.

O runtime drena stdout e stderr e envia stdin com poll, sem esperar uma saída terminar para ler a outra. Em timeout/limite ele envia SIGKILL ao grupo criado, fecha os descritores e recolhe o filho direto. O PID fica reservado até a coleta, para não sinalizar um grupo de PID reutilizado. Descritores além de 0/1/2 não são herdados pelo filho. Não é um sandbox: descendentes podem escapar do grupo, e o runtime não promete controlar ou recolher processos que não sejam seus filhos. A memória de captura também ocupa espaço: o limite de saída não é um limite de memória total da aplicação.

Configuração reutilizável

var Comando: qualquer = importar("cgd:processo").Comando
var comando: qualquer = Comando("git", ["status", "--short"])
    .diretorio("/caminho/do/projeto")
    .timeout(5000)
    .limite(1048576)
var resultado: qualquer = comando.executar()

Comando(programa: texto, argumentos: texto[] = []) copia os argumentos. Seus métodos argumento(texto), diretorio(texto), ambiente(texto, qualquer), timeout(inteiro), limite(inteiro) e entrada(texto) devolvem o próprio comando. executar(): ResultadoProcesso inicia um novo filho a cada chamada. Não há handle persistente nem necessidade de destrutor para essa configuração.

Shell explícito

Processo.executarShell(comando: texto, diretorio: texto = "", ambiente: dicionario = {}, timeout: inteiro = 30000, limite: inteiro = 16777216, entrada: texto = "") devolve ResultadoProcesso e chama /bin/sh -c. Não concatene dados não confiáveis nessa string. Prefira executar com argumentos separados. Esta API existe para quando a interpretação de shell é justamente o que você deseja.

iniciar, espera assíncrona e streams persistentes não são oferecidos nesta etapa. Eles precisam de um dono para o handle, políticas de cancelamento e coleta, limpeza em exceções e um mecanismo real de acompanhamento. Uma chamada síncrona com outro nome não substitui esse trabalho.

Ambiente

importar("cgd:ambiente").Ambiente oferece métodos estáticos:

AssinaturaO que faz
obter(nome: texto, alternativa: qualquer = nulo): qualquerTexto ou alternativa se ausente. Valor vazio é preservado.
contem(nome: texto): logicoDistingue ausência de texto vazio.
variaveis(): dicionarioSnapshot do ambiente atual. Mudar o mapa não altera o ambiente.
definir(nome: texto, valor: texto): vazioAltera explicitamente o ambiente do processo atual.
remover(nome: texto): vazioRemove a variável atual; ausência não é erro.
diretorioAtual(): textoConsulta getcwd; lança em falha, inclusive diretório removido.
diretorioTemporario(): textoTMPDIR não vazio ou /tmp. Não cria nem verifica a pasta.
diretorioUsuario(): qualquerHOME ou nulo. Não garante que o caminho exista.

Nome vazio, = e NUL são recusados; valores com NUL também. As alterações valem para futuros filhos, não para processos já iniciados. Ambiente não é armazenamento confidencial; não coloque sua enumeração em logs. Esta etapa não oferece um contrato de sincronização com threads nativas externas alterando environ.

Sistema

importar("cgd:sistema").Sistema consulta uname e o PID, sem executar comandos. nome(): texto, arquitetura(): texto, versao(): texto e informacoes(): dicionario devolvem dados reais. O mapa tem nome, arquitetura, versao e pid. separadorCaminho(): texto é /; separadorBusca(): texto é : nesta implementação. capacidades(): dicionario informa processos, shell, ambiente e relógio monotônico presentes; processos persistentes estão ausentes. A plataforma validada é informada separadamente da arquitetura detectada. Falha de uname lança exceção.

Tempo e durações

importar("cgd:tempo") fornece Tempo, Duracao e Cronometro:

  • Tempo.monotonico(): real: segundos de CLOCK_MONOTONIC, para medir intervalos. A origem não é uma data nem um valor para persistir entre reinicializações.
  • Tempo.unix(): real: segundos de CLOCK_REALTIME desde a época Unix. O relógio civil pode ser ajustado; não o use para medir o timeout de uma operação.
  • Tempo.dormir(milisegundos: inteiro): vazio: 0..86400000 ms; retoma a espera restante após EINTR. O agendador pode fazer a espera durar mais.
  • Duracao(milisegundos: real): exige valor finito e não negativo. emMilisegundos(): real, emSegundos(): real, somar(outra: Duracao): Duracao e dormir(): vazio. A espera trunca a parte fracionária de milissegundos e respeita os mesmos limites de Tempo.dormir.
  • Cronometro(): inicia uma medição. reiniciar(): vazio, segundos(): real e milisegundos(): real consultam o tempo decorrido.

Não há promises de precisão de nanossegundos, calendário, fusos horários ou formatação de datas. Falhas dos relógios e durações inválidas lançam exceção.

IO de console

importar("cgd:io").IO opera sobre os streams padrão já abertos:

AssinaturaContrato
escrever(valor: texto): inteiroEscreve sem quebra em stdout e faz flush; retorna bytes escritos.
escreverLinha(valor: texto = ""): inteiroAcrescenta LF.
erro(valor: texto): inteiroEscreve em stderr e faz flush.
erroLinha(valor: texto): inteiroAcrescenta LF em stderr.
lerLinha(limite: inteiro = 1048576): qualquerTexto sem LF/CRLF, inclusive texto vazio; nulo em EOF sem dados. Limite em bytes de 1 a 64 MiB.

Leitura é bloqueante. Falha não retorna EOF falso: lança exceção. Excesso de linha lança depois de consumir parte da entrada; não é uma operação com rollback. Escrita pode ter sido parcial antes de falhar. O tipo texto preserva NUL, mas não substitui uma API de buffer binário. IO não fecha stdin/stdout/stderr; eles pertencem ao processo. Sinais como SIGPIPE continuam sujeitos às regras Unix. Não há streams de arquivos com handles expostos nesta etapa.

Algoritmos numéricos

importar("cgd:algoritmos").Algoritmos complementa Colecoes e as operações nativas. Todos os métodos são estáticos e recebem numero[]:

  • limiteInferior(valores, alvo: numero): inteiro: primeira posição com valor maior ou igual ao alvo; tamanho do vetor se não existir.
  • limiteSuperior(valores, alvo: numero): inteiro: primeira posição estritamente maior.
  • buscaBinaria(valores, alvo: numero): inteiro: primeira ocorrência ou -1.
  • estaOrdenado(valores): logico: verifica ordem crescente, permitindo repetições.
  • ordenado(valores): numero[]: cópia ordenada, sem alterar o original.
  • intercalar(a: numero[], b: numero[]): numero[]: intercala dois vetores já ordenados, mantendo repetições e preferindo a esquerda nos empates.

Busca e limites são O(log n) e exigem entrada ordenada com valores comparáveis, sem NaN. Não verificam essa precondição percorrendo o vetor inteiro. Intercalar é O(n+m). Para reduzir, particionar, agrupar ou combinar, use Colecoes: não foram criadas cópias dessas APIs neste módulo. Comparadores personalizados e iteradores lazy ficam para uma etapa que consiga preservar seus contratos.

CLI

var CLI: qualquer = importar("cgd:cli").CLI
var parser: qualquer = CLI("Conversor")
    .opcao("ajuda", "h", falso, "Mostra esta ajuda")
    .opcao("saida", "s", verdadeiro, "Arquivo de destino")
var argumentos: qualquer = parser.atual()
se argumentos.tem("ajuda") { escreva(parser.ajuda()) }

CLI(descricao: texto = "") cria um parser. opcao(nome: texto, curto: texto = "", exigeValor: logico = falso, descricao: texto = ""): CLI registra a opção. Nomes/aliases duplicados e nomes inválidos lançam. analisar(argumentos: texto[]): ResultadoCLI permite entradas explícitas; atual(): ResultadoCLI usa Processo.argumentos(), sem outro acesso nativo ao argv. ajuda(): texto segue a ordem de registro; imprimir ajuda é decisão da aplicação.

Aceita --nome=valor, --nome valor, -n valor, flags --ajuda/-h, posicionais e -- para encerrar as opções. Um valor pode ser vazio ou começar com -. Opções desconhecidas, repetidas ou sem valor, assim como valor em flag booleana, lançam. Flags curtas agrupadas, subcomandos e conversão automática de números não fazem parte desta API. Não há abreviações implícitas ou execução de argumentos.

ResultadoCLI oferece tem(nome: texto): logico, valor(nome: texto, alternativa: qualquer = nulo): qualquer e posicionais(): texto[]. Flags presentes devolvem verdadeiro; opções com valor devolvem texto. Ausência devolve a alternativa. Posicionais são copiados ao consultar.

Log

importar("cgd:log").Logger é uma instância reutilizável. Seu construtor é Logger(nome: texto = "", minimo: inteiro = 1, usarErro: logico = verdadeiro, timestamp: logico = verdadeiro).

Os níveis são Logger.Nivel.Depuracao (0), Informacao (1), Aviso (2) e Erro (3). registrar(nivel: inteiro, mensagem: texto): vazio filtra pelo mínimo; depurar, info, aviso e erro recebem texto e devolvem vazio. O destino padrão é stderr; usarErro = falso escolhe stdout. O timestamp é Unix em segundos; pode ser desligado para saídas reproduzíveis. Nível fora de 0..3 e falhas de IO lançam.

O formato é [NIVEL] nome: mensagem, precedido pelo timestamp quando ativado. Não há arquivos de log, rotação, formatação de calendário ou sincronização entre threads. Quebras de linha e controles da mensagem são preservados: trate dados não confiáveis antes de registrar algo que possa imitar outra linha de log.

CTFE, arquitetura e próximos passos

Estas bibliotecas não liberam OS na VM. Processos, ambiente, IO, relógios e logs são dependentes do sistema e/ou têm efeitos; ficam fora de CTFE. Algoritmos e parsing de CLI são determinísticos para a mesma entrada, mas usam classes, coleções e métodos que não são aprovados pelo subconjunto CTFE atual. Duracao representa valores, mas também é uma classe e não recebe promessa de CTFE.

A camada Delégua compõe a API e os resultados. As primitivas ficam em sistema_posix.c, processo_posix.c e io_posix.c; o compilador apenas acrescenta os nomes dos módulos à resolução estática. Não há palavras-chave novas, lexer especial para bibliotecas ou relaxamento de pureza/capturas. Os módulos antigos e seus entry points C foram preservados.

Esta entrega conclui o núcleo síncrono P0 e acrescenta Algoritmos, CLI e Log. A expansão completa de diretórios/atomicidade/permissões, buffer de bytes, codificações, regex, hashes e iteradores incrementais continua pendente. Regex precisa de um mecanismo consolidado e dependência escolhida; criptografia não será inventada aqui. URI já tem primitivas em Rede/libcurl e deve ser construída sobre elas, sem outro parser concorrente. Processos persistentes precisam de ownership/cancelamento próprios. Compressão, concorrência, datas e configuração serão avaliadas após esses fundamentos; não há módulos vazios com esses nomes.

Critérios para as próximas fases

ÁreaDependência ou decisão antes de implementarAceitação mínima
Arquivos e diretóriosDefinir seguir/não seguir symlinks, sobrescrita, atomicidade e descritores de diretório. Reutilizar Arquivo.Testar falhas de permissão, links, troca concorrente de caminhos, interrupção e limpeza de temporários.
Bytes/codificaçãoAvaliar um buffer GC de bytes separado de texto, com índices em bytes e integração de tipos/ABI.Round-trip de todos os 256 valores, NUL, limites, endian e rejeição de encoding inválido. Não chamar vetor de números de buffer eficiente.
RegexEscolher um motor consolidado; PCRE2 é um candidato, com limites de trabalho e regras UTF explícitas.Capturas/substituição Unicode, sintaxe inválida, limites de complexidade e limpeza do handle. Sem compatibilidade anunciada antes de validar.
IteradoresProtocolos de parada, avaliação preguiçosa e efeitos; callbacks continuam sem captura.Consumir parcialmente sem avaliar o restante, propagar falhas e fechar recursos no cancelamento.
Hash/digestsSeparar hashing de coleções de digest criptográfico. Para digest, usar biblioteca consolidada e comparar implementações.Vetores oficiais, entrada binária completa e limites; nenhuma criptografia criada à mão.
CompressãoBiblioteca consolidada e buffer de bytes, com limite de expansão.Round-trip e rejeição de dados truncados, corrupção e expansão excessiva.
CriptografiaFonte de aleatoriedade do OS, biblioteca auditada e contrato de chaves.Vetores oficiais e revisão de ownership/segredos; não compor protocolos próprios.
ConcorrênciaRever contexto do runtime, exceções, GC e dados compartilhados; hoje não há esse contrato.Testes de corrida, cancelamento, propagação de erro e encerramento limpo.
SincronizaçãoDepende do contrato de concorrência.Ownership, deadlocks, reentrada e destruição com participantes ativos.
TerminalDetecção de TTY e capacidades, preservando IO como base.Pipes sem escapes inesperados e restauração do terminal após falha.
ConfiguraçãoCompor Arquivo/JSON/Ambiente; decidir precedência e formato.Precedência reproduzível, chaves inválidas e mensagens com origem.
DatasSeparar instante, calendário, timezone e duração; escolher fonte de fusos.Transições de horário, datas inválidas e round-trip.
SerializaçãoJSON já existe; outro formato precisa de uso concreto e schema/versionamento.Ciclos, aliases, evolução de formato, limites e dados inválidos.

Timeout não é uma garantia de tempo real: o prazo é verificado pelo loop de acompanhamento, e a inicialização síncrona da libc ou um estado ininterruptível do kernel podem atrasar o retorno. A coleta do filho ainda é necessária para evitar zumbis. Estas bibliotecas não fornecem isolamento de segurança de subprocessos.

Um servidor HTTP no executável

cgd:rede continua sendo o cliente HTTP. Para receber requisições, importe cgd:servidor: o programa abre seus próprios sockets, sem Node, Python, shell ou um servidor externo no caminho da comunicação.

Esta é a primeira etapa da infraestrutura de serviços: TCP IPv4 e um perfil restrito de HTTP/1.1, com uma requisição por conexão. O servidor atende um cliente por vez. Isso permite definir propriedade dos recursos e comportamento das exceções antes de acrescentar concorrência ao runtime.

Primeiro programa

const Servidor: qualquer = importar("cgd:servidor")
var app: qualquer = Servidor.HTTP()

app.get("/", funcao(req: qualquer, res: qualquer): vazio {
    res.enviar("Olá, mundo!\n")
})
app.post("/usuarios", funcao(req: qualquer, res: qualquer): vazio {
    res.status(201).json({ criado: verdadeiro, usuario: req.json() })
})
app.escutar("127.0.0.1", 8080)

Compile normalmente e execute o binário. O exemplo completo em exemplos/servidor/http.delegua também mostra parâmetros e encerramento. No catálogo geral ele tem contrato de compilação, pois iniciar um serviço bloqueante não cabe no runner de exemplos. O teste testes/servidor.py inicia o serviço e faz requisições reais nos dois modos.

Os callbacks recebem a requisição e a resposta como argumentos. Continuam valendo as restrições do CGD: não capturam variáveis locais externas. Passe informações entre middleware e rota por req.contexto.

Rotas e middleware

get, post, put, patch, delete, head e options recebem um caminho e uma função (req: qualquer, res: qualquer): vazio. rota(metodo, caminho, tratar) é a forma geral, com método maiúsculo. Registrar a mesma combinação duas vezes lança uma exceção. A primeira rota compatível na ordem de registro é executada.

Um segmento :nome captura um parâmetro. /usuarios/:nome aceita /usuarios/Jos%C3%A9; req.parametro("nome") devolve José. Não há wildcards, expressões regulares ou conversão automática de parâmetros. A barra final faz parte do caminho. HEAD precisa de rota própria; não executa GET implicitamente. options("*", callback) atende OPTIONS * explicitamente.

Sem rota para o caminho, a resposta é 404. Havendo caminho mas não método, é 405 com Allow. Não há CORS, autenticação nem OPTIONS automático.

app.usar(funcao(req: qualquer, res: qualquer): vazio {
    req.contexto["origem"] = "middleware"
    res.cabecalho("x-aplicacao", "exemplo")
    se req.caminho == "/indisponivel" {
        res.status(503).enviar("Tente novamente depois")
    }
})

usar(callback) executa middleware na ordem de registro. Uma resposta definida por enviar ou json encerra o despacho; caso contrário, o próximo middleware e depois a rota são executados. Não existe next() assíncrono. Cada requisição tem seus próprios mapas de contexto e parâmetros e sua própria resposta.

Requisicao

MembroContrato
metodo: textoMétodo recebido, sensível a maiúsculas.
caminho: textoCaminho decodificado uma vez, sem query.
alvo: textoRequest target original, ainda com escapes e query.
cabecalhos: dicionarioNomes em minúsculas; valores textuais.
consulta: dicionarioCada chave contém um vetor de valores, preservando repetições.
parametros: dicionarioSegmentos capturados pela rota.
contexto: dicionarioDados explícitos da aplicação/middleware.
texto(): textoCorpo completo; o tamanho de transporte é medido em bytes.
json(): qualquerUsa o parser de cgd:json e seus limites próprios.
parametro(nome, alternativa = nulo): qualquerObtém um segmento ou a alternativa.
query(nome, alternativa = nulo): qualquerObtém o primeiro valor de query ou a alternativa.

Em query, + representa espaço e %2B representa +. Em caminhos, + permanece literal. Escapes inválidos, controles, NUL, barras codificadas, contrabarras e segmentos ./.. são recusados com 400. Não existe serviço de arquivos embutido: um caminho de URL nunca é usado como caminho do sistema de arquivos. A aplicação que construir seu próprio serviço de arquivos precisa confinar a raiz de acesso.

texto do runtime armazena bytes; não há validação de UTF-8 de todo corpo HTTP. Use JSON/texto válido nas operações Unicode. O transporte preserva inclusive NUL no corpo, mas não nos headers ou no caminho. O Content-Type recebido não altera o parser automaticamente. req.json() inválido lança; a rota pode capturar e responder 400. Uma exceção não tratada no handler resulta em 500 genérico.

Resposta

MétodoEfeito
status(codigo: inteiro): RespostaCódigo final 200..599; padrão 200.
cabecalho(nome: texto, valor: texto): RespostaDefine um header; o nome é normalizado.
enviar(corpo: texto = ""): RespostaDefine o corpo; não faz I/O imediatamente.
json(valor: qualquer): RespostaSerializa JSON e define Content-Type apropriado.
definida(): logicoInforma se enviar/json já foi chamado.
pararServidor(): RespostaSolicita fechar o listener após transmitir esta resposta.
deveParar(): logicoConsulta essa solicitação.

O tipo inicial é text/plain; charset=utf-8. A resposta fica em memória até o handler terminar; não há streaming. Uma rota que termina sem definir a resposta produz 204 vazio. Os status 204, 205 e 304 não aceitam corpo nesta API. HEAD transmite os headers e o tamanho do corpo que seria enviado, mas nenhum byte do corpo. O runtime calcula Content-Length em bytes, inclusive para Unicode.

Date, Content-Length, Transfer-Encoding, Connection, Trailer e Upgrade são reservados ao transporte. Não podem ser sobrescritos. Date usa UTC e nomes de meses/dias em inglês, sem depender do locale do processo. Nomes inválidos, CR/LF e outros controles nos valores são recusados antes do envio. Se a validação da resposta falhar, o servidor tenta responder 500 genérico. Se o transporte já falhou, fecha a conexão e segue atendendo. Nenhum detalhe da exceção, credencial ou corpo é registrado automaticamente.

Ciclo de vida e limites

HTTP(maxCabecalhos = 16384, maxCorpo = 1048576, leitura = 10000, escrita = 10000) recebe limites em bytes e prazos em milissegundos. Argumentos inválidos falham na construção, antes de abrir sockets.

RecursoLimite
Headers de requisiçãoConfigurável, 256..65536 bytes, incluindo request line.
Quantidade de headers100 por requisição e por resposta.
Corpo de requisiçãoConfigurável, 0..16777216 bytes.
Corpo de respostaAté 16777216 bytes.
Headers de respostaAté 65536 bytes.
Parâmetros de queryAté 256 ocorrências.
Leitura/escritaCada prazo entre 1 e 86400000 ms; relógio monotônico.
Conexões HTTP ativasUma por instância em atendimento sequencial.
Backlog64, sujeito ao limite do kernel.
Sockets vivos do runtime128, incluindo listeners e clientes TCP.
Requisições por conexãoUma; Connection: close em toda resposta.

O prazo de leitura cobre headers e corpo juntos e não reinicia a cada byte. O prazo de escrita cobre headers e corpo juntos. Assim, um cliente lento não mantém uma conexão indefinidamente. Ainda pode atrasar os próximos clientes até o prazo expirar: esta versão sequencial não promete resistência a uma inundação de conexões nem isolamento entre aplicações.

O parser exige HTTP/1.1, Host não vazio e CRLF. Host aceita nome ASCII sem escapes percentuais ou endereço IPv6 entre colchetes, com porta opcional 0..65535. Métodos fora dos sete disponíveis são recusados com 501; o alvo * é exclusivo de OPTIONS. Rejeita headers repetidos (inclusive Content-Length idênticos), folding e Content-Length inválido. Transfer-Encoding é recusado com 501; Expect, com 417. Corpo excessivo produz 413, headers excessivos 431 e prazo de leitura expirado 408. Mensagem incompleta ou inválida produz 400 quando ainda for possível responder. Não tenta recuperar a conexão ou interpretar uma segunda mensagem depois de erro.

Não há keep-alive, chunked, pipelining, streaming, WebSocket, SSE, multipart, upload, TLS, HTTP/2 ou compressão de resposta. Bytes extras depois da primeira requisição são descartados ao fechar; uma segunda requisição não executa rota. O perfil se baseia no framing de RFC 9112, com as restrições adicionais descritas aqui; não afirma implementar o protocolo inteiro.

abrir(endereco = "127.0.0.1", porta = 8080) abre o listener sem entrar no laço. portaLocal() permite descobrir a porta escolhida com porta = 0. atenderUma(timeout = 1000) aceita e trata uma conexão; devolve falso se a espera por conexão expirar. ativo() consulta o estado do listener. Isso permite que a aplicação controle seu próprio laço e condição de encerramento. escutar(endereco, porta) reúne abrir, laço e fechamento em finally.

fechar() é idempotente e fecha o listener; cada conexão aceita é fechada em finally, mesmo se o handler falhar. pararServidor() encerra após a resposta atual; não instala handlers globais de sinais nem oferece cancelamento entre threads. O destrutor chama fechar, mas use fechamento explícito/finally. Um finalizador GC é apenas contingência: não há prazo garantido para sua execução.

cgd:sockets

A camada TCP pode ser usada separadamente:

const Sockets: qualquer = importar("cgd:sockets")
var conexao: qualquer = Sockets.conectar("127.0.0.1", 9000, 1000)
tente {
    conexao.enviar("mensagem", 1000)
    var resposta: texto = conexao.receber(65536, 1000)
} finalmente {
    conexao.fechar()
}

conectar(endereco, porta, timeout = 30000) devolve Conexao. OuvinteTCP(endereco = "127.0.0.1", porta = 0) cria um listener; aceitar(timeout = 1000) devolve Conexao ou nulo no timeout. Ambos têm portaLocal() e fechar() idempotente. Conexao.enviar transmite integralmente até 16 MiB e devolve bytes enviados. receber(limite = 65536, timeout = 30000) lê até o limite (1..16777216 bytes); pode devolver um bloco menor. Texto vazio representa EOF. Timeout ou falha de I/O fecha a conexão e lança, evitando continuar um protocolo após uma operação incompleta.

Conexao.lerHTTP/responderHTTP são a adaptação usada pelo servidor. Não misture leituras TCP manuais e parsing HTTP na mesma conexão. Erros de validação antes do I/O lançam; o proprietário continua responsável por fechar em finally.

Os identificadores nativos são opacos e verificados por tag; não são números, FDs, ponteiros Delégua nem sessões curl. Aliases compartilham o mesmo recurso: fechar por um alias invalida os demais. Descritores são nonblocking/CLOEXEC, com espera síncrona via poll e envio sem SIGPIPE. Endereços de abertura aceitam IPv4 ou IPv6 numéricos sem DNS implícito; resolução explícita usa Sockets.resolverDNS(host, familia) e datagramas usam Sockets.abrirUDP.

Para atendimento concorrente com HTTP/1.1 keep-alive sobre o reactor epoll, HTTP oferece escutarAsync(endereco, porta, maxRequisicoesPorConexao) e atenderConexaoAsync(conexao, maxRequisicoes), reutilizando o mesmo parser validado e a mesma tabela de rotas e middlewares de HTTP. A implementação atual usa accept4 e flags de sockets do Linux; somente Linux x86_64 é a plataforma validada do projeto.

Validação e desempenho

python3 testes/servidor.py verifica rotas, os sete métodos, middleware, Unicode, JSON, corpos binários, framing hostil, tamanhos, timeout, mensagens parciais, pipelining recusado, desconexões, clientes simultâneos atendidos em sequência, fechamento e shutdown. python3 testes/sockets.py cobre cliente TCP, EOF, identificador inválido, reuso de porta e fechamento. Ambos compilam com e sem otimização. O parser puro tem regressões e corpus pseudoaleatório determinístico em testes/http_parser.c; o runner com sanitizadores fica em python3 testes/http_parser.py. Isso não substitui fuzzing contínuo ou auditoria.

scripts/benchmark_http.py mede várias rodadas de conexões novas, RPS, latências p50/p95/p99, RSS máximo observado, CPU do servidor e tempo de inicialização. Os resultados incluem configuração do cliente e sistema e ficam em JSON. Não há resultado de desempenho publicado nesta etapa nem comparação com outros servidores.

Assincronismo nativo do CGD

Data: 18/11/2026. Projeto das Etapas 0–5 e implementação experimental de async/await, handlers, cancelamento, reactor, timers, HTTP e TCP. As seções 1–15 especificam o modelo alvo; as seções 16–17 registram a evolução. As mudanças de 18/11 ainda não foram testadas por instrução do usuário. Não declarar estabilidade. A preparação das rotinas está descrita em rotinas.md.

O CGD é uma implementação própria do perfil compilado de Delégua, com extensões explícitas; não representa o interpretador oficial. Autoria e licença Apache-2.0 dos projetos continuam preservadas. O runtime permanece no submódulo delegua-runtime.

1. Escopo e decisões de base

A primeira entrega será assincronismo cooperativo em uma thread Linux x86_64, com funções stackless, Promessas nativas, microtasks e reactor. Uma chamada assíncrona não cria thread. Capturas externas continuam proibidas; argumentos e receptores são a passagem explícita de dados. Aliasing entre tarefas da mesma thread continua possível quando o programa passa o mesmo objeto: execução sequencial de segmentos evita data races nativas, mas não elimina interferência lógica entre pontos de suspensão.

O runtime possui um pool interno Linux que entrega resultados de callbacks C ao reactor. A execução de funções Delégua nos workers depende da auditoria de threads e da validação do assincronismo. Canais, grupos, M:N e stacks próprias permanecem em etapas futuras. Consulte rotinas.md.

Decisões propostas para fixar o contrato antes do código:

TemaDecisão
Sintaxeassincrona como modificador de função/método; aguardar prefixo
Resultadoassinatura declara T; chamada produz Promessa
Inícioexecução imediata até primeira suspensão ou conclusão
Awaitsomente em corpo assíncrono, inclusive quando o operando já terminou
Operandosomente Promessa nativa; qualquer exige verificação dinâmica
Retornoretorna T; delegação exige retorna aguardar outra()
Cancelamentopedido cooperativo sobre tarefa proprietária; não sobre dependências
Finalmentepode suspender; cancelamento fica mascarado durante limpeza
MicrotasksFIFO drenada integralmente em cada checkpoint
Módulosinicialização síncrona, sem await no topo
Entradaexecutar raiz síncrona, depois drenar loop no runtime
CompatibilidadeAPIs síncronas preservadas; novas APIs têm nomes/importações próprios

Essas decisões são normativas para a implementação proposta. Mudá-las exige atualizar este documento e os testes correspondentes antes de mudar o código.

2. Auditoria do estado existente

Base inspecionada: CGD abe4290, runtime 7833699, mais alterações locais. Os hashes não reproduzem sozinhos o estado auditado: bibliotecas de sistema, sockets e servidor HTTP estão modificadas/não versionadas. Nenhuma dessas alterações foi revertida. Não houve commit ou publicação nesta etapa.

Área e fontesRepresentação observadaReuso e lacuna
frontend/lexer/token.d, keywords.d; parser/parse_decl.d, parse_expr.dtokens próprios, declaração FnDecl e FunctionExpr; métodos com isStaticacrescentar Async/Await, sem tratar async como chamada comum
parser/ast.dAST compartilhada por validação, semântica, otimização, lowering e editoracrescentar marcador de função e nó AwaitExpr; atualizar todas as travessias
type_expr.d, parser/parse_type.dtipos nomeados, arrays, tuplas; nenhum argumento genéricoPromessa precisa de representação sintática própria e leitura de <T> em contexto de tipo
type_sema.d, type_registry.d, type_resolver.dtipos builtin, array, tupla e classe; funcao sem assinatura paramétrica completaadicionar Promise e contrato de chamada assíncrona, sem reduzir Promessa a qualquer
semantic/pipeline.d, analyzer.d, context.ddeclarações, resolução, segurança, pureza e fluxo comuns à CLI/LSP; capturas recebem aviso e erroreusar identidade de vínculos e contexto lexical; separar retorno interno T de resultado da chamada
semantic/flow.danálise conservadora de término e caudas, sem CFG/vivacidadenecessária análise nova por arestas normais e excepcionais
middle/lowering.dreescrita recursiva AST → chamadas de runtime; preserva curto-circuitoinsuficiente para suspensões; introduzir IR assíncrona antes da emissão C
middle/rewrite.d, opt/pass_manager.d, ctfe/travessias e otimização até ponto fixo; CTFE de funções elegíveisAwait é efeito/barreira; funções assíncronas não entram na VM
backend/c/codegen.d, lvalue.dmaterialização ordenada, funções C com argc/argv, variáveis tagged, contratos e descritores estáticosreusar avaliação e contratos; emitir wrapper e step próprios para async
runtime/src/objetos.cfunção contém ponteiro C, aridade mínima/máxima, receptor ligado e decoradores; objetos têm classe e mapa de camposwrapper async conserva ABI de chamada; não há ambiente de closure lexical a reutilizar
runtime/src/excecoes.c, delegua_rt.hcadeia active, setjmp/longjmp, profundidade global; backend duplica limpeza nas saídasnunca preservar jmp_buf como continuação; handlers suspensos serão dados da IR
runtime/src/interno.h, delegua_rt.hrt_alloc usa GC_MALLOC; texto usa alocação atômica; delegua_value é tagged com referênciasframes e listas precisam de memória rastreada; buffers sem ponteiros podem ser atômicos
runtime/src/delegua_rt.cGC_INIT, contexto, delegua_main, liberação de contexto, saídaintegrar loop após raiz e antes de liberar contexto; preservar programa síncrono
runtime/src/rede.ccurl_easy_perform síncrono; lote usa curl_multi_perform/poll até terminarreusar opções, limites, TLS e conversão; lote atual não é async da linguagem
sockets_posix.c, http_servidor.c locaisdescritores nonblocking opacos, mas API espera com poll/prazos dentro da chamadareusar validações/close; separar iniciar/tentar/registrar, sem chamar espera síncrona pelo reactor
processo_posix.c, sistema_posix.c; bibliotecas processo/tempopoll de pipes/waitpid e dormir síncronosmanter contratos; processos assíncronos ficam para extensão posterior
frontend/modules.d, analysis.d, lsp/módulos estáticos, buffers por revisão, análise sem codegen/CTFE/processosnamespace assíncrono estático; editor usa mesmos tipos e diagnósticos

Pontos críticos confirmados pela leitura:

  • compileFnDecl() emite função retornando delegua_value e materializa isto em métodos não estáticos. functionValue() cria função com aridade; referências indiretas passam por delegua_chamar(). Isso permite devolver uma Promise pela ABI atual, mas exige metadados novos para contratos de retorno e editor.
  • compileTry() e cleanupCode() implementam pegue/finalmente com frames C. Mesmo quando delegua_try_frame é alocado no GC, seu jmp_buf referencia uma ativação C. Retomar esse frame depois de retornar seria inválido.
  • Destrutores são explícitos e possuem proteção de reentrada em objetos.c. Sair de um escopo não chama destrutor automaticamente. Async não introduzirá destruição automática de objetos do usuário; operações nativas têm limpeza interna obrigatória e o programa continua usando finalmente para fechar recursos.
  • active, delegua_call_depth, localização atual e contadores nativos são estado global. Uma thread simplifica acesso, mas cada step ainda precisa salvar e restaurar contexto antes de entregar o controle a outra tarefa.
  • pkg-config local informou Boehm 8.2.6 e headers libcurl 8.22.0-DEV. Isso não verifica versão carregada, resolvedor DNS ou configuração de threads do GC. Não houve execução de programa para validar essas propriedades nesta etapa.

3. Gramática e contextos

Delta EBNF sobre a gramática existente (bloco, parâmetros e expressões mantêm suas regras atuais):

declaracao_funcao = ["assincrona"], palavra_funcao, nome,
                   "(", parametros, ")", [":", tipo], bloco ;
expressao_funcao = ["assincrona"], palavra_funcao,
                  "(", parametros, ")", [":", tipo], bloco ;
metodo = [modificador_estatico], ["assincrona"], nome,
         "(", parametros, ")", [":", tipo], (bloco | assinatura_abstrata) ;
unaria = "aguardar", unaria | unaria_existente ;
tipo_primario = "Promessa", "<", tipo, ">" | tipo_primario_existente ;

palavra_funcao inclui os aliases atuais funcao/função. A grafia nova inicial é assincrona, sem aliases ingleses. aguardar f().campo aguarda o resultado da expressão de chamada/acesso; (aguardar f()).campo acessa o valor resolvido. aguardar a + b significa (aguardar a) + b. O parser deve tratar fechamentos de Promessa<Promessa<inteiro>> em contexto de tipo sem alterar shifts em expressões. Promessa é construtor de tipo intrínseco, não genéricos arbitrários de classes. Promessa<T>[] é válido. Promessa sem T em anotação é erro.

Métodos seguem a sintaxe de classe existente, sem palavra funcao. Ordem inicial: estatico assincrona nome(). Blocos de visibilidade continuam externos ao método. Arrows assíncronas são adiadas; funções anônimas assíncronas com funcao atendem callbacks sem introduzir outra precedência.

Permitido: aguardar em laços, condicionais, argumentos, retornos, pegue e finalmente dentro do corpo async. O contexto reinicia em cada função aninhada: uma função síncrona interna não herda permissão de aguardar.

Proibido: aguardar no topo do programa/módulo, defaults de parâmetros, inicializadores de atributos, decoradores, construtores, destrutores, getters e setters. Construtores e destrutores não podem ser assincronos; fábricas async explícitas podem construir objetos. Assinaturas FFI não podem receber modificador async: uma ABI escalar não vira operação não bloqueante por anotação. Métodos de interfaces/abstratos podem declarar async; implementação e override devem manter o efeito e o contrato de resultado.

Adicionar palavras-chave é uma quebra lexical para identificadores homônimos. Antes da Etapa 2, inventariar fontes/bibliotecas e documentar migração; não reinterpretar código silenciosamente.

4. Tipos e regras de chamada

Escrevemos Γ ⊢ e : T para tipagem e A para contexto de corpo assíncrono.

assincrona f(args): T  ⇒  tipo de chamada f(args) = Promessa<T>
Γ ⊢ p : Promessa<T>, contexto = A  ⇒  Γ ⊢ aguardar p : T
Γ ⊢ retorna e, corpo async com retorno T  ⇒  e deve satisfazer T

Promessa é invariante. Promessa não satisfaz inteiro nem Promessa. Uso de qualquer mantém guardas dinâmicas, inclusive contrato do valor resolvido. Preservar descritor de T na Promise e nas fronteiras de variáveis, campos, parâmetros, retornos e coleções; não validar apenas a tag. Promessa resolve internamente nulo; aguardar como comando é permitido, usar seu resultado em posição que exige valor recebe diagnóstico.

Uma função async com retorno T verifica T quando completa, não contra a Promise externa. Retorno implícito conserva a regra atual da linguagem: aviso de fluxo quando aplicável e verificação dinâmica correspondente, sem inventar default. retorna p onde p é Promessa não substitui retorna aguardar p quando o retorno declarado é T. Um retorno explicitamente Promessa produz Promessa<Promessa>; não há assimilação automática no retorno de funções.

O operando qualquer de aguardar deve ser uma Promise nativa em execução; caso contrário lança Excecao. Valores comuns e objetos com método entao não são assimilados. Essa é uma diferença deliberada em relação ao await JavaScript.

Funções síncronas podem criar, receber, armazenar e devolver Promessas, registrar entao/capturar e iniciar funções async. Não podem bloquear para obter seu valor nem executar o loop recursivamente. Uma função síncrona que retorna Promessa é distinta de uma função async que retorna T.

O builtin funcao atual não expressa toda essa assinatura. Acrescentar metadados de efeito, parâmetros e retorno aos símbolos de funções/métodos; chamadas indiretas conhecidas usam esses dados. Nas desconhecidas, resultado qualquer passa por validação nativa. O LSP não deve prometer uma assinatura inventada.

Avaliar callee, receptor e argumentos da esquerda para a direita antes de entrar no corpo. Erro nessa avaliação e erro de aridade de delegua_chamar permanecem síncronos. Depois de criada a Promise no wrapper, defaults, contratos dos parâmetros e execução do corpo falham por rejeição. Falha irrecuperável de alocação antes de criar a Promise não ganha garantia de rejeição.

5. Ciclo de vida e Promessas

Promise e ativação são entidades diferentes. Uma Promise contém estado PENDENTE, RESOLVIDA ou REJEITADA, descritor de resultado, valor/erro, localização da falha, reações FIFO e observação. Uma ativação contém pc, handlers, conclusão pendente, slots vivos, referência à Promise de saída e cancelamento. Promessas resolvidas manualmente não precisam de ativação.

Transição terminal é única. Há também trava interna de resolução: adotar outra Promise mantém PENDENTE, mas impede outro resolve/reject de ganhar. Autoadotar ou criar ciclo na cadeia de adoção rejeita com Excecao; atravessar a cadeia deve ter limite de recursos. Após terminal, liberar reações destacadas e referências que não sejam resultado/erro ainda observáveis.

API inicial proposta:

APIContrato
Promessa.resolvida(valor)devolve Promise terminal; reações sempre diferidas
Promessa.rejeitada(erro)normaliza erro como Excecao e devolve Promise rejeitada
p.entao(callback)nova Promise; callback recebe resultado; rejeição é encaminhada
p.capturar(callback)nova Promise; callback recebe Excecao; sucesso é encaminhado
p.cancelar()logico: indica novo pedido aceito por uma ativação proprietária ativa

Callback executa em microtask e não captura léxico externo. Método ligado pode conservar receptor explícito. Se callback devolve Promise nativa, a Promise de encadeamento adota seu destino; se devolve valor, resolve; se lança, rejeita. Não assimilar objetos arbitrários. A tipagem do encadeamento usa retorno do callback conhecido; qualquer exige contrato em execução.

Não expor executor com closures de resolução nesta primeira API. A resolução de operações nativas pertence a primitivas controladas; ponteiros e continuadores C permanecem internos. cancelamento de Promise sem ativação proprietária, incluindo Promise terminal, retorna falso; não simular cancelamento de valor.

Combinadores entram depois da base: todas preserva ordem dos resultados e rejeita na primeira falha observada; corrida segue primeira conclusão; qualquer resolve no primeiro sucesso e agrega falhas em ordem de entrada; todasResolvidas retorna registros de estado na ordem de entrada. Entrada deve ser coleção de Promessas nativas. Casos vazios: todas/todasResolvidas resolvem vetor vazio, qualquer rejeita erro agregado, corrida permanece pendente. Perder uma corrida não cancela operações compartilhadas. Cada combinador instala observadores nas entradas antes de permitir notificação; nenhuma reação inline.

6. Ordem de execução e Event Loop

Uma chamada async executa imediatamente seu segmento inicial. Toda ocorrência de aguardar suspende e retorna ao chamador, mesmo com Promise já resolvida ou rejeitada. O primeiro segmento pode terminar sem suspensão: devolve Promise terminal e continuações ainda passam pela fila. Sem preempção; código CPU longo e chamadas síncronas bloqueantes impedem progresso do loop.

Componentes: fila FIFO de eventos prontos, fila FIFO de microtasks, heap mínimo de temporizadores por (prazo monotônico, sequência), reactor epoll e registro fortemente enraizado de ativações/operações pendentes. Não criar fila adicional de tarefas com uma prioridade indefinida.

Algoritmo do loop:

  1. Ao retornar a raiz síncrona, executar checkpoint de microtasks.
  2. Enquanto houver microtasks, retirar e executar uma, incluindo as anexadas durante essa drenagem. Cada execução salva/restaura contexto de diagnóstico.
  3. No fim da drenagem, registrar rejeições não observadas para diagnóstico.
  4. Coletar timers vencidos em ordem (prazo, sequência). Consultar epoll com timeout zero se já houver eventos prontos; caso contrário, esperar até o próximo prazo ou evento. Tratar EINTR recalculando o prazo monotônico.
  5. Eventos de I/O do mesmo lote são ordenados pelo identificador de registro; anexar primeiro timers vencidos, depois I/O, à fila pronta. Eventos que já estavam na fila permanecem à frente. Não prometer ordem entre chegadas reais em instantes diferentes.
  6. Retirar um evento pronto, avançar operação limitada e realizar novo checkpoint.

Uma reação já registrada é enfileirada quando a Promise termina; reação nova em Promise terminal é anexada ao fim das microtasks. Retomada de await é uma dessas reações. Nenhuma resolução chama código Delégua recursivamente.

Exemplo de ordem normativa: a raiz escreve A, chama função async que escreve B, aguarda Promessa.resolvida(1), depois escreve D; a raiz escreve C. Saída: A, B, C, D. TempoAssincrono.dormir(0) é evento de timer e fica depois das microtasks já prontas.

Drenagem integral pode causar starvation se o programa gerar microtasks infinitamente; não haverá quota silenciosa que mude essa ordem. Limites de memória/pendências devem rejeitar novas operações com erro explícito. As quotas de operações por callback de I/O são separadas da ordem de microtasks.

O único bloqueio legítimo de espera de I/O no loop é epoll_wait quando não há trabalho pronto. Usar level-triggered inicialmente. Ler/escrever até EAGAIN ou budget por evento; nesse último caso, registrar continuação justa na fila pronta. Não tratar regular files como sockets assíncronos por terem descritor.

7. IR, vivacidade e lowering

Introduzir módulos próprios, por exemplo middle/async_ir.d, async_lowering.d e liveness.d; nomes são propostos, arquivos ainda não existem. O fluxo futuro:

lexer/parser → módulos → validação → semântica/fluxo/segurança
→ otimização AST opcional com barreiras de efeito
→ normalização ordenada → CFG async → vivacidade → layout do frame
→ emissão C99 de wrapper/step (síncronas mantêm caminho existente)

O lowering existente de operações será fatorado/reutilizado pela normalização; não executar uma reescrita que apague vínculos, tipos ou posições necessários à análise. Ordem exata entre normalização e lowering de operadores deve ficar fixada no primeiro teste da IR. --verificar e LSP param na análise semântica.

IR por função: blocos identificados, temporários tipados, locais por identidade resolvida, descritores de localização, região lexical, região de exceção e arestas normais/excepcionais. Instruções: avaliar, copiar, contrato, chamada, acesso, escrita e manipulação de handlers. Terminadores: salto, desvio, suspender, concluir e lançar. Suspender contém operando Promise, destino do resultado, sucessores de sucesso/falha/cancelamento e geração de espera.

Normalizar expressões em operações sequenciais antes de separar estados. Em f(a(), aguardar b(), c()), materializar f e a, iniciar b, suspender, recuperar valor, então avaliar c. Em atribuição indexada, persistir receptor e índice se vivos, sem refazer getters. Curto-circuitos, coalescência, ternário, laços, compreensões, interpolação e spreads mantêm seus ramos e efeitos. Não guardar ponteiro para elemento de vetor que possa realocar durante suspensão: guardar container/índice e aplicar a escrita segundo o contrato de avaliação original.

Calcular ponto fixo sobre CFG incluindo caminhos excepcionais e finalmente:

OUT[b] = união de IN[s] para sucessores s
IN[b]  = USE[b] união (OUT[b] menos DEF[b])

Promover ao frame apenas vínculos/temporários que atravessam suspensão, além de metadados obrigatórios de controle. Defaults, receptor e argumentos só persistem quando vivos; o wrapper consome/copía argv antes de devolver controle, sem reter ponteiro para argv do chamador. Referências em handlers e conclusões pendentes entram em USE. Um slot morto pode ser limpo após seu último uso; isso não autoriza descartar sua inicialização ou atribuições com efeitos.

Frame esquemático C99, sem ABI pública nova de callbacks para a linguagem:

struct exemplo_frame {
    unsigned pc;
    unsigned status;
    size_t wait_generation;
    delegua_value output;
    delegua_value pending_completion;
    const delegua_local *location;
    /* handlers, cancelamento e somente os slots vivos nesta função */
};

Wrapper conserva delegua_value f(sz argc, delegua_value *argv) e devolve a Promise. Step tem ponteiro de frame interno e roda switch(pc) em laço até suspensão/conclusão; saltos internos não precisam recursão C. await registra reação e estado seguinte antes de devolver. Nunca usar stack C ou jmp_buf como continuação. Recursão async antes de primeira suspensão ainda consome stack C; preservar limite de profundidade e diagnóstico atual, sem alegar stack constante.

Estado de ativação: EXECUTANDO → SUSPENSA → PRONTA → EXECUTANDO, ou FINALIZADA. Uma espera carrega identidade e geração. Evento obsoleto é ignorado; reação só transita SUSPENSA uma vez; fila não insere ativação já PRONTA; step rejeita reentrada; FINALIZADA nunca retoma. Verificador da IR confere sucessores, tipos, definições dominantes e slots necessários em toda suspensão.

8. Exceções, finalmente e cancelamento

Cada invocação de step instala uma fronteira C de exceção válida somente durante essa invocação. longjmp de primitivas síncronas é capturado nela, convertido em conclusão excepcional e roteado pela tabela/stack de handlers da IR. Antes de suspender/concluir, remover a fronteira e restaurar active, profundidade e localização do chamador. Não copiar active entre tarefas. Locais C modificados após setjmp e lidos no erro precisam obedecer às regras C de volatile ou residir no frame; revisar isso no backend e testar com otimização.

Conclusão explícita: NORMAL, RETORNO(valor), FALHA(erro), SALTO(destino), CANCELAMENTO(erro). finally recebe a conclusão pendente, pode suspender e, quando termina normalmente, a restaura. Return/throw/break/continue de finally substituem a conclusão como no contrato síncrono; falha de limpeza substitui falha anterior, preservando-a como contexto de diagnóstico sem imprimi-la duas vezes. finally entra uma vez por saída da região, inclusive em cancelamento.

Rejeição de operando await segue a aresta excepcional na localização de await, com origem da falha preservada separadamente. pegue recebe Excecao pelo contrato existente. Localização usa descritores estáticos; renderizar só no erro.

Cancelar marca um pedido idempotente. Pontos seguros: início de step e retomada de await, nunca instrução C arbitrária. Cancelar ativação suspensa invalida sua reação de espera, agenda retomada com Excecao de cancelamento e inicia unwind. Se sucesso já foi enfileirado mas step ainda não começou, pedido de cancelamento ganha no ponto seguro. Se tarefa já concluiu, pedido retorna falso.

O cancelamento é injetado uma única vez, pode ser tratado por pegue e não cancela a Promise aguardada, que pode ter outros consumidores. Durante finally iniciado por unwind, mascarar nova injeção até completar a limpeza; awaits de limpeza podem portanto demorar indefinidamente. Não prometer timeout forçado seguro. Se pegue consumir cancelamento e terminar normalmente, a tarefa pode resolver.

Uma operação nativa tem dono e cancel hook idempotente. Cancelar sua própria tarefa remove interesse no reactor, solta recursos e rejeita sua Promise; cancelar um consumidor não fecha recurso compartilhado do produtor. Callbacks curl/OS não podem executar código Delégua nem longjmp através de frames de biblioteca: registrar código de erro/abortar pelo retorno nativo e converter em rejeição depois de sair da biblioteca. Inclusive falhas de alocação exigem essa disciplina; os callbacks atuais devem ser auditados antes de reuso.

9. Encerramento e rejeições não observadas

Após a raiz síncrona, loop drena tarefas iniciadas, mesmo sem variável guardando sua Promise. Registro de ativações é raiz de GC até finalizar. Não criar tarefa órfã esquecida porque o usuário descartou o resultado.

Registrar rejeição como observada quando existe await, capturar ou encadeamento que a encaminha para outra Promise. No último caso, responsabilidade passa ao destino: entao sem tratador não suprime erro. No checkpoint, marcar rejeição terminal sem observador como candidata; observador posterior antes do shutdown retira a candidatura. No encerramento, renderizar candidatas em ordem de criação e sair com falha. Não interromper outras limpezas na primeira rejeição candidata.

Se não há trabalho pronto, timer ou registro de I/O capaz de progredir, mas há ativação suspensa, diagnosticar falta de progresso. Solicitar cancelamento das ativações, drenar limpezas possíveis, reportar pendências restantes e sair com falha; não girar em busy-wait nem declarar sucesso. Promise pendente isolada sem consumidor/ativação, como corrida vazia descartada, não mantém loop vivo. Rejeições não observadas continuam contabilizadas até shutdown.

Operação de I/O registrada pode nunca terminar: o programa permanece ativo até deadline/cancelamento explícitos. Saída abrupta por sinal/abort não garante finally. Falha síncrona não capturada na raiz deve passar pela fronteira externa do runtime futuro: cancelar/drainar tarefas antes de reportar; manter ABI C antiga de delegua_falhar fora desse contexto. Falta de memória fatal pode impedir limpeza.

10. GC, recursos e ABI

Frames, Promessas, reações e nós de filas usam GC_MALLOC/rt_alloc rastreado, nunca GC_MALLOC_ATOMIC quando contêm referências. O loop permanece alcançável por raiz global/contexto durante toda a execução. Registro liga operação → Promise → frame/reações; uma fila nativa alocada com malloc não é raiz suficiente. Dados guardados em epoll.data ou CURLOPT_PRIVATE também precisam desse registro. O coletor conservador pode reter memória; não prometer liberação imediata.

Desvincular reação cancelada da Promise produtora, limpar slots mortos e remover operação terminal do registro. Ciclos sem raízes podem ser coletados; Promise rejeitada candidata mantém erro até observação/relatório. Evitar criar histórico ilimitado de frames para diagnóstico: referências de origem têm limite explícito.

FDs, CURL easy/multi e buffers externos têm proprietário e close determinístico; finalizadores GC são apenas contingência. Remover registro epoll antes de close; usar geração por registro para não aceitar evento de FD reutilizado. Cancel hook e conclusão competem por uma única transição terminal na thread do loop.

Adicionar tag de Promise ao final da enumeração tagged, preservando números, layout e símbolos C existentes. Adicionar descritor Promise em paralelo, mantendo APIs antigas; expandir impressão, tipo de, igualdade por identidade, contratos, clonagem (rejeitar clone de Promise), serialização e coleções com diagnósticos consistentes. Não converter Promise para inteiro/ponteiro por FFI escalar. ABI gerenciada pode transportar valor opaco com tag reconhecida, sem conceder permissão de resolver ou retomar a partir de threads estrangeiras.

O modelo inicial não cria threads do CGD e não valida GC multithread. Antes da fase paralela serão obrigatórios auditoria do build de Boehm, registro de threads, roots/stacks, finalizadores, sincronização, publicação de memória e remoção de globais inseguros. GC seguro não implica objetos livres de data races.

11. Temporizadores, sockets e libcurl

Não mudar cgd:tempo.Tempo.dormir, cgd:rede ou Processo.executar existentes. Proposta de módulos novos: cgd:tempo_assincrono, cgd:rede_assincrona e cgd:sockets_assincronos. Nomes de APIs HTTP definitivos precisam ser alinhados às classes reais, não copiar HTTP.obter fictício por cima do servidor HTTP atual.

TempoAssincrono.dormir(ms): Promessa valida inteiro não negativo e overflow de prazo monotônico antes de registrar timer. Zero agenda próximo evento. Cancelar remove timer; não usar sleep no callback. Empates usam sequência crescente.

Sockets: conexão, aceite, leitura e escrita com nonblocking/CLOEXEC, prazos, EINTR/EAGAIN, EOF, envios parciais e orçamento por evento. Um leitor e um escritor pendentes por conexão; tentativa duplicada rejeita explicitamente. Fechar rejeita pendências uma vez; buffers permanecem vivos e envio recebe snapshot para evitar mutação entre awaits. Preservar ausência de SIGPIPE. O teto síncrono atual de 128 sockets exige revisão/limite explícito antes de testar milhares de sockets; milhares de timers não provam escalabilidade de rede.

HTTP cliente: um CURLM do loop, CURL easy por requisição, integração por CURLMOPT_SOCKETFUNCTION e TIMERFUNCTION; epoll dispara curl_multi_socket_action e depois curl_multi_info_read coleta conclusões. Respeitar pedidos de remover socket e timer da libcurl. Sem laço curl_multi_poll interno aguardando o lote. Reusar TLS, limites e opções seguras, sem compartilhar sessão easy ativa com chamada síncrona, reset/opcao/fechar: definir posse exclusiva até concluir. Callbacks internos apenas acumulam bytes limitados e registram falha.

DNS é condição de aceitação, não detalhe: API multi pode ainda bloquear na resolução dependendo do build. Verificar curl_version_info em execução e resolvedor usado. Preferir build com c-ares para cumprir ausência de threads de espera por operação; não declarar HTTP/DNS não bloqueante apenas por usar multi. Se incapaz de garantir resolução não bloqueante, rejeitar a API async nesse ambiente com motivo claro, sem fallback bloqueante. Handshake TLS e protocolo também exigem validação de responsividade com timers concorrentes.

Arquivos comuns e processos permanecem síncronos nesta primeira biblioteca. Poll de pipes pode ser integrado depois; espera de filho deve usar estratégia não bloqueante/reaping definida. Não anunciar arquivo async com read bloqueante. Servidor atual continua sequencial até migração explícita posterior.

12. Ferramentas, diagnósticos e limites

CLI e LSP devem compartilhar regras via semantic/pipeline.d. Hover mostra retorno declarado T e resultado Promessa; inlay hints inferem Promessa sem editar texto. Completion após Promise usa membros próprios, nunca métodos globais como fallback. Semantic tokens destacam novas palavras; formatter preserva quatro espaços, strings e comentários. Não compilar/linkar por edição.

Catálogo diagnostics/catalog.d receberá códigos após conferir faixa livre: await fora de contexto, operando inválido, modificador proibido, retorno incompatível, override divergente, genérico inválido e função async marcada pura. Não inventar códigos numéricos disponíveis sem registrá-los. Falhas dinâmicas mantêm categoria R0001 inicialmente, com mensagem/origem de cancelamento, rejeição ou falta de progresso. --explicar, JSON e tabela gerada acompanham catálogo.

Toda travessia com switch/final switch deve reconhecer AwaitExpr/Promise: validação estrutural, módulos, semântica, fluxo, segurança, pureza, CTFE, otimização, rewrite, backend, formatter, indexação e editor. Mesmo ramos descartados passam pela semântica. Segurança estática mantém W31xx em pegue. Não considerar await função pura e não executar event loop em hover/CTFE.

Antes de implementar, fixar budgets para frames, filas, timers, reações, operações e bytes de corpo. Checar overflow e reserva antes de instalar operação; falha de registro desfaz recursos parciais. Valores de quota devem ser centralizados, documentados e testados nos limites; esta RFC não inventa limites sem medição.

13. Implementação incremental e estratégia de validação

EtapaEntrega e condição de avanço
0auditoria e contratos; sem scheduler/alteração da linguagem
1núcleo C Promise/reação/fila, transição única, adoção, observação e limpeza; testes C sem I/O
2tipos, lexer/parser/AST, semântica comum, CFG, vivacidade, wrapper/step; suspensão de Promise pronta e pendente controlada
3timers, reactor, sockets e curl multi; verificar DNS e responsividade
4cancelamento, finally suspenso, diagnóstico, encerramento, budgets, stress
5regressão síncrona, longa duração, sanitizadores, benchmarks e documentação pública

Para cada etapa, executar apenas testes pertinentes até estabilizar mudanças; matriz completa é gate da Etapa 5, não repetição a cada edição. Testar com/sem otimização e DMD/LDC2, C99 Clang/GCC, debug/release nas mudanças de backend. Não usar sleeps frágeis como prova de ordem: relógio/reactor falsos nos testes unitários do loop e operações locais controladas nos testes de integração.

Regressões obrigatórias:

  • Gramática, precedência, tipos aninhados, contextos aninhados, palavras antes usadas como identificadores e diagnóstico consistente CLI/LSP/--verificar.
  • Ordem observável de callee/argumentos/getters/indexações, curta avaliação, aliases, escritas e inicializadores não utilizados; snapshots de stdout/erro devem distinguir comportamento incorreto, não apenas recompilação de fixtures.
  • CFG/vivacidade: variável morta não ocupa slot; objeto, receptor, índice e conclusão pendente vivos sobrevivem a GC forçado entre suspensões. Validar efeitos de inicialização mesmo quando vínculo não fica no frame.
  • Await aninhado, em laços/condicionais/compreensões/métodos, herança, funções recursivas e indiretas; argumentos opcionais/rest e retorno com contratos.
  • Promise já resolvida/rejeitada, reações registradas antes/depois da conclusão, resolução dupla, adoção/ciclos, callback que lança, cadeia que encaminha falha, combinadores vazios e entradas fora de ordem.
  • Tente/pegue/finalmente em múltiplos níveis; await em catch/finally; return, break, continue e throw com limpeza; cancelamento antes/depois da suspensão, sucesso já pronto, cancelamento tratado e falha durante limpeza.
  • Reação duplicada, FD reutilizado, evento atrasado, close duplicado, cancel hook repetido, falha ao registrar; nenhuma retomada depois do estado terminal.
  • Loop sem progresso, raiz que falha com tarefas vivas, rejeição observada tarde, erro encaminhado, recursos fechados e exit status coerente.
  • Milhares de timers/Promessas pendentes e, com quota adequada, conexões locais; respostas HTTP parciais, timeout, DNS, TLS, EOF e cancelamento de transferência. Um timer deve disparar enquanto outro socket permanece sem responder.
  • Longa duração: lotes repetidos com estabilização de contagem de FDs/registros, RSS e heap após coletas. Reportar duração, volume e pico reais; RSS conservador não demonstra sozinho vazamento. ASan/UBSan, API C anterior e política do GC para leak detection continuam documentados.
  • LSP persistente: hover, assinatura, tokens, completion por receptor, formatação e diagnóstico, sem build ou loop do programa durante edição.

Benchmarks devem separar criação de Promise, custo de suspensão/retomada, timers, latência do reactor e throughput HTTP. Registrar hardware, quotas, versões carregadas, concorrência e distribuição de latência; comparação síncrona usa a mesma carga local. Nenhum benchmark foi executado nesta Etapa 0.

Paralelismo continua bloqueado por critério técnico até todos os 14 itens de estabilidade do pedido estarem cobertos: compilação, await em níveis diversos, resolução/rejeição, exceções, locais, finally, loop responsivo, timers, I/O real, recursos estáveis, cancelamento, longa duração, milhares de pendências e regressão síncrona. Registrar evidências em CONTINUIDADE.md, sem antecipar suporte.

14. Decisões pendentes antes de codificar cada camada

Não há necessidade de aprovação remota ou de publicação para trabalho local. As escolhas abaixo são tarefas de engenharia com evidência ainda necessária:

  1. Confirmar versão carregada e backend DNS da libcurl; escolher dependência c-ares se o ambiente não satisfizer o contrato. Isso precede HTTP async.
  2. Definir números dos budgets e faixa de diagnóstico; inventariar switches, símbolos chamados assincrona/aguardar/Promessa e todos os contratos de tipo.
  3. Fixar esquema do descritor Promise e metadados de callbacks/assinaturas, com testes negativos de qualquer e coleções, antes do parser da Etapa 2.
  4. Prototipar no teste C da Etapa 1 a fronteira longjmp, contexto restaurado e erros sem salto através de callbacks externos; isso precede reuso de rede.c.
  5. Especificar layout de IR/verificador e integração da normalização com materialize/LValue, medindo slots promovidos e mantendo caminho síncrono.
  6. Alinhar nomes/classes dos módulos async à biblioteca existente e definir exclusividade de sessão, antes de publicar exemplos de usuário executáveis.

As decisões semânticas das seções anteriores permitem iniciar a Etapa 1 sem improvisar await bloqueante. Esta entrega se encerra na Etapa 0 conforme a instrução inicial do pedido; implementação e testes funcionais seguem pendentes.

15. Fontes primárias consultadas

Consulta em 17/11/2026, além dos fontes locais da seção 2:

  • ECMAScript: objetos Promise: referência conceitual para estados, reações e encadeamento. A proposta CGD não promete identidade semântica, em particular para valores comuns e thenables.
  • Interface C do Boehm GC e /usr/include/gc/gc.h local: distinção entre memória rastreada/atômica, raízes e registro de threads. O projeto deve verificar o build efetivo.
  • Visão geral libcurl multi e CURLMOPT_SOCKETFUNCTION: integração de sockets/timers sob controle da aplicação; uso de multi não constitui por si só teste de ausência de bloqueio DNS.
  • epoll(7), Linux man-pages: readiness level-triggered, tratamento de descritores e integração do reactor.

Semântica de cancelamento, prioridades, IR e encerramento aqui definida é proposta própria do CGD, não garantia fornecida por essas bibliotecas.

16. Histórico da Etapa 1: núcleo C sem I/O

Estado entregue antes da Etapa 2, descrita a seguir.

O runtime possui src/assincrono.h e src/assincrono.c, API interna monothread C99. Os tipos rt_async_loop e rt_promise são opacos. Não houve mudança na enumeração tagged, na ABI C existente, no main ou no compilador: Promise ainda não é um delegua_value, e o núcleo não está exposto por FFI ou Primitivas. A integração tipada e sua tag pertencem à Etapa 2.

Implementado:

  • Criar/fechar loop e Promessas, resolver/rejeitar uma única vez, consultar estado, resultado terminal e localização. Rejeições normalizam valores como Excecao.
  • Encadear callbacks C internos de sucesso/falha com contexto gerenciado, encaminhar resultados e falhas, adotar Promessas do mesmo loop, rejeitar autoadopção/ciclos na cadeia de adoção e limitar sua caminhada.
  • FIFO de reações. Resolver apenas enfileira; checkpoint drena inclusive reações anexadas por callbacks. Adoção também termina através da fila, sem chamar consumidores inline ou recursão C por cadeia de reações.
  • Fronteira setjmp/longjmp válida durante o checkpoint, instalada antes de modificar a fila. Falhas de callbacks rejeitam o destino; localização atual, API legada de localização e profundidade são restauradas. Origem da falha é copiada na Promise, inclusive quando vem da API legada, sem renderização.
  • Raiz global de loops abertos, registro de Promessas pendentes/rejeições não observadas, filas e contextos rastreados pelo Boehm. Resultados concluídos e observados saem do registro; nós consumidos soltam referências.
  • Encaminhar erro transfere a responsabilidade ao destino. Consultar valor não observa falha. O reporter C pode enumerar rejeições em ordem de criação e reconhecer explicitamente cada uma, sem alocar nova reação; isso permite reportar/encerrar mesmo com a quota de Promessas ocupada por erros.
  • Quotas positivas fornecidas na criação: Promessas retidas no registro, reações pendentes/prontas e profundidade de adoção. Reservar reação ao registrar, não ao resolver. Falha de quota não registra destino, não observa fonte e não trava adoção parcialmente. Sem defaults globais de produção nesta etapa.
  • Fechamento explícito somente sem pendências, reações e rejeições não observadas; reentrada no checkpoint, fechamento durante callback e adoção entre loops lançam erro capturável. Handles de loop fechado são rejeitados.

O contexto C de callback deve usar memória rastreada pelo GC para referências persistentes; ponteiros para locais temporários do chamador não são continuação. Essa API não cria threads e exige uso em uma thread. Tampouco aceita um jmp_buf como estado persistente de tarefa.

Verificação executada

python3 testes/assincronismo.py compila todos os fontes do runtime para pastas isoladas em out/assincronismo, liga os testes novos e a suíte C anterior, sem substituir libdelegua_rt.o nem a instalação do usuário. Requer a tabela curl já preparada por build-runtime. O relatório resultado.json indica complete=true somente quando todas as variantes terminam.

Passaram Clang sem otimização, GCC com núcleo/teste novos em O2 e Clang O1 com NDEBUG e ASan/UBSan. A variante GCC usa O0 nos fontes anteriores: compilá-los todos com O2 e -Werror encontrou avisos de fluxo em rede/textos, associados a helpers panic sem noreturn. Eles não foram suprimidos e esses fontes não foram alterados. Isso não equivale à matriz completa GCC/O2.

A suíte verifica ordem FIFO, callbacks nunca inline, registro tardio, rejeição e recuperação, falha no callback, restauração do handler síncrono/localização, adoção pendente/pronta, resolução dupla, ciclos, limites transacionais, reentrada, fechamento inválido, rejeições sem observador e reconhecimento pelo reporter. Inclui coletas forçadas entre registro/execução, 20000 ciclos sob quota de quatro Promessas e cadeia de 12000 reações pendentes, sem recursão C de encadeamento. A suíte da API C anterior e seus 23 modos de erro R0001 passaram nas mesmas variantes. Clang-format e Ruff verificam os arquivos novos. A suíte nova também integra vendor/delegua-runtime/tests/run.sh; a inclusão foi conferida com shfmt e sh -n, sem substituir o runtime normal para executá-la.

ASan usa detect_leaks=0 e detect_stack_use_after_return=0, como o runner existente do projeto, pois o GC não rastreia a fake stack do ASan como stack nativa. A primeira tentativa sem esta segunda opção falhou no teste anterior de mapa após GC; a execução com a configuração do projeto passou. Não afirmar prova universal de ausência de vazamento nem teste de longa duração.

Limites e próxima etapa

Ainda faltam descritores Promessa, funções de linguagem, lexer/parser/AST, vivacidade/IR e frames de suspensão; depois vêm timers, reactor, curl multi, cancelamento de ativações, finally suspenso e encerramento integrado no main. Não há combinadores, scheduler de tarefas prontas de I/O ou cancelamento neste núcleo. O reporter apenas enumera/reconhece falhas: política de impressão e exit status do programa pertence à integração futura. Ciclos de dependência através de callbacks arbitrários não são detectados como ciclos de adoção; falta de progresso será responsabilidade do loop integrado.

Próxima ação: Etapa 2, começando por tipos/contratos de retorno, diagnóstico de contexto, inventário de travessias e IR verificável. Não habilitar async/await como chamada bloqueante. Paralelismo continua condicionado à estabilização de todo o modelo assíncrono.

17. Primeira entrega da Etapa 2: linguagem e suspensão

Há execução real de assincrona/aguardar no compilador, ainda com limites experimentais. O exemplo executável 41_assincronismo.delegua imprime raiz, início, continua, 11: a função começa imediatamente, devolve sua Promise e retoma depois da raiz. Não há espera bloqueante dentro de aguardar.

Frontend e ferramentas

  • Tokens Async/Await, marcador isAsync em FnDecl, AwaitExpr na AST e tipos sintático/semântico próprios de Promessa. Arrays/tuplas podem conter o tipo, e fechamentos aninhados >> são separados apenas na gramática de tipos. Promessa é reservado como nome de tipo; assincrona/aguardar viram palavras-chave.
  • A anotação de retorno continua descrevendo T; a chamada de função ou método async produz Promessa. Promessas aninhadas exigem awaits distintos. Não há unwrap automático no retorno de função. Uso de qualquer tem guardas nativas. Promessa é invariante, com refinamentos dinâmicos sujeitos a todos os contratos.
  • Metadados de chamadas conhecidas por referências imutáveis preservam o efeito; parâmetros funcao e demais chamadas desconhecidas continuam dinâmicos, com guardas em execução. Capturas de variáveis externas continuam recebendo W4001/E4001; receptor e argumentos são passagem explícita, sem clonagem implícita.
  • E3301: contexto inválido; E3302: operando sem Promise; E3303: async puro/CTFE; E3304: efeito incompatível em contrato/override; E3305: lowering ainda ausente; E3306: consumo de resultado vazio como valor; E3307: orçamento da IR excedido. Tipos incompatíveis mantêm E3002 e falhas dinâmicas continuam R0001.
  • CLI/LSP compartilham análise; hover mostra assincrona, T e Promessa, dicas virtuais mostram tipos inferidos, tokens reconhecem as palavras/tipo e completion de uma Promise oferece entao/capturar, sem fallback global após ponto. Não há build, link, execução de tarefas ou CTFE de async durante a edição.
  • O formatador lexical mantém quatro espaços e modificadores juntos; atualmente pode escrever Promessa < inteiro >, que é uma anotação válida equivalente.

IR e emissão C99

middle/async_ir.d normaliza avaliações em instruções atômicas e cria CFG com Evaluate, Jump, Branch, Await, Resume, Return e Throw. Vínculos usam identidade resolvida e slots únicos; sombras lexicais não se confundem. Receptor, índices, callee, argumentos e valores anteriores de atribuição composta são materializados na ordem original, antes de qualquer suspensão subsequente.

Vivacidade por ponto fixo seleciona os slots que atravessam Await. Definições de atribuições e incrementos entram no cálculo; um vínculo escrito novamente antes de ser lido após suspensão não precisa do valor anterior no frame. Inicializadores e escritas mantêm seus efeitos mesmo quando seu resultado não persiste. O verificador inicial verifica intervalos, expressões sem await oculto e pareamento de suspensão/retomada; verificação completa de dominância/tipos continua evolução.

O backend emite wrapper da ABI argc/argv e step com switch(pc). O frame rastreado pelo GC contém pc e somente slots persistentes. Variáveis e temporários restantes são locais C do step. Argumentos são consumidos no primeiro segmento, sem guardar argv do chamador. Defaults são avaliados antes dos contratos, como nas funções síncronas. Antes de suspender, salvar slots vivos; na retomada, recuperar valores e limpar referências do frame que já não precisam permanecer enraizadas.

Limites atuais por função: 100000 instruções e slots, 2000000 fatos simultâneos de vivacidade e 50000000 visitas de instrução/fato. Exceder gera E3307 na geração C, sem stack trace de exceção D. --verificar e o editor não executam esse lowering.

Runtime, tipos e ciclo de vida

DELEGUA_T_PROMESSA foi acrescentada no fim da enumeração, sem renumerar as tags anteriores. Funções/métodos mantêm a ABI C de chamada; wrappers async devolvem um valor tagged. O descritor estrutural preserva o resultado T, inclusive coleções e classes. Registrar um vínculo mais restrito não pode apagar contratos de aliases anteriores; resolução incompatível rejeita a Promise e resultados de coleção mantêm suas restrições nas escritas posteriores.

Tarefas têm fronteira setjmp válida apenas enquanto o step está na stack C. Uma suspensão nunca mantém jmp_buf de uma ativação retornada. Reações retomam através da FIFO da Etapa 1, incluindo Promessas já prontas. Continuar/concluir mais de uma vez é erro; o frame é desvinculado ao terminar. No erro, restaurar localização/profundidade/handler do chamador. Propagação por await conserva separadamente a localização do await e a origem da rejeição; o reporter imprime uma nota de origem escapada, sem reimprimir a exceção nem reter a cadeia de frames.

O loop do programa é criado sob demanda e drenado após delegua_main. Sem tarefas, o caminho síncrono apenas testa a ausência do loop. Rejeições não observadas são reportadas em ordem de criação e causam status 1. Falta de progresso também causa falha, sem busy-wait. Promessas C de outros loops não são aceitas por aguardar/encadeamento da linguagem: a FFI gerenciada não autoriza misturar loops ou retomar de outra thread.

Limites do loop padrão: 65536 Promessas retidas (pendentes/rejeições não observadas), 65536 reações e profundidade de adoção 4096. Uma Promise aceita até 256 contratos distintos. Limites são contabilizados antes de registrar operação; a criação da própria Promise pode falhar antes de existir um resultado rejeitável. Não há preempção de código CPU ou de chamadas síncronas de I/O.

entao(callback) e capturar(callback) devolvem nova Promise. São métodos nativos por receptor, com callback sem captura lexical ou método ligado a receptor explícito. Callback executa em microtask; retorno de Promise é adotado; retorno de valor resolve; exceção rejeita. Metadados atuais do encadeamento retornam Promessa, com contratos dinâmicos ao vincular/aguardar.

Limites de implementação e sequência

A IR agora representa arestas excepcionais, retorno pendente e limpeza em saídas normais, erro, retorno, break e continue. pegue e finalmente podem suspender sem guardar handlers C de ativações encerradas. Slots C locais são volatile para manter valores definidos após longjmp. A checagem final do retorno ocorre após as limpezas, preservando o contrato síncrono. Para cada, escolha, compreensões, laços coletores e spread também têm lowering; E3305 permanece para classes locais dentro de funções assíncronas.

Cancelamento, combinadores e encerramento

Promessas produtoras oferecem cancelar(): logico: solicita uma vez e retorna falso quando não há proprietário cancelável ou já terminou. Tarefas injetam uma Excecao de cancelamento nos pontos seguros; não há preempção de código CPU. Limpezas finalmente são protegidas durante suspensão. Cancelar uma tarefa remove seu waiter, mas não cancela automaticamente a Promise aguardada.

Promessa.resolvida, rejeitada, todas, corrida, qualquer e todasResolvidas estão implementadas. Combinadores recebem vetor de Promessas; resultados de todas preservam a ordem de entrada. todasResolvidas produz mapas com estado resolvida/rejeitada e valor/erro. qualquer agrega falhas em Excecao.erros. Cancelamento do combinador desinscreve consumidores sem cancelar produtores. As reações tardias de entradas perdedoras continuam observadas.

Ao falhar a raiz, o runtime solicita cancelamento dos produtores, preserva as dependências das limpezas já suspensas e drena o trabalho de limpeza. Cancelamentos de encerramento não substituem o erro original; falhas secundárias são reportadas. Novas operações durante encerramento exigem contexto de limpeza. Após o cancelamento inicial, a drenagem dispõe de cinco segundos de relógio monotônico. O reactor limita a espera por I/O ao tempo restante e o loop verifica o prazo entre reações. O vencimento gera um diagnóstico secundário e preserva o erro da raiz. Uma chamada síncrona já em execução precisa devolver o controle para que o loop observe o prazo.

I/O nativo: cgd:assincrono

O módulo separado cgd:assincrono oferece Tempo.dormir, HTTP e TCP. As bibliotecas anteriores cgd:tempo, cgd:rede, cgd:sockets, servidor e processos permanecem síncronas. Usar assincrona não transforma automaticamente essas chamadas em I/O não bloqueante.

O reactor Linux usa epoll level triggered e heap de prazos monotônicos, sem thread por operação. Timers iguais seguem sequência de registro; microtasks são drenadas antes da próxima espera. Até 65536 watches/timers; cada lote tem até 64 fontes. O registro mantém raízes fortes dos contextos gerenciados.

HTTP usa curl multi e curl_multi_waitfds (libcurl >= 8.8), descoberto dinamicamente para preservar o mínimo da API síncrona anterior. HTTP.obter/requisitar/enviar produzem RespostaHTTP com status, texto, url, tipoConteudo, sucesso e json. URLs numéricas funcionam sem resolver; hostnames exigem libcurl com c-ares. Não há fallback DNS bloqueante ou thread por consulta. Proxy de ambiente e redirecionamentos estão desativados; TLS verifica certificado e hostname. O último argumento opcional de HTTP.obter, HTTP.enviar e HTTP.requisitar limita o corpo da resposta em bytes. O padrão é 16 MiB. Uma resposta exatamente no limite é aceita; o primeiro byte excedente rejeita a promessa. São até 4096 requisições; corpo até 64 MiB por operação, memória de resposta 256 MiB global e cabeçalhos de envio 64 KiB por operação/16 MiB globais. Callbacks curl não lançam longjmp através da biblioteca: falhas são convertidas fora deles.

TCP.conectar aceita IPv4 numérico e produz ConexaoTCP; enviar/receber e OuvinteTCP.aceitar usam eventos de prontidão e timeout. Uma operação pendente por socket, inclusive entre aliases; acesso síncrono concorrente é recusado. Cancelar/expirar/falhar uma conexão fecha o recurso, inclusive em escrita parcial. O cancelamento das promessas públicas de HTTP, conexão e aceite alcança a operação nativa criada pela chamada. Após observar a rejeição do aceite, o ouvinte pode aceitar outra conexão. Cancelar/expirar aceite preserva o ouvinte; fechar o recurso rejeita sua operação. Leitura devolve texto binário e texto vazio no EOF; escrita resolve a contagem após enviar o corpo inteiro. Limites: 128 sockets, leitura até 1 MiB, buffers de leitura 16 MiB globais, escrita até 16 MiB. Não há DNS, IPv6 ou TLS nesse TCP.

Exemplo de uso da API nova (ainda aguardando a rodada de validação):

assincrona funcao principal(): vazio {
    aguardar importar("cgd:assincrono").Tempo.dormir(10)
    const resposta: qualquer = aguardar importar("cgd:assincrono").HTTP.obter("http://127.0.0.1:8080/")
    escreva(resposta.status(), resposta.texto())
}
principal()

As novas integrações e os handlers ainda aguardam validação funcional. Há regressões preparadas; não foram executadas após a suspensão de testes. Uma rejeição propagada diretamente por esperas sucessivas conserva a origem e até 32 locais de aguardar. O relatório indica quando atingiu o limite. A adoção e o encaminhamento sem tratador preservam os locais já registrados. A recuperação seguida de outra suspensão pode interromper a cadeia de esperas. A API de grupos e a execução de tarefas paralelas seguem para a etapa de rotinas.

Testes específicos: python3 testes/async_linguagem.py, a mesma suíte com CC=gcc e --sanitizadores, unitários DMD/LDC e python3 testes/assincronismo.py. A suíte de linguagem verifica saída/efeitos, defaults, aliases, sombras, laços, herança, calls indiretas, encadeamento/recuperação, rejeição com origem e falta de progresso, com/sem otimização. Os resultados finais e regressões síncronas realmente executados estão em CONTINUIDADE.md.

Rotinas paralelas (rotina, Tarefa<T>, Canal, GrupoTarefas)

Data: 20/11/2026 (CGD 0.9.0). Execução paralela de funções Delégua auditadas sobre pool de workers nativos com isolamento por thread (TLS) e registro de threads no Boehm GC.

Sintaxe e tipos implementados

rotina chamada(argumentos) é uma expressão prefixa que produz Tarefa<T>. Como comando de expressão, inicia a mesma tarefa; o loop principal aguarda a drenagem antes do encerramento do processo. Callee e argumentos são avaliados uma única vez, da esquerda para a direita, na thread chamadora, antes da submissão. aguardar tarefa integra a conclusão ao reactor epoll sem bloquear a thread principal. Tarefa<T> distingue trabalho paralelo de Promessa<T>, mantendo entao, capturar, cancelar, concluida e cancelada (e compatibilidade com combinadores Promessa.todas/corrida/qualquer/todasResolvidas).

A auditoria transitiva de efeitos (frontend/semantic/routine_validation.d, códigos E3401–E3404) exige função de topo ou método estático conhecido sem captura, transitivamente livre de I/O global, FFI, campos estáticos mutáveis, chamadas indiretas sem contrato e funções assíncronas. Argumentos e retorno exigem tipos transferíveis (nulo, logico, inteiro, real, texto copiado ou qualquer validado em execução pelo runtime). Exceções lançadas no worker são capturadas na fronteira TLS da thread de trabalho e propagadas como rejeição Excecao tratável com tente/pegue na thread principal.

Transferência implementada como base interna

vendor/delegua-runtime/src/rotinas_transferencia.{c,h} implementa pacotes de propriedade exclusiva, sem ponteiros para valores gerenciados. Aceita nulo, lógico, inteiro, real e texto copiado com tamanho explícito, inclusive bytes NUL. Rejeita funções, Promessas, sockets, classes, objetos, coleções e ponteiros, sem conversões ou inspeção de campos. Limites: 4096 valores e 16 MiB por pacote. Isso ainda não constitui suporte a rotinas na linguagem.

A conversão de e para valores Delégua ocorre na thread principal. Workers podem construir pacotes de resultado a partir de views nativas com cópia dos textos. O pacote usa calloc/free, e seus registros usam offsets para textos dentro da própria alocação. Views são imutáveis e válidas apenas durante a vida do pacote. Não há acesso concorrente autorizado ao destrutor: o proprietário só libera após todos os leitores terminarem. O pool transfere propriedade sob mutex; publicar um ponteiro sem sincronização não é transferência. Não há finalizador do GC: o proprietário libera o pacote explicitamente. Em caso de recusa, a posse continua com o chamador.

Pool interno no Linux

O módulo C interno rotinas_pool.{c,h} cria de 1 a 64 threads por pool. A capacidade configurável (1 a 4096 tarefas) conta as tarefas em fila FIFO, em execução e concluídas que a thread principal ainda não recolheu. Na recusa, o pacote continua com o chamador. Na aceitação, a fila assume sua propriedade e devolve um identificador que não é reutilizado durante a vida do pool.

Cada conclusão acrescenta uma unidade a um eventfd não bloqueante. A thread principal pode observar o descritor com epoll e consumir uma conclusão por rt_pool_take, assumindo o pacote. O cancelamento remove uma tarefa em fila imediatamente. Um callback em execução consulta rt_pool_cancelled em pontos cooperativos. Ao destruir o pool, a thread principal interrompe o despacho, sinaliza cancelamento, aguarda as threads e libera os pacotes restantes.

O pool aceita callbacks C internos que operam sobre pacotes exclusivos.

Conclusão no reactor

A entrada C interna rt_routine_start copia os argumentos e usa um pool de quatro workers com limite de 256 tarefas. O reactor acompanha um único eventfd enquanto houver trabalho. A cada notificação ele recolhe até 32 conclusões, converte o resultado escalar e resolve ou rejeita a Promessa na thread principal. Um cancelamento aceito antes dessa entrega prevalece mesmo se o worker já terminou. Fechar o reactor ocioso também encerra o pool.

As regressões preparadas cobrem conclusão em múltiplos lotes, pressão de GC, texto com NUL, retorno inválido, argumento mutável e cancelamento em fila e em execução. A validação funcional continua pendente.

Isolamento por thread, canais e grupos

  • Estado de exceções (active, reporting, delegua_call_depth) e localização (delegua_local_atual e campos legados) usam armazenamento TLS por thread.
  • Classes núcleo (Objeto, Excecao) são inicializadas com pthread_once e pré-aquecidas em main antes de qualquer worker iniciar.
  • Workers registram sua pilha no Boehm GC (GC_allow_register_threads, GC_register_my_thread/GC_unregister_my_thread) por hooks de ciclo de vida do pool, mantendo rotinas_pool.c desacoplado do GC para validação TSan.
  • cgd:assincrono disponibiliza Canal(capacidade) (fila limitada de valores transferíveis com backpressure assíncrono, tentarEnviar/tentarReceber e fechar) e GrupoTarefas (espera agregada e cancelamento em falha).

M:N e corrotinas stackful permanecem fora do escopo atual.