Pular para o conteúdo principal

BASICGOL — Referência de Palavras-chave e Operadores

Referência de consulta. Para o porquê de cada decisão, ver 01 — Especificação; para a expansão exata de cada construtor, ver 03 — Mapeamento para C.

Como ler esta referência​

ColunaSignificado
Formacomo se escreve no programa .c
PerfilN = funciona no caminho M0 (macros); X = só com basicgolc (M1); C = C nativo
Tipoobjeto = macro sem argumentos; função(n) = macro com argumentos; função C = helper compilado da biblioteca padrão

Desde a Fase 5, funções de biblioteca são implementadas em módulos C e exigem build/libbasicgol.a (ou os fontes de src/biblioteca/) na ligação. Build, dependências, contratos de retorno e ownership estão em 09 — Biblioteca padrão.

Convenção tipográfica: MAIÚSCULAS = palavra-chave; minusculas = identificador do usuário; expressao = qualquer expressão C; cmd* = zero ou mais comandos.


1. Estrutura do programa​

FormaPerfilTipoSignificado
INICIONobjetoabre a função de entrada: int main(void) {
FIMNobjetofecha a função de entrada: }
FUNCAO tipo nome(params) { … }Nobjeto vaziodeclara função com valor de retorno (FUNCAO expande para nada; o tipo vem em seguida)
PROCEDIMENTO nome(params) { … }Nobjetodeclara procedimento (void)
RETORNE expressao;Nobjetodevolve valor
ESTATICONobjetostatic: função/variável privada do arquivo
EXTERNONobjetoextern: declara símbolo de outra unidade

2. Tipos​

Palavra-chaveTipo CObservação
LOGICOboolvalores: VERDADEIRO, FALSO
CARACTEREchar1 byte; sinal depende da plataforma
INTEIRO_CURTOshort≥ 16 bits
INTEIROint≥ 16 bits
INTEIRO_LONGOlong≥ 32 bits
INTEIRO8 INTEIRO16 INTEIRO32 INTEIRO64int8_t … int64_tlargura exata
NATURALunsigned≥ 16 bits
NATURAL_CURTOunsigned short≥ 16 bits
NATURAL_LONGOunsigned long≥ 32 bits
NATURAL8 NATURAL16 NATURAL32 NATURAL64uint8_t … uint64_tlargura exata, sem sinal
REAL_CURTOfloatprecisão simples
REALdoubleprecisão dupla
REAL_LONGOlong double≥ double
TEXTOconst char *referência imutável a texto UTF-8
VAZIOvoidausência de valor

Qualificadores: CONSTANTE → static const; ESTATICO → static; EXTERNO → extern.

Inteiros e reais têm a largura da plataforma, exceto os de largura exata. As constantes abaixo dizem o valor real do ambiente:

FormaValorUso
TAMANHO_DE(t)((size_t) sizeof(t))bytes do tipo
BITS_DE(t)((size_t) (sizeof(t) * CHAR_BIT))bits do tipo
MAXIMO_INTEIRO / MINIMO_INTEIROINT_MAX / INT_MINfaixa de INTEIRO
MAXIMO_NATURALUINT_MAXfaixa de NATURAL
MAXIMO_REAL / EPSILON_REALDBL_MAX / DBL_EPSILONfaixa e precisão de REAL

A referência completa de representação, faixa e conversão está em 06 — Tipos e Expressões.

3. Declarações​

FormaPerfilTipoSignificado
INTEIRO x = 0;N/C—variável
CONSTANTE REAL k_pi = 3.14159;Nobjetoconstante
VETOR(INTEIRO, v, 10);Nfunção(3)vetor de 10 posições, índices 0…9
TAMANHO_VETOR(v)Nfunção(1)número de elementos, devolve NATURAL; só para vetor real, não ponteiro (C-18, W-06)
TEXTO_FIXO(nome, 40);Nfunção(2)buffer de texto mutável (char nome[40])
REGISTRO(Nome) … FIM_REGISTRO(Nome);Nfunção(1) cadadefine registro (typedef struct)
ENUMERACAO(Nome) … FIM_ENUMERACAO(Nome);Nfunção(1) cadadefine enumeração (typedef enum)

