Pular para o conteúdo principal

BASICGOL → C: tabela de mapeamento

Este documento é normativo: define exatamente em que cada construtor BASICGOL se transforma. Qualquer implementação (o cabeçalho basicgol.h da Fase 2 ou o transpilador basicgolc) deve produzir o C descrito aqui, e nada além.

Legenda de perfil: N = núcleo, funciona com macros (M0) · X = extensão, exige basicgolc (M1) · C = C nativo, sem tradução.


1. Como este mapeamento foi verificado​

Antes de congelar a especificação, cada construtor foi reduzido a macros em uma sonda descartável (não versionada: a implementação é entrega da Fase 2) e compilada com:

gcc 12.2 -std=c11 -Wall -Wextra -Wformat=2 programa.c -I <sonda> -lm

Resultado: compilação limpa (zero avisos) e comportamento esperado para todos os construtores N aqui listados. Duas descobertas dessa validação mudaram o desenho da linguagem e estão registradas em 04:

  • SENAO SE não funciona → foi criada a palavra-chave SENAO_SE (C-05).
  • LEIA + LEIA_TEXTO deixam \n pendente no stdin → LEIA_TEXTO passou a ter a obrigação contratual de descartar o resto da linha (C-20).

Os trechos de saída de pré-processador mostrados na §4 são reais (com a tabela de _Generic abreviada por … para caber na página).


2. Tabela mestra​

2.1 Programa, funções e tipos​

#Sintaxe BASICGOLC equivalentePerfil
1INICIOint main(void) {N
2FIM}N
3FUNCAO INTEIRO soma(INTEIRO a, INTEIRO b) { … }int soma(int a, int b) { … } (FUNCAO = vazio)N
4PROCEDIMENTO p(INTEIRO n) { … }void p(int n) { … }N
5RETORNE expr;return expr;N
6RETORNE;return;N
7ESTATICO FUNCAO …static int …N
8EXTERNO FUNCAO REAL media(REAL, REAL);extern double media(double, double);N
9INTEIRO x = 0;int x = 0;N
10REAL r = 1.5;double r = 1.5;N
11LOGICO ok = VERDADEIRO;bool ok = true;N
12TEXTO s = "oi";const char *s = "oi";N
13CARACTERE c = 'A';char c = 'A';N
14VAZIOvoidN
15INTEIRO8/16/32/64 / NATURAL8/16/32/64int8_t…int64_t / uint8_t…uint64_tN
16CONSTANTE INTEIRO k_n = 10;static const int k_n = 10;N
17EXTERNO INTEIRO total;extern int total;N
18(REAL) contador(double) contadorC
18aNATURAL_CURTO / NATURAL_LONGOunsigned short / unsigned longN
18bTAMANHO_DE(t) / BITS_DE(t)((size_t) sizeof(t)) / ((size_t) (sizeof(t) * CHAR_BIT))N
18cMAXIMO_INTEIRO / MINIMO_INTEIRO / MAXIMO_NATURALINT_MAX / INT_MIN / UINT_MAXN
18dMAXIMO_REAL / EPSILON_REALDBL_MAX / DBL_EPSILONN
19INTEIRO v[] (em parâmetro)int *vN/C

2.2 Declarações compostas​

#Sintaxe BASICGOLC equivalentePerfil
20VETOR(INTEIRO, notas, 4);int notas[4];N
21VETOR(TEXTO, nomes, 10);const char *nomes[10];N
22TEXTO_FIXO(nome, 40);char nome[40];N
23TAMANHO_VETOR(notas)(sizeof(notas) / sizeof((notas)[0]))N
24REGISTRO(Aluno) … FIM_REGISTRO(Aluno);typedef struct Aluno { … } Aluno;N
25ENUMERACAO(Conceito) A, B FIM_ENUMERACAO(Conceito);typedef enum Conceito { A, B } Conceito;N
26aluno.notaaluno.notaC
27notas[i]notas[i]C

2.3 Controle de fluxo​

