Lição 36: Macros Básicas (Protocolos de Expansão)

1. Narrativa

O mecha Æther possui módulos de comunicação que geram mensagens padronizadas automaticamente — Protocolos de Expansão são como macros declarativas que expandem código em tempo de compilação. O piloto cria templates de código que se repetem, economizando escrita manual e garantindo consistência.

2. Conceito

Macros declarativas (macro_rules!) são padrões que casam com código-fonte e o expandem. Diferente de funções, macros operam em tokens, não valores:

• macro_rules!: Define uma macro com padrões (braços)
• Braços (pattern) => { expansion }: Cada padrão gera código diferente
• Metavariáveis: $x:expr (expressão), $y:ty (tipo), $z:ident (identificador)
• Repetição: $($x),* — captura lista de itens separados por vírgula
• Expansão em tempo de compilação: Zero custo em runtime

3. Requisitos

• Criar macros com macro_rules!
• Usar metavariáveis ($x:expr, $y:ty, $z:ident)
• Aplicar repetição $($x),* para múltiplos argumentos
• Distinguir macros de funções

4. Design de Dados

graph LR
    A[Código-fonte] --> B[macro_rules!]
    B --> C[Casamento de padrão]
    C --> D[Expansão de tokens]
    D --> E[Código expandido]
    E --> F[Compilação normal]

5. Diagrama de Fluxo

flowchart TD
    A[Início: invocar macro] --> B{Qual padrão?}
    B -->|1 arg| C[Expandir braço simples]
    B -->|N args| D[Expandir com repetição]
    C --> E[Substituir metavariáveis]
    D --> E
    E --> F[Inserir código expandido]
    F --> G[Compilar código final]
    G --> H[Fim]

6. Funções

Função / Macro	Descrição
status_mecha!	Macro que imprime status com prefixo [ÆTHER]
vec_mecha!	Macro que cria Vec com $($x),* repetição
config_mecha!	Macro que cria HashMap de $key:ident : $val:expr
contar_bracos_macro	Conta braços de macro (stub educacional)
formatar_diagnostico	Formata mensagem de diagnóstico
verificar_condicoes	Verifica se todas condições são true
gerar_relatorio	Gera relatório textual de sistemas
transformar_lote	Aplica função a múltiplos valores
contar_ocorrencias	Conta ocorrências de valor em lista

7. Exemplo

// Macro básica com uma expressão
status_mecha!("Sistemas OK");
// Expande para: println!("[ÆTHER] Sistemas OK");

// Macro com repetição
let v: Vec<i32> = vec_mecha![1, 2, 3];
// Expande para: { let mut t = Vec::new(); t.push(1); t.push(2); t.push(3); t }

// Macro com identificador e expressão
let config = config_mecha! { potencia: 100 };
// Expande para HashMap com chave "potencia" e valor "100"

8. Missão

1. Entender como status_mecha! expande para println!
2. Implementar contar_bracos_macro retornando o total de macros declaradas no arquivo (3)
3. Implementar formatar_diagnostico seguindo o padrão da macro
4. Implementar verificar_condicoes usando .iter().all()
5. Implementar gerar_relatorio com formatação de strings
6. Implementar transformar_lote usando .iter().map().collect()
7. Implementar contar_ocorrencias usando .iter().filter().count()
8. Estudar como vec_mecha! usa $($x),* para repetição
9. Estudar como config_mecha! usa $key:ident : $val:expr

9. Como Executar

cargo build
cargo test
cargo clippy -- -D warnings
cargo fmt --check

10. Dicas

• Macros expandem em tempo de compilação — não existem em runtime
• $x:expr captura qualquer expressão Rust; $x:ty captura tipos
• $($x),* significa "zero ou mais X separados por vírgulas"
• Macros são mais poderosas que funções, mas mais difíceis de depurar
• Use cargo expand para ver o código expandido pelas macros