4. Controle de fluxo​

FormaPerfilSignificado
SE cond ENTAO … FIM_SENcondicional
SENAO_SE cond ENTAO …Nnovo ramo condicional na mesma cadeia
SENAO …Nramo final
ENQUANTO cond FACA … FIM_ENQUANTONlaço com teste antes
REPITA … ATE_QUE(cond);Nlaço com teste depois (ao menos uma execução)
PARA (i, inicio, fim) { … }Nlaço contado inclusivo, passo +1
PARA_PASSO (i, inicio, fim, passo) { … }Nlaço contado inclusivo, passo genérico; passo zero é erro de execução
PARA i DE inicio ATE fim [PASSO p] FACA … FIM_PARAXmesma semântica, sintaxe Portugol/BASIC
ESCOLHA (expr) … CASO v: … CONTRARIO: … FIM_ESCOLHANseleção múltipla
PARE;Nsai do laço/ESCOLHA mais interno (break)
PROSSIGA;Npróxima iteração (continue)
ATE cond;Xforma alternativa de ATE_QUE(cond)

Regras de ouro do controle de fluxo​

  1. SE sempre tem ENTAO; ENQUANTO sempre tem FACA; REPITA sempre termina em ATE_QUE(...).
  2. Cada bloco aberto tem um FIM_* no fim (um por cadeia SE/SENAO_SE/SENAO, não um por ramo).
  3. SENAO SE (duas palavras) é proibido; use SENAO_SE.
  4. SE x { … } é proibido; use SE x ENTAO … FIM_SE (ou if de C).
  5. Blocos criam escopo; declare antes do SE o que precisar sobreviver a ele.

5. Operadores​

5.1 Por palavra (a forma canônica didática)​

FormaEquivalente CAridadeObservação
a E ba && bbináriocurto-circuito garantido
a OU ba || bbináriocurto-circuito garantido
NAO a!aunárioprecedência alta: NAO a E b = (!a) && b
a MOD ba % bbináriosó inteiros; sinal do dividendo
VERDADEIRO / FALSOtrue / falseliteraltipo LOGICO
IGUAL(a, b)((a) == (b))função(2)evita a confusão = × ==. É prefixado: x IGUAL 3 não compila; para infixo use == (§11.6 de 01)
DIFERENTE(a, b)((a) != (b))função(2)idem
TEXTOS_IGUAIS(a, b)strcmp(a,b) == 0função(2)única forma correta de comparar conteúdo de texto
TEXTOS_DIFERENTES(a, b)strcmp(a,b) != 0função(2)idem
OU_EXCLUSIVO(a, b)((bool) (((a) != 0) != ((b) != 0)))função(2)XOR lógico; normaliza os operandos
LOGICO_DE(x)((bool) ((x) != 0))função(1)valor de verdade normalizado (0/1); aceita literal real (LOGICO_DE(0.5))
DIVIDE(a, b)_Generic → bg_divide_*função(2)divisão verificada: recusa divisor 0 e quociente assinado não representável
RESTO(a, b)_Generic → bg_resto_*função(2)resto verificado, só inteiros

5.2 Símbolos C (sempre aceitos)​

+ - * / % = == != < <= > >= && || ! ++ -- += -= *= /= [ ] . ( ) & * (ponteiros) ? : sizeof.

5.3 Precedência (idêntica a C)​

( ) [ ] . ->
++ -- (pós) NAO (!) ~ + - (unários) (cast) * (indireção) & (endereço) sizeof
* / MOD
+ -
< <= > >=
== !=
E (&&)
OU (||)
? :
= += -= *= /= %=
,

R-6: parentize ao misturar E/OU/NAO com comparações ou aritmética.

Nota: MOD= (com MOD por palavra) não existe — geraria %= como dois tokens. Use x = x MOD 2 ou x %= 2 (C nativo). Ver C-01 em 04.