#Sintaxe BASICGOLC equivalentePerfil
28SE c ENTAOif ( c ) {N
29SENAO_SE c ENTAO} else if ( c ) {N
30SENAO} else {N
31FIM_SE}N
32ENQUANTO c FACAwhile ( c ) {N
33FIM_ENQUANTO}N
34REPITAdo {N
35ATE_QUE(c);} while (!(c));N
36PARA (i, 1, 10) { … }for ((i) = (1); (i) <= (10); ++(i)) { … }N
37PARA_PASSO (i, 0, 100, 10) { … }for ((i) = (0); ((10) > 0) ? ((i) <= (100)) : (((10) == 0) ? bg_passo_zero(__FILE__, __LINE__) : ((i) >= (100))); (i) += (10)) { … } — o passo negativo conta para trás; passo zero é erro de execuçãoN
38PARA i DE 1 ATE 10 FACA … FIM_PARAfor (i = (1); (1) > 0 ? (i <= (10)) : ((1) == 0 ? bg_passo_zero(__FILE__, __LINE__) : (i >= (10))); i += (1)) { … }X
39ESCOLHA(e)switch (e) {N
40CASO 2:case 2:N
41CONTRARIO:default:N
42FIM_ESCOLHA}N
43PARE;break;N
44PROSSIGA;continue;N
45se/caso com bloco próprio: CASO 3: { … }idênticoC

2.4 Expressões​

#Sintaxe BASICGOLC equivalentePerfil
46a E ba && bN
47a OU ba || bN
48NAO a!aN
49a MOD ba % bN
50VERDADEIRO / FALSOtrue / falseN
51IGUAL(a, b)((a) == (b))N
52DIFERENTE(a, b)((a) != (b))N
53TEXTOS_IGUAIS(a, b)(strcmp((a), (b)) == 0)N
54TEXTOS_DIFERENTES(a, b)(strcmp((a), (b)) != 0)N
54aOU_EXCLUSIVO(a, b)((bool) (((a) != 0) != ((b) != 0)))N
54bLOGICO_DE(x)((bool) ((x) != 0))N
54cDIVIDE(a, b)_Generic((a)+(b), int: bg_divide_i, …, double: bg_divide_d, default: bg_divide_d)((a), (b), __FILE__, __LINE__)N
54dRESTO(a, b)_Generic((a)+(b), int: bg_resto_i, …)((a), (b), __FILE__, __LINE__) — sem realN
55ABS(x)_Generic((x), int: bg_abs_i, long: bg_abs_l, float: bg_abs_f, double: bg_abs_d, default: bg_abs_d)(x)N
56MINIMO(a, b) / MAXIMO(a, b)despacho _Generic para bg_min_*/bg_max_*N
57POTENCIA(b, e)pow((b), (e))N
58RAIZ(x)sqrt(x)N
59ARREDONDA(x)bg_round_l((double)(x))N
60PISO(x) / TETO(x)floor(x) / ceil(x)N
61TAMANHO_TEXTO(s)bg_tamanho_texto(s)N
62SORTEIA(n)bg_sorteia(n)N
63INICIA_SORTEIO(s)bg_inicia_sorteio((unsigned)(s))N
63aACRESCENTA_TEXTO(d, t, s)bg_acrescenta_texto((d), (size_t)(t), (s))N
63bTRECHO_TEXTO(d, t, s, i, n)bg_trecho_texto((d), (size_t)(t), (s), (size_t)(i), (size_t)(n))N
63cCOMPARA_TEXTO(a, b)bg_compara_texto((a), (b))N
63dTEXTO_VAZIO(s)bg_texto_vazio(s)N
63eFORMATA_TEXTO(d, t, …)bg_formata_texto((d), (size_t)(t), __VA_ARGS__)N
63fE_DIGITO(c) / E_LETRA(c)bg_e_digito(c) / bg_e_letra(c) (ASCII)N
63gCARACTERE_MAIUSCULO(c) / CARACTERE_MINUSCULO(c)bg_caractere_maiusculo(c) / bg_caractere_minusculo(c)N
63hTEXTO_PARA_NATURAL(s, p)bg_texto_para_natural((s), (p))N
63iREAL_PARA_INTEIRO(x, p)bg_numero_para_inteiro((x), (p))N
63jSOMA_SEGURA(a,b,p) etc.bg_soma_segura((a),(b),(p)) — só com BG_USAR_EXTENSOESN (opcional)

