Pular para o conteúdo principal
Linguagem didática · C11 · documentação viva

BASICGOL

A legibilidade do BASIC e do Portugol, entregue como uma camada de macros C. Cada símbolo desta documentação é rastreado até o fonte, os testes e as condições de compilador que realmente existem no projeto.

Começar agora · Explorar a referência · Ver os testes

Referência viva

Macros, palavras-chave, funções da biblioteca, expansões, contratos, exemplos e usos localizados nos testes.

Testes rastreáveis

Casos dourados, entradas, saídas esperadas, negativos, avisos e modos de falha fatal — com links para as linhas.

Portabilidade sem atalhos

O que é compartilhado, o que depende de GCC/Clang/MSVC/MinGW e o que foi executado, compilado ou apenas avaliado.

Por dentro do projeto

Transpilador, harness, runners Bash e scripts Python. O próprio gerador também é inventariado.

Sessenta segundos até o primeiro binário​

BASICGOL é um .c comum: o cabeçalho traz as palavras-chave, a biblioteca traz os helpers e o compilador C faz o resto.

#include <basicgol.h>

INICIO
TEXTO_FIXO(nome, 64);

ESCREVA("Como voce se chama? ");
SE LEIA_TEXTO(nome, TAMANHO_DE(nome)) ENTAO
ESCREVAL("Ola, ");
ESCREVAL(nome);
SENAO
ESCREVAL("nao consegui ler o nome");
FIM_SE
FIM
make
cc -std=c11 -Wall -Wextra -Wformat=2 -I include programa.c \
build/libbasicgol.a -lm -o programa
./programa

Se o programa usar PARA i DE 1 ATE 10 FACA, acrescente uma passada pelo transpilador:

build/basicgolc programa.c -o programa.gerado.c
cc -std=c11 -I include programa.gerado.c build/libbasicgol.a -lm -o programa

O que você encontra aqui​

CamadaConteúdoAtualização
Guiasprimeiros passos, arquitetura, leitura de evidências, portabilidade, publicaçãomanual
Referênciauma página por macro/função, com expansão, contrato, guards e FAQsgerada do código
Testescasos, arquivos dourados, modos fatais e coberturagerada dos testes
Exemplosprogramas completos e suas saídasgerada de docs/exemplos
Projetoespecificação, decisões, critérios, relatórios e defeitosimportada de docs/
Internostranspilador, harness, runners e scripts Pythongerada de tools/ e tests/

Perguntas frequentes em toda página​

Cada página gerada termina com uma seção Perguntas frequentes específica do que ela mostra: expansão, uso real em testes, dependência de compilador, armadilhas e como executar. As respostas usam o código do repositório, não texto genérico.

# exemplo: conferir a FAQ e a evidência de uma macro
python3 -c "import json; d=json.load(open('website/static/api/inventario.json')); print(d['counts'])"

O que torna esta documentação diferente​

  • Gerada por Python a cada build. Novos arquivos, funções, macros, casos e modos aparecem sem editar uma lista manual de páginas.
  • Evidência, não suposição. Uma referência de teste é distinguida de uma chamada indireta; nenhuma delas é apresentada como cobertura de ramos.
  • Ramos de compilador preservados. A análise não pré-processa o C para um único alvo: guards e diretivas continuam visíveis.
  • Histórico preservado. A especificação, as decisões, os relatórios e a matriz original continuam disponíveis em Projeto.

Dois caminhos, uma linguagem​

CaminhoFerramentasCobre
M0compilador C11 + libbasicgol.atodo o subconjunto redutível a macros
M1C11 + basicgolc + libbasicgol.ao núcleo + açúcar como PARA i DE … FACA
Estado e versões

As versões e os números impressos pelos testes são os do código executado. As páginas geradas mostram contagens estáticas do repositório e não substituem os logs de CI. Consulte a matriz de compatibilidade antes de chamar um alvo de “suportado”.

Perguntas frequentes​

BASICGOL é uma linguagem nova ou um conjunto de macros?​

As duas coisas em camadas: a linguagem é definida pelas macros e pelo transpilador; o que executa é C11 puro. Não há runtime próprio nem máquina virtual.

#include <basicgol.h>

INICIO
ESCREVAL("sem VM, sem interpretador");
FIM

Qual compilador devo usar?​

O mais disponível no seu sistema, desde que aceite C11. GCC e o frontend Clang foram executados; MinGW-w64 foi executado em CI; MSVC é apenas avaliado. Em Linux, o comando documentado é o do GCC/Clang com -lm.

cc --version
cc -std=c11 -Wall -Wextra -I include programa.c build/libbasicgol.a -lm -o programa

Preciso do transpilador para tudo?​

Não. Só quando o fonte usa construções que exigem reordenar tokens, como PARA i DE 1 ATE 3 FACA. Sem elas, o caminho M0 compila direto.

As FAQs são iguais em todas as páginas?​

Não. Cada página monta as perguntas a partir da sua própria definição, dos usos em testes, dos guards e do contrato editorial. Uma macro sem teste direto recebe uma resposta diferente de uma função com 18 referências.

Posso usar BASICGOL em produção?​

O projeto declara com precisão o que foi executado e o que não foi. Para produção, verifique a matriz de compatibilidade, rode a suíte no seu compilador/alvo e trate o que está marcado como avaliado ou não testado como risco, não como garantia.

make test
make test-portabilidade
make test-sanitize

Onde reporto um erro na documentação?​

Abra um pull request no repositório. Guias ficam em website/manuais/, contratos editoriais em tools/documentacao/contratos.json e páginas de símbolo são regeneradas do fonte — não edite website/docs/.

python3 tools/gerar_documentacao.py --strict
cd website && npm run build