DIVIDE/RESTO mantêm o tipo promovido dos operandos e trocam o comportamento indefinido por um erro com arquivo e linha. / e MOD continuam sendo o C cru; a diferença entre eles está em 06 §5.4–5.5.

6. Entrada e saída​

FormaPerfilSignificado
ESCREVA(x);Nescreve um valor escalar, sem quebra de linha
ESCREVAL(x);Nescreve um valor escalar e quebra a linha
ESCREVA_LINHA();Nquebra a linha
ESCREVA_TEXTO(s);Nescreve texto como %s (sem consultar tipo)
ESCREVA_FMT(fmt, …);Nprintf direto (formatação fina, múltiplos valores)
ESCREVA_ERRO(s);Nescreve texto em stderr
LEIA(x);Nlê um valor escalar para x; o formato sai de _Generic pelo tipo do destino (NATURAL8→%hhu, NATURAL_CURTO→%hu, REAL_LONGO→%Lf, CARACTERE→ %c); LOGICO, TEXTO e TEXTO_FIXO são recusados pelo compilador (erro de _Generic, não aviso); texto se lê com LEIA_TEXTO
LEIA_OK(x);Nlê e devolve LOGICO (sucesso/falha)
LEIA_TEXTO(buf, tam);Nlê uma linha para TEXTO_FIXO; consome o \n pendente de um LEIA anterior, se houver
LEIA_INTEIRO(x);Nlê uma linha e converte para INTEIRO; devolve LOGICO; não deixa lixo no stdin
LEIA_REAL(x);Nidem para REAL

Formatos usados por ESCREVA/ESCREVAL (escolhidos em tempo de compilação):

Tipo do argumentoFormato
LOGICO, INTEIRO, INTEIRO_CURTO%d
INTEIRO_LONGO, INTEIRO64%ld / %lld
NATURAL, NATURAL32, NATURAL64, size_t%u / %lu
CARACTERE%c
REAL_CURTO, REAL%g
REAL_LONGO%Lg
TEXTO, char *%s
enumeração%d
qualquer outro (ponteiro)%p

Limitações declaradas: sem controle de casas decimais (ESCREVA_FMT resolve); um valor por chamada; sem detecção de tipo em tempo de execução.

7. Matemática, texto e utilidades​

FormaPerfilTipoSignificado
ABS(x)Nfunção C selecionada por _Genericvalor absoluto; mínimo de inteiro assinado é erro fatal porque o resultado não cabe
MINIMO(a, b) / MAXIMO(a, b)Nfunção C selecionada por _Genericmínimo/máximo; cada argumento é avaliado uma vez
POTENCIA(base, exp)Nmacro → libmpotência (pow, -lm)
RAIZ(x)Nmacro → libmraiz quadrada (sqrt, -lm)
ARREDONDA(x)Nfunção C (llround)inteiro mais próximo, empate longe de zero
PISO(x) / TETO(x)Nmacro → libmpiso/teto (floor/ceil)
SORTEIA(n)Nfunção Cinteiro pseudoaleatório em 0 … n-1; para limites inválidos devolve 0
INICIA_SORTEIO(semente)Nfunção Cinicializa explicitamente o PRNG próprio (xorshift64*, derivado por splitmix64); mesma semente → mesma sequência em qualquer plataforma
TAMANHO_TEXTO(s)Nfunção Ccomprimento em bytes (strlen), devolve NATURAL; cada acento UTF-8 ocupa 2 bytes (D-20)
COPIA_TEXTO(destino, tam, origem)Nfunção C → LOGICOcopia com verificação de espaço
JUNTA_TEXTO(destino, tam, a, b)Nfunção C → LOGICOconcatena dois textos em destino
TEXTO_PARA_INTEIRO(s, &var) / TEXTO_PARA_REAL(s, &var)Nfunção C → LOGICOconverte texto em número; rejeita texto com sobra ("4x2", "12abc") e estouro de faixa
TEXTO_PARA_NATURAL(s, &var)Nfunção C → LOGICOidem para NATURAL; recusa -
REAL_PARA_INTEIRO(x, &var)Nfunção C → LOGICOconverte real em inteiro com checagem de faixa e NaN
ACRESCENTA_TEXTO(destino, tam, origem)Nfunção C → LOGICOacrescenta ao fim do conteúdo atual
TRECHO_TEXTO(destino, tam, origem, inicio, n)Nfunção C → LOGICOcopia até n bytes a partir de inicio
COMPARA_TEXTO(a, b)Nfunção C → INTEIRO−1/0/+1; NULL conta como ""
TEXTO_VAZIO(s)Nfunção C → LOGICOverdadeiro para "" e NULL
FORMATA_TEXTO(destino, tam, formato, …)Nfunção C → LOGICOvsnprintf verificável; false se truncou
E_DIGITO(c) / E_LETRA(c)Nfunção C → LOGICOclassificação ASCII, independente de locale
CARACTERE_MAIUSCULO(c) / CARACTERE_MINUSCULO(c)Nfunção C → CARACTEREconversão ASCII de 1 byte