2.5 Entrada e saída​

#Sintaxe BASICGOLC equivalentePerfil
64ESCREVA(x);printf(_Generic((x), …), (x)) (formato por tipo)N
65ESCREVAL(x);(printf(_Generic((x), …), (x)), fputc('\n', stdout))N
66ESCREVA_LINHA();fputc('\n', stdout)N
67ESCREVA_TEXTO(s);printf("%s", (s))N
68ESCREVA_FMT(fmt, …);printf(__VA_ARGS__)N
69ESCREVA_ERRO(s);fprintf(stderr, "%s", (s))N
70LEIA(x);((void)(scanf(_Generic(&(x), …), &(x)) == 1))N
71LEIA_OK(x);(scanf(_Generic(&(x), …), &(x)) == 1)N
72LEIA_TEXTO(buf, tam);bg_leia_texto((buf), (size_t)(tam))N
72aLEIA_INTEIRO(x);bg_leia_inteiro(&(x)) (linha inteira, devolve LOGICO)N
72bLEIA_REAL(x);bg_leia_real(&(x))N

2.6 Erros​

#Sintaxe BASICGOLC equivalentePerfil
73ERRO("msg");bg_erro(__FILE__, __LINE__, ("msg"))N
74AFIRME(c, "msg");((c) ? (void)0 : bg_erro(__FILE__, __LINE__, ("msg")))N

3. Definições normativas das macros​

Trecho normativo do cabeçalho (a implementação completa, com nomes prefixados, detecção de compilador e documentação embutida, é entrega da Fase 2). Esta é a forma verificada:

/* ---- programa ---- */
#define INICIO int main(void) {
#define FIM }

/* ---- tipos ---- */
#define LOGICO bool
#define CARACTERE char
#define INTEIRO_CURTO short
#define INTEIRO int
#define INTEIRO_LONGO long
#define INTEIRO8 int8_t
#define INTEIRO16 int16_t
#define INTEIRO32 int32_t
#define INTEIRO64 int64_t
#define NATURAL unsigned
#define NATURAL8 uint8_t
#define NATURAL16 uint16_t
#define NATURAL32 uint32_t
#define NATURAL64 uint64_t
#define REAL_CURTO float
#define REAL double
#define REAL_LONGO long double
#define TEXTO const char *
#define VAZIO void
#define CONSTANTE static const
#define ESTATICO static
#define EXTERNO extern

/* ---- declarações ---- */
#define VETOR(t, n, k) t n[k]
#define TAMANHO_VETOR(v) (sizeof(v) / sizeof((v)[0]))
#define TEXTO_FIXO(n, k) char n[k]
#define REGISTRO(n) typedef struct n {
#define FIM_REGISTRO(n) } n
#define ENUMERACAO(n) typedef enum n {
#define FIM_ENUMERACAO(n) } n

/* ---- funções ---- */
#define FUNCAO
#define PROCEDIMENTO void
#define RETORNE return

/* ---- controle ---- */
#define SE if (
#define ENTAO ) {
#define SENAO_SE } else if (
#define SENAO } else {
#define FIM_SE }
#define ENQUANTO while (
#define FACA ) {
#define FIM_ENQUANTO }
#define REPITA do {
#define ATE_QUE(c) } while (!(c))
#define ESCOLHA(e) switch (e) {
#define CASO case
#define CONTRARIO default
#define FIM_ESCOLHA }
#define PARE break
#define PROSSIGA continue
#define PARA(i, a, b) for ((i) = (a); (i) <= (b); ++(i))
#define PARA_PASSO(i, a, b, p) for ((i) = (a); ((p) > 0) ? ((i) <= (b)) : (((p) == 0) ? bg_passo_zero(__FILE__, __LINE__) : ((i) >= (b))); (i) += (p))

/* ---- operadores por palavra ---- */
#define E &&
#define OU ||
#define NAO !
#define MOD %
#define VERDADEIRO true
#define FALSO false
#define IGUAL(a, b) ((a) == (b))
#define DIFERENTE(a, b) ((a) != (b))
#define TEXTOS_IGUAIS(a, b) (strcmp((a), (b)) == 0)
#define TEXTOS_DIFERENTES(a, b) (strcmp((a), (b)) != 0)

/* ---- E/S ---- */
#define BG_FMT(x) _Generic((x), \
_Bool: "%d", char: "%c", signed char: "%hhd", unsigned char: "%hhu", \
short: "%hd", unsigned short: "%hu", int: "%d", unsigned int: "%u", \
long: "%ld", unsigned long: "%lu", long long: "%lld", \
unsigned long long: "%llu", float: "%g", double: "%g", \
long double: "%Lg", char *: "%s", const char *: "%s", default: "%p")
#define ESCREVA(x) printf(BG_FMT(x), (x))
#define ESCREVAL(x) (printf(BG_FMT(x), (x)), fputc('\n', stdout))
#define ESCREVA_LINHA() fputc('\n', stdout)
#define ESCREVA_TEXTO(s) printf("%s", (s))
#define ESCREVA_FMT(...) printf(__VA_ARGS__)
#define ESCREVA_ERRO(s) fprintf(stderr, "%s", (s))

/* Sem `default`: destino sem formato (LOGICO, TEXTO, TEXTO_FIXO) é
* violação de restrição do _Generic (C11 6.5.1.1p3) — erro de compilação,
* com ou sem -Werror. Com `default: "%p"` o scanf gravaria um ponteiro
* (8 bytes) dentro de um LOGICO de 1 byte. Ver DF-01 em 13-defeitos. */
#define BG_SFMT(x) _Generic(&(x), \
int *: "%d", unsigned *: "%u", long *: "%ld", unsigned long *: "%lu", \
long long *: "%lld", unsigned long long *: "%llu", \
float *: "%f", double *: "%lf", long double *: "%Lf", \
char *: " %c", signed char *: " %hhd", unsigned char *: "%hhu", \
short *: "%hd", unsigned short *: "%hu")
#define LEIA(x) ((void)(scanf(BG_SFMT(x), &(x)) == 1))
#define LEIA_OK(x) (scanf(BG_SFMT(x), &(x)) == 1)
#define LEIA_TEXTO(b, t) bg_leia_texto((b), (size_t)(t))

/* ---- erros ---- */
#define ERRO(msg) bg_erro(__FILE__, __LINE__, (msg))
#define AFIRME(c, msg) ((c) ? (void)0 : bg_erro(__FILE__, __LINE__, (msg)))

/* ---- Fase 4: tipos, operadores e conversões verificadas ---- */
#define NATURAL_CURTO unsigned short
#define NATURAL_LONGO unsigned long
#define TAMANHO_DE(t) ((size_t) sizeof(t))
#define BITS_DE(t) ((size_t) (sizeof(t) * CHAR_BIT))
#define MAXIMO_INTEIRO INT_MAX
#define MINIMO_INTEIRO INT_MIN
#define MAXIMO_NATURAL UINT_MAX
#define MAXIMO_REAL DBL_MAX
#define EPSILON_REAL DBL_EPSILON

#define OU_EXCLUSIVO(a, b) ((bool) (((a) != 0) != ((b) != 0)))
#define LOGICO_DE(x) ((bool) ((x) != 0))
#define DIVIDE(a, b) _Generic((a) + (b), /* … por tipo … */ \
default: bg_divide_d)((a), (b), __FILE__, __LINE__)
#define RESTO(a, b) _Generic((a) + (b), /* só tipos inteiros */ \
default: bg_resto_i)((a), (b), __FILE__, __LINE__)