Não existe concatenação com +: "a" + "b" é aritmética de ponteiros em C e produz lixo. Use JUNTA_TEXTO ou ACRESCENTA_TEXTO.

Todo truncamento é reportado por valor de retorno, e em caso de falha o destino fica vazio (dest[0] == '\0') — nunca conteúdo parcial. Origem NULL é texto vazio, e origem e destino podem ser o mesmo buffer (memmove). Contrato completo em 06 §8.

8. Erros​

FormaPerfilSignificado
ERRO("mensagem");Nimprime arquivo:linha: erro: mensagem em stderr e encerra com código 1
AFIRME(cond, "mensagem");Ncomo ERRO, mas só dispara quando cond é falsa
LEIA_OK(x) / funções que devolvem LOGICONtratamento por valor de retorno (forma preferida)

Não há TENTE/CAPTURE/FINALMENTE em v1.0 (ver D-06).

9. Configuração (macros BG_*)​

MacroEfeito
BG_SEM_APELIDOSdefinida antes do #include: desliga os nomes curtos; só existem BG_SE, BG_ENTAO, …
BG_VERSAO_MAIOR / BG_VERSAO_MENOR / BG_VERSAO_CORRECAOversão da implementação (inteiros)
BG_VERSAO_MINIMA(mai, men)emite #error se a implementação for mais antiga
BG_ESTRITOliga verificações extras em tempo de compilação (reservado; ver D-09)
BG_USAR_EXTENSOESliga a seção opcional de extensões (SOMA_SEGURA, …); exige GCC/Clang (D-22)
BG_TEM_EXTENSOESdefinida pelo cabeçalho quando as extensões estão ativas (1)

10. Nomes reservados​

Não podem ser usados como identificadores: todas as palavras-chave das tabelas acima, os nomes bg_*, BG_*, k_* (convenção), identificadores iniciados por _, e os reservados para o futuro: PARA_CADA, TENTE, CAPTURE, FINALMENTE, CLASSE, MODULO, IMPORTE, GLOBAL, LOCAL, REF, PONTEIRO.

11. Índice alfabético​