#define ACRESCENTA_TEXTO(d, t, o) bg_acrescenta_texto((d), (size_t)(t), (o))
#define TRECHO_TEXTO(d, t, o, i, q) bg_trecho_texto((d), (size_t)(t), (o), (size_t)(i), (size_t)(q))
#define COMPARA_TEXTO(a, b) bg_compara_texto((a), (b))
#define TEXTO_VAZIO(s) bg_texto_vazio(s)
#define FORMATA_TEXTO(d, t, ...) bg_formata_texto((d), (size_t)(t), __VA_ARGS__)
#define E_DIGITO(c) bg_e_digito(c)
#define E_LETRA(c) bg_e_letra(c)
#define CARACTERE_MAIUSCULO(c) bg_caractere_maiusculo(c)
#define CARACTERE_MINUSCULO(c) bg_caractere_minusculo(c)
#define TEXTO_PARA_NATURAL(s, p) bg_texto_para_natural((s), (p))
#define REAL_PARA_INTEIRO(x, p) bg_numero_para_inteiro((x), (p))
#define LEIA_INTEIRO(x) bg_leia_inteiro(&(x))
#define LEIA_REAL(x) bg_leia_real(&(x))

Observações normativas sobre este bloco:

  • SENAO expande para } else { e portanto encadeia mal; por isso existe SENAO_SE (§C-05).
  • SE expande para if ( e portanto não aceita { em seguida; por isso ENTAO existe (§C-06).
  • INICIO/FIM são macros objeto que produzem a definição de main; não use main em arquivo com INICIO.
  • FUNCAO é uma macro vazia de propósito: FUNCAO + tipo é mais legível que só o tipo, e a expansão é literalmente o tipo.
  • ATE_QUE(c) consome o ; do programador: ATE_QUE(c); → } while (!(c));.
  • Nomes prefixados (BG_SE, BG_ENTAO, …) têm a mesma expansão, e são obrigatórios quando BG_SEM_APELIDOS está definido antes do #include.

4. Saída real do pré-processador​

4.1 Condicional (gcc -E -P)​

Fonte:

INICIO
INTEIRO nota = 8;
SE nota >= 7 ENTAO
ESCREVAL("Aprovado");
SENAO
ESCREVAL("Reprovado");
FIM_SE
FIM

Saída (tabela _Generic abreviada por …):

int main(void) {
int nota = 8;
if ( nota >= 7 ) {
(printf(_Generic(("Aprovado"), …), ("Aprovado")), fputc('\n', stdout));
} else {
(printf(_Generic(("Reprovado"), …), ("Reprovado")), fputc('\n', stdout));
}
}

4.2 Registro, vetor, laço contado e cadeia SE/SENAO_SE​

Fonte:

REGISTRO(Aluno)
INTEIRO matricula;
REAL nota;
FIM_REGISTRO(Aluno);

INICIO
VETOR(INTEIRO, v, 3);
Aluno a;
INTEIRO i;
PARA (i, 0, 2) {
v[i] = i * 2;
}
SE a.nota >= 7 E a.matricula > 0 ENTAO
ESCREVAL(a.matricula);
SENAO_SE a.nota >= 5 ENTAO
ESCREVAL(0);
SENAO
ESCREVAL(-1);
FIM_SE
RETORNE 0;
FIM

Saída:

typedef struct Aluno {
int matricula;
double nota;
} Aluno;
int main(void) {
int v[3];
Aluno a;
int i;
for ((i) = (0); (i) <= (2); ++(i)) {
v[i] = i * 2;
}
if ( a.nota >= 7 && a.matricula > 0 ) {
} else if ( a.nota >= 5 ) {
} else {
}
return 0;
}

Esse é o argumento central da linguagem: o aluno escreveu BASIC/Portugol e o compilador viu C.


5. Tabela reversa: de BG para C (material de aula)​

ConceitoBASICGOLC
blocoSE … ENTAO … FIM_SEif (…) { … }
senãoSENAOelse
senão seSENAO_SEelse if
enquantoENQUANTO c FACA … FIM_ENQUANTOwhile (c) { … }
repitaREPITA … ATE_QUE(c);do { … } while (!(c));
paraPARA (i, a, b) { … }for (i = a; i <= b; ++i) { … }
escolhaESCOLHA(e) … FIM_ESCOLHAswitch (e) { … } (M1 emite switch e as chaves)
casoCASO v:case v:
padrãoCONTRARIO:default:
parePARE;break;
continuePROSSIGA;continue;
retorneRETORNE x;return x;
escrevaESCREVA(x);printf(…)
leiaLEIA(x);scanf(…, &x)
textoTEXTO s = "oi";const char *s = "oi";
vetorVETOR(INTEIRO, v, 10);int v[10];
registroREGISTRO(Aluno) … FIM_REGISTRO(Aluno);typedef struct Aluno { … } Aluno; (M1 emite typedef struct e as chaves)
e/ou/nãoE OU NAO&& || !
móduloMOD%

6. O que não é mapeável (e o substituto)​

Sintaxe desejadaPor que não dáSubstituto
VETOR INTEIRO v DE 10;exigiria reordenar tokens (int v[10])VETOR(INTEIRO, v, 10); (N)
PARA i DE 1 ATE 10 FACAexigiria montar três partes de for fora de ordemPARA (i, 1, 10) { } (N) ou M1 (X)
ESCREVA "oi" (sem parênteses)o pré-processador não vê fim de linha nem precedênciaESCREVA("oi"); — nunca haverá
ESCREVAL(a, b, c)sem contagem/classificação de variádicosuma chamada por valor, ou ESCREVA_FMT
SE x { … }SE já emite (; colidiria com a forma canônicaSE x ENTAO … FIM_SE, ou if (x) { … }
SENAO SE cond ENTAOSENAO emite } else {, gerando { extraSENAO_SE cond ENTAO
FUNCAO soma(a, b) INTEIROexigiria mover o tipo de voltaFUNCAO INTEIRO soma(…)
fim de bloco automático pela indentaçãomacros não veem indentaçãoFIM_SE, FIM_ENQUANTO, …
; opcionalmacro não pode inserir ; com segurança depois de comandos arbitrários; obrigatório (P-07)
texto com + ("a" + "b")em C é aritmética de ponteirosJUNTA_TEXTO(dest, tam, a, b)
TEXTO modificável (s[0] = 'x')TEXTO é const char *TEXTO_FIXO(nome, tam)
ESCOLHA(a, b) (vírgula no nível superior)a vírgula seria lida como separador de argumentosatribua a uma variável antes. ESCOLHA(f(a, b)) é válido: os parênteses internos protegem a vírgula (correção empírica da Fase 2 — ver C-04 em 04)
identificadores acentuados (média)C não garante; quebra portabilidademedia
PARA i DE 1 ATE 10 com i novo (INTEIRO i)exige declaração + laço (2 construtos)declare antes
TENTE/CAPTUREnão há exceções em Cvalor de retorno + AFIRME/ERRO
vetor de tamanho dinâmico VETOR(t, v, n) com n variávelseria VLA: vetores de tamanho variável são limitados e perigososmalloc (C nativo) ou tamanho máximo fixo
VETOR(t, v, k_minha_constante) com CONSTANTEstatic const int não é expressão constante em C → VLA silenciosouse literal (VETOR(t, v, 30)) ou #define (C-23)

7. Biblioteca de execução (API especificada)​

A Fase 5 mantém as expansões de linguagem desta especificação, mas moveu a biblioteca para headers por módulo em include/basicgol/ e implementações em src/biblioteca/. <basicgol.h> reexporta esses headers. Os helpers que forem usados devem ser ligados por build/libbasicgol.a (ou pelos fontes); build, parâmetros e retornos completos estão em 09 — Biblioteca padrão.

A API pública C usa bg_ e inclui:

/* console */
_Noreturn void bg_erro(const char *arquivo, int linha, const char *mensagem);
int bg_passo_zero(const char *arquivo, int linha); /* fatal; só para PARA_PASSO */
bool bg_leia_linha(FILE *entrada, char *destino, size_t capacidade);
bool bg_leia_texto(char *destino, size_t capacidade); /* wrapper stdin de LEIA_TEXTO */
bool bg_leia_inteiro_de(FILE *entrada, int *saida);
bool bg_leia_real_de(FILE *entrada, double *saida);
bool bg_leia_inteiro(int *saida); /* stdin */
bool bg_leia_real(double *saida); /* stdin */
bool bg_escreva_texto(FILE *saida, const char *texto);
bool bg_escreva_linha(FILE *saida, const char *texto);

/* texto: bool false indica falha; destino é limpo quando utilizável */
size_t bg_tamanho_texto(const char *texto);
bool bg_copia_texto(char *destino, size_t capacidade, const char *origem);
bool bg_junta_texto(char *destino, size_t capacidade,
const char *primeiro, const char *segundo);
bool bg_acrescenta_texto(char *destino, size_t capacidade, const char *origem);
bool bg_trecho_texto(char *destino, size_t capacidade, const char *origem,
size_t inicio, size_t quantidade);
int bg_compara_texto(const char *primeiro, const char *segundo); /* -1/0/+1 */
bool bg_texto_vazio(const char *texto);
bool bg_formata_texto(char *destino, size_t capacidade, const char *formato, ...);
bool bg_texto_para_inteiro(const char *texto, int *saida);
bool bg_texto_para_natural(const char *texto, unsigned *saida);
bool bg_texto_para_real(const char *texto, double *saida);
bool bg_numero_para_inteiro(double valor, int *saida);

/* ASCII */
bool bg_e_digito(char caractere);
bool bg_e_letra(char caractere);
char bg_caractere_maiusculo(char caractere);
char bg_caractere_minusculo(char caractere);

/* matemática: famílias por tipo */
int bg_divide_i(int a, int b, const char *arquivo, int linha);
/* também bg_divide_l/ll/u/ul/ull/f/d/ld com o tipo indicado no sufixo */
int bg_resto_i(int a, int b, const char *arquivo, int linha);
/* também bg_resto_l/ll/u/ul/ull */
int bg_abs_i(int valor); /* bg_abs_l/ll/f/d; mínimo assinado é erro fatal */
int bg_min_i(int a, int b); /* bg_min_l/d, bg_max_i/l/d */
long long bg_round_l(double valor);

/* utilidades — rand() global, não criptográfico */
void bg_inicia_sorteio(unsigned semente);
bool bg_sorteia_ate(unsigned limite_exclusivo, unsigned *saida);
int bg_sorteia(int n); /* alias compatível: n inválido devolve 0 */

Convenções fundamentais: as funções que escrevem em buffers recebem capacidade explícita incluindo NUL; memória e streams pertencem ao chamador; falhas recuperáveis retornam false sem alterar saídas numéricas; as conversões preservam errno. Só bg_erro e os wrappers de linguagem para entradas impossíveis (divisor zero, quociente assinado não representável e magnitude de ABS que não cabe) encerram o processo. O sorteio exige semente explícita e declara a faixa limitada por RAND_MAX; detalhes e limitações estão em 09.

Requisitos de qualidade da biblioteca:

IDRequisito
RB-1Nenhum macro avalia um argumento mais de uma vez
RB-2Efeitos de I/O, alocação temporária e gerador pseudoaleatório estão documentados
RB-3Truncamento de texto é reportado por valor de retorno e não deixa conteúdo parcial
RB-4bg_erro é o único terminador explícito; wrappers matemáticos só o usam em domínio inválido documentado
RB-5Todos os módulos compilam sem avisos com GCC e Clang em C11
RB-6Core portátil sem extensão de compilador nem dependência de plataforma
RB-7Conversão texto→número exige o texto inteiro, sem sobra
RB-8bg_leia_texto descarta apenas terminador pendente; bg_leia_linha preserva linha vazia
RB-9Toda operação de texto com destino limitado informa falha e limpa o destino quando possível
RB-10Conversão verificada não altera saída quando falha
RB-11DIVIDE/RESTO recusam zero e quociente assinado não representável, com diagnóstico na origem da macro
RB-12Conversores restauram errno após usar strto*; false é a indicação de falha
RB-13NULL é texto vazio onde documentado; operações com destino suportam sobreposição
RB-14rand() tem semente explícita, limite documentado e nenhuma promessa criptográfica

8. Regras normativas para implementadores​

IDRegra
RG-1Toda macro com argumentos parentiza cada uso do argumento.
RG-2Nenhum argumento de macro aparece mais de uma vez na expansão (P-11); se precisar de estado/uma única avaliação, use uma função C da biblioteca.
RG-3Macros de comando não têm valor utilizável (são instruções); não as use em expressão.
RG-4Nenhuma macro de bloco usa do { … } while (0): os FIM_* já fecham o bloco com }, e um invólucro do/while(0) impediria SENAO de se ligar ao if gerado por SE.
RG-5As expansões devem ser exatamente as da §3; mudanças exigem alteração desta especificação e nova rodada de validação.
RG-6O cabeçalho deve ser idempotente (#ifndef), compilável isoladamente e não deve definir nada além do que está documentado.
RG-7O cabeçalho deve funcionar incluído depois de <stdio.h>, <math.h> e <string.h> (que ele mesmo inclui).
RG-8Diante de BG_SEM_APELIDOS, nenhum nome curto pode ser definido.
RG-9O mapeamento não pode depender de sizeof, de avaliação em tempo de execução nem de qualquer informação que só o transpilador teria.
RG-10basicgolc (M1) deve emitir C sem macros (palavras-chave já traduzidas, chaves explícitas), para que as mensagens do compilador apontem para o código do aluno.

Símbolos citados neste documento​

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

bg_erro, bg_leia_texto, bg_passo_zero, BG_FMT, BG_SFMT, bg_acrescenta_texto, bg_caractere_maiusculo, bg_caractere_minusculo, bg_compara_texto, bg_divide_d, bg_e_digito, bg_e_letra, bg_formata_texto, bg_leia_inteiro, bg_leia_real, bg_numero_para_inteiro, bg_resto_i, bg_texto_para_natural.

Perguntas frequentes​

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

As expansões mostradas são reais ou ilustrativas?​

São reais: a seção 4 do documento registra a saída literal de gcc -E -P. A tabela de expansões também é conferida com cc -E -dM pelos testes, e a página de cada macro mostra o corpo extraído do cabeçalho.

cc -std=c11 -I include -E -P programa.c | sed -n '1,40p'
cc -std=c11 -I include -E -dM programa.c | grep -E '^#define (BG_SE|SE) '

O que não é mapeável para macros?​

Tudo que exige reordenar tokens ou inserir texto que o programador não escreveu. O caso clássico é PARA i DE 1 ATE 10 FACA: as palavras aparecem antes do corpo, mas o for de C precisa de inicialização, condição e incremento no cabeçalho. Isso é M1.

SENAO SE (dois tokens) também não é normalizável pelas macros: use SENAO_SE.

Como auditar um construtor específico?​

Siga a cadeia: tabela mestra → definição normativa → página gerada do símbolo → referências em testes. A página mostra a definição canônica, a expansão e cada ocorrência com linha, o que permite reproduzir exatamente o que foi compilado.

Por que a tabela reversa (BG para C) existe?​

Para uso didático: ela mostra o que o aluno escreveria em C e serve de ponte para sair do dialeto. É material de aula, não uma API nem uma promessa de tradução automática nos dois sentidos.