ABS · ACRESCENTA_TEXTO · AFIRME · ARREDONDA · ATE (X) · ATE_QUE · BITS_DE · CARACTERE_MAIUSCULO · CARACTERE_MINUSCULO · CASO · CARACTERE · COMPARA_TEXTO · CONSTANTE · CONTRARIO · COPIA_TEXTO · DE (X) · DIFERENTE · DIVIDE · E · E_DIGITO · E_LETRA · ENTAO · EPSILON_REAL · ENQUANTO · ENUMERACAO · ERRO · ESCOLHA · ESCREVA · ESCREVA_ERRO · ESCREVA_FMT · ESCREVA_LINHA · ESCREVA_TEXTO · ESCREVAL · ESTATICO · EXTERNO · FACA · FALSO · FIM · FIM_ENQUANTO · FIM_ENUMERACAO · FIM_ESCOLHA · FORMATA_TEXTO · FIM_PARA (X) · FIM_REGISTRO · FIM_SE · FUNCAO · IGUAL · INICIA_SORTEIO · INICIO · INTEIRO · INTEIRO8/16/32/64 · INTEIRO_CURTO · INTEIRO_LONGO · JUNTA_TEXTO · LEIA · LEIA_INTEIRO · LEIA_OK · LEIA_REAL · LEIA_TEXTO · LOGICO · LOGICO_DE · MAXIMO · MAXIMO_INTEIRO · MAXIMO_NATURAL · MAXIMO_REAL · MINIMO · MINIMO_INTEIRO · MOD · NAO · NATURAL · NATURAL_CURTO · NATURAL_LONGO · NATURAL8/16/32/64 · OU · OU_EXCLUSIVO · PARA · PARA_PASSO · PARE · PASSO (X) · PISO · POTENCIA · PROCEDIMENTO · PROSSIGA · RAIZ · REAL · REAL_CURTO · REAL_LONGO · REAL_PARA_INTEIRO · REGISTRO · REPITA · RESTO · RETORNE · SE · SENAO · SENAO_SE · SORTEIA · TAMANHO_DE · TAMANHO_TEXTO · TAMANHO_VETOR · TETO · TEXTO · TEXTO_FIXO · TEXTO_PARA_INTEIRO · TEXTO_PARA_NATURAL · TEXTO_PARA_REAL · TEXTO_VAZIO · TEXTOS_DIFERENTES · TEXTOS_IGUAIS · TRECHO_TEXTO · VAZIO · VERDADEIRO · VETOR

Símbolos citados neste documento​

Nomes que aparecem literalmente no texto acima e que possuem página de referência gerada do fonte:

BG_ENTAO, BG_SE, BG_SEM_APELIDOS, BG_TEM_EXTENSOES, BG_USAR_EXTENSOES, BG_VERSAO_CORRECAO, BG_VERSAO_MAIOR, BG_VERSAO_MENOR, BG_VERSAO_MINIMA.

Perguntas frequentes​

Perguntas frequentes sobre este documento, respondidas a partir do conteúdo versionado e da referência gerada.

Onde vejo a expansão exata de uma palavra-chave?​

Na página gerada do símbolo (seção Assinatura e expansão) e em 03-mapeamento-para-c. A referência mostra a forma, o perfil (N/X/C) e o significado; as páginas por nome mostram o corpo literal da macro e os usos reais nos testes.

#include <basicgol.h>

INICIO
INTEIRO idade = 0;
LEIA(idade);
SE idade >= 18 ENTAO
ESCREVAL("maior de idade");
SENAO
ESCREVAL("menor de idade");
FIM_SE
FIM

LEIA funciona com LOGICO, TEXTO ou TEXTO_FIXO?​

Não. O formato de LEIA vem de _Generic pelo tipo do destino e esses três tipos não têm associação: o compilador recusa com erro de _Generic (não é aviso).

Para texto use LEIA_TEXTO com capacidade explícita; para uma linha convertida use LEIA_INTEIRO/LEIA_REAL.

TEXTO_FIXO(nome, 80);
SE LEIA_TEXTO(nome, TAMANHO_DE(nome)) ENTAO
ESCREVAL(nome);
SENAO
ESCREVAL("nao foi possivel ler");
FIM_SE

Como junto dois textos? "a" + "b" não funciona.​

Correto: em C isso é aritmética de ponteiros e produz lixo. Use JUNTA_TEXTO (dois textos) ou ACRESCENTA_TEXTO (acrescenta ao conteúdo atual). Ambas devolvem LOGICO e esvaziam o destino em falha.

TEXTO_FIXO(nome, 32);
SE JUNTA_TEXTO(nome, TAMANHO_DE(nome), "BASIC", "GOL") ENTAO
ESCREVAL(nome);
FIM_SE

Por que existem duas formas de laço contado?​

PARA (i, a, b) é a forma N, redutível no pré-processador. PARA i DE a ATE b FACA é a forma X, que precisa de basicgolc para reordenar início, fim e incremento. As duas têm o mesmo significado e limites inclusivos.