DEV Community: Angelo Belchior

Criando um compilador em csharp: Parte 7

Angelo Belchior — Fri, 22 Aug 2025 23:45:00 +0000

Parte 7! Chegamos!

Habemus for!

E mais uma vez implementamos uma funcionalidade ao vivo! Gostei desse formato.

Agora é possível escrever códigos como esse:

for int i = 1 to 10 step 2
 print(1)
end

Porém, se você não assistiu, não tem problema: vou repassar o código de ponta a ponta para que você não perca nada.

Então, vamos ao que viemos.

Se você nos acompanha, já sabe que começamos sempre fazendo o mapeamento dos tokens:

Pasta CodeAnalysis:

public enum TokenType  
{  
  .. 
  For,  
  To,  
  Step,
  ...
}

public class Token  
{  
  ...
  public const string FOR = "for";  
  public const string TO = "to";  
  public const string STEP = "step";  
  ...
  public static Token For(int position)  
      => new(TokenType.For, FOR, position);  
  public static Token To(int position)  
      => new(TokenType.To, TO, position);  
  public static Token Step(int position)  
      => new(TokenType.Step, STEP, position);  
}

Basicamente, adicionamos novos itens de enum que mapeiam os novos tokens: for, to e step.

Agora é extrair do código:

public class Lexer  
{
    private Token ExtractKeyword()  
    {  
      ...

      if (identifier.Value == Token.FOR)  
          return Token.For(position);  
      if (identifier.Value == Token.TO)  
          return Token.To(position);  
      if (identifier.Value == Token.STEP)  
          return Token.Step(position);  

      return Token.Identifier(position, identifier.Value);  
    }
}

Sem segredo e sem suar…

Agora precisamos alterar nossa classe SyntaxParser. O mais interessante é que, após muitas implementações, temos basicamente um padrão a ser seguido para adicionar uma funcionalidade nova.

Na live fiz questão de mostrar novamente como penso no momento de implementação de uma nova feature.

Analise o código abaixo:

for int i = 1 to 10 step 2
 print(1)
end

Para que eu “visualize” o fluxo de implementação, gosto de escrever o código dessa forma:

$for [int i =] {1} to {10} $step {2} < print(1) > $end
.......................................^............^
                                       |<-<-<-<-<-<-|

Explicando:

O que começa com $ são tokens que preciso validar a sua existência (caso seja obrigatório) e sua posição no código.
O que está entre colchetes é um evaluate interno, isto é, eu valido os tokens de declaração de variável e jogo na memória global (OK, não é a forma ideal, mas isso vai mudar num futuro) .
O que está entre { } é uma expressão e, sendo assim, vamos aplicar o EvaluateExpression. Dessa forma, podemos colocar qualquer expressão válida para calcularmos o valor.
O que está entre < > é um processo que vai ser executado inúmeras vezes, e para isso vamos invocar o método ParseBlock que por sua vez efetua um EvaluateToken caso o token atual não seja um token delimitador de bloco.

Basicamente é isso. E caso você não tenha entendido o que é um token delimitador de bloco, explico: um bloco de código é aquele que começa com um determinado token e termina com end ou - no caso do if - else.

if -> end
if -> else -> end
while -> end
for -> end

Sendo, assim, precisamos saber exatamente quando existiu uma abertura e um fechamento de bloco. Falei mais sobre isso no post anterior.

Arquivo CodeAnalysis/SyntaxParser.cs:

public class SyntaxParser(Dictionary<string, Identifier> variables, List<Token> tokens)  
{
    ...
    private Identifier EvaluateToken()  
        => CurrentToken.Type switch  
        {  
            ...
            TokenType.For => EvaluateFor()
            ...
        };
    ...

    private Identifier EvaluateFor()
    {
        // Valido se o token é o for
        NextIfTokenIs(TokenType.For);

        /// Extraio a declaração de variável
        NextIfTokenIs(TokenType.DataType);
        var variableToken = NextIfTokenIs(TokenType.Identifier);
        var variableName = variableToken.Value;

        // Inicializo o valor da variável que dá início ao for como 1
        var from = new Identifier(DataTypes.Int, 1);
        // Caso exista uma atribuição na declaração de variável, o evaluate expression é invocado.
        if (CurrentToken.Type == TokenType.Assign)
        {
            NextIfTokenIs(TokenType.Assign);
            from = EvaluateExpression();
        }
        // Seto o valor do from na "memória"
        variables[variableName] = from;

        // Validamos e aavançamos até o to
        NextIfTokenIs(TokenType.To);
        // Obtemos o valor informado ao to a partir de uma expressão. 
        var to = EvaluateExpression();
        var end = to.ToInt();

        // O step é opcional sendo seu valor inicial 1 
        var stepValue = 1;
        // Caso o step seja informado, o seu valor é obtido a partir de uma expressão. 
        if (CurrentToken.Type == TokenType.Step)
        {
            NextIfTokenIs(TokenType.Step);
            var step = EvaluateExpression();
            stepValue = step.ToInt();
        }

        // Após obter todos os dados referente a declaração do for, armazeno a posição atual do token. Isso serve para que o looping volte sempre para o lugar correto.
        var forPosition = _currentPosition;
        // efetuamos o looping (tanto crescente, quanto decrescente)
        while (
            (stepValue > 0 && variables[variableName].ToInt() <= end) ||
            (stepValue < 0 && variables[variableName].ToInt() >= end)
        )
        {
            // Fazemos o parse do corpo do for
            ParseBlock();
            variables[variableName] = new Identifier(DataTypes.Int, variables[variableName].ToInt() + stepValue);
            _currentPosition = forPosition;
        }

       // Avançamos até sair do for
        SkipBlockUntil();

        // Validamos se o for termina com o end
        NextIfTokenIs(TokenType.End);
        return Identifier.None;
    }
}

Fiz questão de explicar trecho por trecho no próprio código e acredito que não tem segredo.

Aliás, tem sim!!! O segredo é “visualizar” o trecho de código que será analisado, demarcando cada ponto. Dessa forma, fica muito fácil implementar cada parte já que temos praticamente tudo feito pelo fato de termos implementado if/else e while.

É isso. Simples assim.

Curtiu?

Código-fonte está em https://github.com/angelobelchior/Pug.Compiler/tree/parte7

Muito obrigado e até a próxima!

🚀 A nossa live sobre compiladores vai começar em breve, as 21:00hs! 👉 Venha acompanhar com a gente e participar ao vivo: https://www.youtube.com/live/GAfQukDTVIo

Angelo Belchior — Sun, 17 Aug 2025 23:44:54 +0000

Criando um compilador em csharp: Parte 6

Angelo Belchior — Wed, 30 Jul 2025 20:36:00 +0000

Parte 6! Chegamos!

E dessa vez fizemos algo um pouco diferente: fizemos uma live mostrando a implementação do nosso famigerado while! Ao vivo, a cores e em Full HD!

Saca só!!!

Essa, aliás, foi a segunda live sobre o tema. Antes dela, fiz uma para explicar um pouco sobre o processo de criação do compilador e tirar dúvidas. Caso queira assistir, clique aqui.

De qualquer forma, vou repassar a implementação detalhando cada ponto importante…

Bom, vamos ao que viemos.

Como sempre, a implementação de uma nova funcionalidade passa pela criação e extração dos tokens. Para quem acompanha a série, já sabe e de cor e salteado como fazer isso:

Arquivo CodeAnalysis/TokenType.cs:

public enum TokenType  
{  
    ...
    While,
    ...
}

Começamos adicionando um novo item de enum chamado While. Em seguida, vamos modificar a classe Token.cs:

Arquivo CodeAnalysis/Token.cs:

public class Token  
{  
    ...
    public const string WHILE = "while";  
    ...
    public static Token While(int position)  
        => new(TokenType.While, WHILE, position);  
    ...  
}

Com isso, já podemos começar a extração do token while.
Arquivo CodeAnalysis/Token.cs:

public class Lexer  
{ 
    ...
    private Token ExtractKeyword()  
    {  
        ... 
        if (identifier.Value == Token.WHILE)  
            return Token.While(position);  

        return Token.Identifier(position, identifier.Value);  
    } 
    ...  
}

É isso. O processo é simples, já que fizemos toda a estrutura de código anteriormente para suportar tokens como if, else, etc.

Primeira parte foi para o done!

Arquivo CodeAnalysis/SyntaxParser.cs:

No post passado, na parte 5, ao implementarmos suporte a if e else, adicionamos dois métodos importantes que vão ser reutilizados na implementação do while: ParseBlock e SkipBlockUntil.

Com isso, a implementação do while acaba sendo razoavelmente simples, até porque a estrutura de execução não difere muito da estrutura de suporte ao if.

Uma coisa que mostrei ao vivo e acho que é bem legal para “visualizar” o fluxo de validação e evaluate das expressões, foi apresentar o código-fonte e demonstrar como o ponteiro “passeia” entre os tokens, além de destacar o que é uma expressão (algo que vai retornar um valor booleano) e o que é o bloco de execução (trechos de código que serão repetidos n vezes dependendo do resultado computado da expressão).

Vejamos o código:

int i = 1
while i <= 10
    print(i)
    i = i + 1
end

Quando penso na implementação dos evaluates imagino uma sequência de tokens demarcando o que são expressões e o que são blocos de execução. Dessa forma, fica fácil para eu identificar como vai ficar a estrutura de implementação. Saca só:

int i = 1 while [i <= 10] {print(i) i = i + 1} end
          ^....................................^

O que temos acima é uma representação linear onde o ^ é um ponteiro que vai avançando entre os tokens até encontrar o token delimitador final. Isso acontece do primeiro ao último token. Aqui, foquei somente no que interessa no momento.

Não sei se isso ficou claro no post anterior, mas esses blocos de execução precisam ter um token de abertura e um de fechamento. Um par que me indica onde começa e onde termina o bloco. if e end, while e end e num futuro for e end, são blocos com essas características.

Dessa forma, é possível visualizar a expressão (tudo que está entre colchetes), o bloco de execução (tudo que está entre chaves) e onde começa e termina nosso fluxo.

Isso é importante já que temos dois processos fundamentais: EvaluateExpression e EvaluateToken.
Lembrando que o último processo da cadeia executada pelo EvaluateExpression é a invocação do EvaluateToken, porém, em muitos casos, podemos chamar diretamente o EvaluateToken.

Por isso essa separação: preciso ter total noção de quando invocar um e quando invocar os outros.

public class SyntaxParser  
{  
    ...
    private Identifier EvaluateToken()  
        => CurrentToken.Type switch  
        {  
            ...
            TokenType.While => EvaluateWhile(),  
            ...  
        };

    private Identifier EvaluateWhile()  
    {  
        NextIfTokenIs(TokenType.While);  
        var whilePosition = _currentPosition;  

        while (true)  
        {  
            var condition = EvaluateExpression();  
            if (condition.ToBool())  
            {  
                ParseBlock(TokenType.End);  
                _currentPosition = whilePosition;  
            }  
            else  
            {  
                SkipBlockUntil(TokenType.End);  
                break;  
            } 
        }  
        NextIfTokenIs(TokenType.End);  
        return Identifier.None;  
    }

    ...  
}

EvaluateWhile! Sim, é simples.

E não, não tem como remover aquele while true. Segue o jogo…

Começamos validando a presença do token while e armazenamos a posição atual dele para permitir a repetição do bloco. Lembra do ponteiro ^? Então… ao chegar no fim do bloco, é necessário voltar para o início, com isso a variável whilePosition armazena esse valor que será posteriormente setado na variável global _currentPosition e o processo reinicia do ponto de partida correto.

A cada iteração é necessário processar a expressão (EvaluateExpression) e validar se o resultado é um valor booleano. Se for booleano e for true executa o bloco associado (ParseBlock) e retorna à posição inicial para reavaliar a condição.

Caso a condição seja falsa, o método avança até o token End, encerrando o laço.

E é aqui que temos uma pegadinha marota: identificar o verdadeiro end final. Aquele que determina o fim do bloco, já que podemos ter um while dentro de outro que está dentro de um if que por sua vez tem um else. Algo como:

Ou ainda:

int i = 1
while i <= 10
    int j = 1
    while  j <= 10
        print(i + "x" + j + "=" + i * j)
        j = j + 1

        if i % 2 == 0
            print(i + " é par")
        else
            print(i + " é ímpar")
        end
    end
    print("=========")
    i = i + 1
end

No exemplo acima, temos 3 tokens do tipo end, mas qual deles é, de fato, o que finaliza o bloco do while? E note que existe um while dentro de um while.

É aí que entra o famigerado SkipBlockUntil:

private void SkipBlockUntil(params TokenType[] delimiters)  
{  
    var nestedCount = 0;  
    while (CurrentToken.Type != TokenType.EndOfFile)  
    {  
        if (delimiters.Contains(CurrentToken.Type) && nestedCount == 0)  
            return;  

        if (CurrentToken.Type is TokenType.If or TokenType.While)  
            nestedCount++;  
        else if (CurrentToken.Type == TokenType.End && nestedCount > 0)  
            nestedCount--;  

        _currentPosition++;  
    }
}

Esse método avança a posição atual dos tokens até encontrar um dos delimitadores informados, ignorando o conteúdo do bloco.
No caso do processamento do if informamos TokenType.Else e TokenType.End. O else é um delimitador do if também!
Já no caso do while informamos somente oTokenType.End.

Encontrou algum desses tokens, pára o processo!

Tudo isso é feito considerando blocos aninhados, incrementando um contador ao encontrar novos if ou while e decrementando ao encontrar end, garantindo que somente o bloco correto seja pulado.

Feito isso, temos o while implementado, executando corretamente o bloco de código e saindo graciosamente quando deve sair.

Simples e funcional.

O fato de ter implementado suporte a if e else fez com que criássemos métodos que serão reaproveitados em vários outros cenários.

Para o propósito desse compilador, arrisco a dizer que a infraestrutura de código está praticamente completa, sendo necessário somente adicionar suporte a alguns novos tokens, como o for e um para identificar métodos, algo que ainda não defini como será.

O próximo post promete!

Como foi razoavelmente simples essa implementação, resolvi fazer uma correção na identificação do tipo numérico (double e int), reorganizar os testes unitários, incluir vários exemplos de código (verificar números primos e palíndromos, converter decimal para binário, inverter string, Célsius para Fahrenheit, etc.) além de dar um tapinha na nossa “IDE”.

Aliás, ao reorganizar os testes, eu refiz boa parte deles para poder cobrir o máximo de cenários possíveis.

Hoje são 345 testes, que rodam em aproximadamente 1 segundo(!), dando uma cobertura total de aproximadamente 92%:

O Pug está saindo da casinha \o/

E assim chegamos ao fim da parte 6.
Espero que tenham curtido a live e o post!

Código-Fonte: https://github.com/angelobelchior/Pug.Compiler/tree/parte6

É isso.

Muito obrigado e até a próxima.

Criando um compilador em csharp: Parte 5

Angelo Belchior — Wed, 16 Jul 2025 22:00:00 +0000

Caramba… chegamos à parte 5! Quem diria…

Aliás, a ideia de primeiro escrever o código e depois escrever o post facilitou muito a minha vida. Faço um diff entre as branchs e consigo saber exatamente quais foram as mudanças de um post para o outro. Simples assim! Vivendo, codando e aprendendo.

Bom, no post anterior adicionamos suporte a operadores lógicos &&, ||, ==, >=, <=, etc., além de mapear os tokens if, else, e end para podermos adicionar suporte a estrutura condicional.
Basicamente, hoje vamos adicionar suporte a uma estrutura de código como esta:

if idade >= 18
   print("acesso liberado")
else
   print("acesso negado")
end

O token then foi mapeado, mas eu resolvi removê-lo. Preferi deixar a linguagem mais enxuta...

Nós já mapeamos os tokens necessários no post anterior, agora precisamos fazer a análise sintática deles, além do evaluate.

A implementação em si não foi tão complexa, o que me causou estranheza, mas basicamente vamos criar um método EvaluateIf e fazer toda a mágica nele.

Arquivo CodeAnalysis/SyntaxParser.cs:

Primeiro vamos alterar o método EvaluateToken para invocar o evaluate do If:

private Identifier EvaluateToken()  
  => CurrentToken.Type switch  
  {  
      TokenType.If => EvaluateIf(),  
      ...
 };

Em seguida criamos o método EvaluateIf:

private Identifier EvaluateIf()
{
    NextIfTokenIs(TokenType.If);
    var condition = EvaluateExpression();

    if (condition.ToBool())
        ParseBlock(TokenType.Else, TokenType.End);
    else
        SkipBlockUntil(TokenType.Else, TokenType.End);

    if (CurrentToken.Type == TokenType.Else)
    {
        NextIfTokenIs(TokenType.Else);
        if (!condition.ToBool())
            ParseBlock(TokenType.End);
        else
            SkipBlockUntil(TokenType.End);
    }

    NextIfTokenIs(TokenType.End);
    return condition;
}

private void ParseBlock(params TokenType[] delimiters)
{
    while (!delimiters.Contains(CurrentToken.Type) && CurrentToken.Type != TokenType.EndOfFile)
        EvaluateToken();
}

private void SkipBlockUntil(params TokenType[] delimiters)
{
    var nestedIfCount = 0;
    while (CurrentToken.Type != TokenType.EndOfFile)
    {
        if (delimiters.Contains(CurrentToken.Type) && nestedIfCount == 0)
            return;

        if (CurrentToken.Type == TokenType.If)
            nestedIfCount++;
        else if (CurrentToken.Type == TokenType.End && nestedIfCount > 0)
            nestedIfCount--;

        _currentPosition++;
    }
}

Só isso… que moleza, hein... Nem suei!

Basicamente procuramos pelo token If. Ao encontrá-lo, avançamos e fazemos o parse da expressão seguinte. Essa expressão precisa ser uma condição booleana, logo, seu resultado é convertido para true ou false. Caso não seja possível essa conversão, obteremos erro…

Se essa expressão retornar um true, iniciamos o processamento do bloco do if. Para isso, invocamos o método ParseBlock que vai processando todos os tokens que não sejam tokens de finalização de bloco, no caso TokenType.Else e TokenType.End.

Acredito que o método ParseBlock seja autoexplicativo: vai avançando e dando evaluate nos tokens até que encontre um token de finalização.

Eu não sei se valeu a pena isolar esse processo em um método, mas acho que ficou mais fácil para explicar...

Caso a condição seja false, é necessário "pular" para o token de finalização, que pode ser um else ou um end. Para isso temos o método SkipBlockUntil.

Esse método é interessante. Imagine que podemos ter inúmeros if dentro de else ou até mesmo de um if. Por exemplo:

int idade = 18
string nome = "Angelo"
if idade >= 18
    print("acesso permitido")
else
    if nome == "Angelo"
        print("acesso em avaliação")
    else
        print("acesso negado")
    end
end
print("Fim do programa")

O código acima é bonitinho, mas podemos ter o tenebroso Código Hadouken:

Com isso, o método SkipBlockUntil precisa identificar quando um bloco if ou else terminam. Porém, como podemos ter um bloco dentro do outro que está em um terceiro bloco, precisamos identificar a “profundidade” do bloco para sabermos se chegamos ao final ou ainda devemos avançar entre os tokens.

Esse processo só termina quando encontra um token de finalização no mesmo nível de aninhamento (ou seja, quando nestedIfCount é zero), garantindo que blocos internos não causem término prematuro da busca. Isso força o processo a pular partes do código que não devem ser executadas.

Acredito que exista uma forma de simplificar esse algorítimo, mas não estou preocupado com isso. Mas é certo que tem como medir essa profundidade de forma mais performática e/ou inteligente.

Funcionou? Sim. Segue o baile.

O processo segue verificando se, após encontrar um if e fazer o seu processo, existe um else.
Caso exista e a condição force a execução do bloco do else (condition é false), o método ParseBlock é invocado e o fluxo segue da mesma forma apresentada acima.

E por fim, fechamos o processo validando a presença do end no final do bloco da estrutura condicional.

Esse fluxo não foi tão complexo e abre as portas para a implementação da estrutura de looping while. Mas isso fica para o próximo post.

Como finalizei essa implementação até que rápido, resolvi incluir suporte ao operador % que obtém o resto da divisão.

Essa implementação é bem simples também, já que os operadores matemáticos já estão implementados.

Começamos adicionando o token Remainder. Sim, aquele símbolo de percentual é chamado de Remainder. Eu também não sabia…

Arquivo CodeAnalysis/Token.cs:

...
public const char REMAINDER = '%';
...

public static Token Remainder(int position)  
  => new(TokenType.Remainder, REMAINDER, position);
...

Token criado, vamos extraí-lo:

Arquivo CodeAnalysis/Lexer.cs:

private Token ExtractSymbols()
{
    ...
    var singleCharTokenFactory = new Dictionary<char, Func<int, Token>>
    {
        ...
        [Token.REMAINDER] = Token.Remainder,
        ...
    };

    if (singleCharTokenFactory.TryGetValue(_currentChar, out var tokenFactory))  
    {  
      Next();  
      return tokenFactory(position);  
    }
    ...
}

No método ExtractSymbols, incluímos o novo operador para ser encontrado no processo de extração de símbolos. Esse método ficou bem interessante já que é muito simples adicionar qualquer novo operador. Se num futuro eu quiser adicionar o operador ^ para efetuar o cálculo de potência, moleza.

Feito isso, se você já acompanha a série, sabe que agora precisamos fazer o evaluate dessa operação.

Arquivo CodeAnalysis/SyntaxParser.cs:

O método EvaluatePlusOrMinus mudou de nome para EvaluatePlusOrMinusOrRemainder. E como o próprio nome diz, agora vamos verificar % além do + e -.

private Identifier EvaluatePlusOrMinusOrRemainder()  
{  
    var left = EvaluateMultiplyOrDivide();  
    while (CurrentToken.Type is TokenType.Plus or TokenType.Minus or TokenType.Remainder)  
    {  
        var op = NextIfTokenIs(CurrentToken.Type);  
        var right = EvaluateMultiplyOrDivide();  
        left = EvaluateOperation(left, right, op);  
    }  
    return left;  
}

Essa alteração foi feita nesse método já que o operador % tem a mesma prioridade da soma e da subtração.

Em seguida, executamos a operação. E para isso precisei alterar o método EvaluateNumberOperation:

private static Identifier EvaluateNumberOperation(Identifier left, Identifier right, Token @operator)  
{  
    var value = @operator.Type switch  
    {  
        ...
        TokenType.Remainder => left.ToDouble() % right.ToDouble(),  
        _ => throw new Exception($"Unexpected token: {@operator.Type}")  
    };  
    return new Identifier(DataTypes.Double, value);  
}

Basicamente é isso! Simples assim.

E com essas novas features podemos escrever o seguinte código na nossa linda linguagem de programação:

int numero = 10
if numero % 2 == 0
    print("Número " + numero + " é par")
else
    print("Número " + numero + " é ímpar")
end

Além disso, nessa branch foi ajustado o código para que nomes de variáveis permitirem _ e números no meio da palavra: exemplo: int var_1 = 4.

E é claro que nosso Pug.Editor não ficou de fora e recebeu boas atualizações:

Ajustes no Layout
Inclusão de um combo com samples de código
Ao clicar em um token (no painel a esquerda) é possível visualizar no editor o código-fonte que gerou aquele token
Caso ocorra algum erro de compilação, o editor irá destacar a linha do erro

Gravei um vídeo mostrando por cima como o nosso editor ficou:

Curtiu???

Sensacional! A cada nova feature eu me empolgo mais e mais.

Na parte 6 vamos adicionar suporte a estrutura de looping: while!!!

O Pug ta saindo da casinha!

Antes de terminar o post, gostaria de fazer uma menção honrosa!

Dando uma zapeada na internet, achei esses dois posts onde o grande Konstanty Koszewski implementa um interpretador BASIC usando Ruby. SENSACIONAL! Ótima fonte de estudos!

Destaque para o quão bonita é a linguagem Ruby…

Parte 1: https://medium.com/@konstanty.koszewski_35161/basic-interpreter-in-ruby-from-scratch-part-1-c68bbf365ab0

Parte 2: https://medium.com/@konstanty.koszewski_35161/basic-interpreter-in-ruby-from-scratch-part-2-d55a778af326

É muito louco pensar em escrever um compilador/interpretador. Não é nada trivial, logo, é difícil achar conteúdos sobre o tema que não sejam artigos científicos/acadêmicos. Eu sempre pesquiso sobre compiladores e o que encontro geralmente são estudos densos e tensos. Saber que existem conteúdos sobre o tema acessíveis, numa linguagem de fácil entendimento é realmente maravilhoso.

E fechamos aqui mais um post.

Código-fonte do post: https://github.com/angelobelchior/Pug.Compiler/tree/parte5

Muito obrigado e até a próxima.

Criando um compilador em csharp: Parte 4

Angelo Belchior — Wed, 25 Jun 2025 22:05:00 +0000

Caramba, chegamos à quarta parte!

Dessa vez, mudei um pouco a dinâmica de escrita. Antes eu ia codando e escrevendo algumas coisas que depois eu organizava no post. Porém, pela complexidade da nova feature não consegui codar e escrever, sendo assim, nesse momento tenho todo o código pronto. Gostei dessa dinâmica. Talvez eu continue dessa forma, foi muito mais produtivo, a meu ver.

Certo. E o que temos para hoje?

Bem, na parte 3 implementamos suporte a variáveis int, double, string e bool além de adicionar suporte à concatenação de strings e cálculos matemáticos entre números.

Porém, nessa quarta parte, decidi explorar mais os operadores lógicos e de comparação.

É importante destacar que vamos mapear os tokens if, then, else e end, mas a implementação da estrutura condicional ficará para o próximo post.

Aliás, um ponto muito importante. Para poder efetuar essa implementação, dediquei um bom tempo lendo um livro simplesmente sensacional: Crafting Interpreters.

Que livro foda! Escrito pelo grande Robert Nystrom, esse livro aborda a implementação de um compilador de maneira simples e direta. O Robert usa Java, facilitando muito a leitura do código. Além disso, ele aborda os tópicos de forma muito didática. Gostei bastante. É um baita guia prático para criar sua própria linguagem de programação. Que é o nosso caso…

Esse livro foi indicação do grande mestre Pedro Jesus. Lembrando sempre que In Pedro Jesus we trust.

Seguimos…

Se você está nos acompanhando desde a primeira parte já sabe que o início da implementação de novos tokens começa pela classe Token mapeando as novas palavras reservadas e novos símbolos e, em seguida, usamos a classe Lexer para efetuar a extração dos mesmos.

Nessa feature, vamos adicionar suporte a operadores lógicos e para isso precisamos mapear os tokens >, <, !, & e |:

Arquivo CodeAnalysis/Token.cs

public const char GREATER = '>';
public const char LESS = '<';
public const char NOT = '!';
public const char AMPERSAND = '&';
public const char PIPE = '|';

Criamos essas novas constantes além dos métodos de apoio:

public static Token Greater(int position)
    => new(TokenType.Greater, GREATER, position);

public static Token Less(int position)
    => new(TokenType.Less, LESS, position);

public static Token GreaterOrEqual(int position)
    => new(TokenType.GreaterOrEqual, GREATER + EQUAL.ToString(), position);

public static Token LessOrEqual(int position)
    => new(TokenType.LessOrEqual, LESS + EQUAL.ToString(), position);

public static Token Equal(int position)
    => new(TokenType.Equal, EQUAL + EQUAL.ToString(), position);

public static Token NotEqual(int position)
    => new(TokenType.NotEqual, NOT + EQUAL.ToString(), position);

public static Token And(int position)
    => new(TokenType.And, AMPERSAND + AMPERSAND.ToString(), position);

public static Token Or(int position)
    => new(TokenType.Or, PIPE + PIPE.ToString(), position);

Nenhuma novidade até aqui.

Além de operadores lógicos, começo a mapear os tokens necessários para termos uma estrutura de if/else.

Na nossa linguagem de programação, a forma de uso dessas instruções será feita da seguinte forma:

if idade >= 18 then
   print("acesso liberado")
else
    print("acesso negado")
end

Ruby like pero no mucho… Na verdade, tem meio que uma pegada de VB6… (Lembrando que esse trecho de código ainda não funciona…)

Para isso, novos tokens precisam ser mapeados. O processo é o mesmo:

public const string IF = "if";
public const string THEN = "then";
public const string ELSE = "else";
public const string END = "end";

...

public static Token If(int position)
    => new(TokenType.If, IF, position);

public static Token Then(int position)
    => new(TokenType.Then, THEN, position);

public static Token Else(int position)
    => new(TokenType.Else, ELSE, position);

public static Token End(int position)
    => new(TokenType.End, END, position);

Certo, agora vamos incluir a extração desses tokens. O processo é idêntico aos que já fizemos anteriormente, logo, vou passar somente por alguns métodos.

Arquivo CodeAnalysis/Lexer.cs

Basicamente, alteramos dois métodos: ExtractKeyword e ExtractSymbols:

private Token ExtractKeyword()
{
    var position = _currentPosition;
    var identifier = ExtractIdentifier();

    if (Identifier.ContainsDataType(identifier.Value))
        return Token.DataType(position, identifier.Value);
    if (BuiltInFunctions.Contains(identifier.Value))
        return Token.Function(position, identifier.Value);
    if (identifier.Value is Token.TRUE or Token.FALSE)
        return Token.Bool(position, identifier.Value);

    if (identifier.Value == Token.IF)
        return Token.If(position);

    if (identifier.Value == Token.THEN)
        return Token.Then(position);

    if (identifier.Value == Token.ELSE)
        return Token.Else(position);

    if (identifier.Value == Token.END)
        return Token.End(position);

    return Token.Identifier(position, identifier.Value);
}

O ExtractKeyword não tem segredo: procuramos por textos equivalentes ao if, else, then e end. Simples assim.

Já o ExtractSymbols…

private Token ExtractSymbols()
{
    var position = _currentPosition;

    var doubleCharToken = (_currentChar, Peek()) switch
    {
        (Token.AMPERSAND, Token.AMPERSAND) => Token.And(position),
        (Token.PIPE, Token.PIPE) => Token.Or(position),
        (Token.EQUAL, Token.EQUAL) => Token.Equal(position),
        (Token.NOT, Token.EQUAL) => Token.NotEqual(position),
        (Token.GREATER, Token.EQUAL) => Token.GreaterOrEqual(position),
        (Token.LESS, Token.EQUAL) => Token.LessOrEqual(position),
        _ => null
    };
    if (doubleCharToken is not null)
    {        
        Next(2);
        return doubleCharToken;
    }
    var singleCharTokenFactory = new Dictionary<char, Func<int, Token>>
    {        
        [Token.PLUS] = Token.Plus,
        [Token.MINUS] = Token.Minus,
        [Token.MULTIPLY] = Token.Multiply,
        [Token.DIVIDER] = Token.Divide,
        [Token.OPEN_PARENTHESIS] = Token.OpenParenthesis,
        [Token.CLOSE_PARENTHESIS] = Token.CloseParenthesis,
        [Token.COMMA] = Token.Comma,
        [Token.GREATER] = Token.Greater,
        [Token.LESS] = Token.Less
    };

    if (singleCharTokenFactory.TryGetValue(_currentChar, out var tokenFactory))
    {        
        Next();
        return tokenFactory(position);
    }
    throw new Exception($"Unexpected character {_currentChar}");
}

Nesse caso, inicio tentando identificar tokens com dois caracteres. Esse switch usa o _currentChare o método Peek para identificar operadores lógicos (&&, ||, ==, etc.).

Caso não existam operadores lógicos, o fluxo segue o mesmo, obtendo símbolos como (, ), +, etc.

Nesse momento, já conseguimos extrair os novos tokens.

Agora vem a parte mais “cabulosa”: SyntaxParser…

Pega um café…

Arquivo CodeAnalysis/SyntaxParser.cs

public class SyntaxParser(Dictionary<string, Identifier> identifiers, List<Token> tokens)
{
    // ...

    // public List<Identifier> Evaluate() ...

    private Identifier EvaluateExpression()
        => EvaluateLogicalOr();

    private Identifier EvaluateLogicalOr()
    {
        var left = EvaluateLogicalAnd();
        if (CurrentToken.Type != TokenType.Or) return left;
        var or = NextIfTokenIs(TokenType.Or);
        var right = EvaluateLogicalAnd();
        left = EvaluateLogicalOperation(left, right, or);
        return left;
    }

    private Identifier EvaluateLogicalAnd()
    {
        var left = EvaluateComparison();
        if (CurrentToken.Type != TokenType.And) return left;
        var and = NextIfTokenIs(TokenType.And);
        var right = EvaluateComparison();
        left = EvaluateLogicalOperation(left, right, and);
        return left;
    }

    private Identifier EvaluateComparison()
    {
        var left = EvaluatePlusOrMinus();
        if (!Token.IsMathOperatorType(CurrentToken.Type)) return left;
        var @operator = NextIfTokenIs(CurrentToken.Type);
        var right = EvaluatePlusOrMinus();
        left = EvaluateComparison(left, right, @operator);
        return left;
    }

    private Identifier EvaluatePlusOrMinus()  
    {  
        var left = EvaluateMultiplyOrDivide();  
        while (CurrentToken.Type is TokenType.Plus or TokenType.Minus)  
        {  
            var op = NextIfTokenIs(CurrentToken.Type);  
            var right = EvaluateMultiplyOrDivide();  
            left = EvaluateOperation(left, right, op);  
        }  
        return left;  
    }

    private Identifier EvaluateMultiplyOrDivide()
    {
        var left = EvaluateToken();
        while (CurrentToken.Type is TokenType.Multiply or TokenType.Divide)
        {
            var op = NextIfTokenIs(CurrentToken.Type);
            var right = EvaluateToken();
            left = EvaluateOperation(left, right, op);
        }

        return left;
    }

    // Métodos evaluates...

    private static Identifier EvaluateComparison(Identifier left, Identifier right, Token @operator)
    {
        const double epsilon = 1e-6;

        Identifier.EnsureSameTypes(left, right, @operator);

        var result = @operator.Type switch
        {
            TokenType.Equal => Equal(),
            TokenType.NotEqual => !Equal(),
            TokenType.Greater => Greater(),
            TokenType.GreaterOrEqual => Greater() || Equal(),
            TokenType.Less => Less(),
            TokenType.LessOrEqual => Less() || Equal(),
            _ => throw new Exception($"Unexpected comparison operator: {@operator.Type}")
        };

        return new Identifier(DataTypes.Bool, result);

        bool Equal()
            => (left.DataType, right.DataType) switch
            {
                (DataTypes.Double, _) or (_, DataTypes.Double) =>
                    Math.Abs(left.ToDouble() - right.ToDouble()) < epsilon,

                (DataTypes.Int, DataTypes.Int) =>
                    left.ToInt() == right.ToInt(),

                (DataTypes.Bool, DataTypes.Bool) =>
                    left.ToBool() == right.ToBool(),

                (DataTypes.String, DataTypes.String) =>
                    left.ToString() == right.ToString(),

                _ => ThrowException()
            };

        bool Greater()
            => (left.DataType, right.DataType) switch
            {
                (DataTypes.Double, _) or (_, DataTypes.Double) =>
                    left.ToDouble() > right.ToDouble(),

                (DataTypes.Int, DataTypes.Int) =>
                    left.ToInt() > right.ToInt(),

                _ => ThrowException()
            };

        bool Less()
            => (left.DataType, right.DataType) switch
            {
                (DataTypes.Double, _) or (_, DataTypes.Double) =>
                    left.ToDouble() < right.ToDouble(),

                (DataTypes.Int, DataTypes.Int) =>
                    left.ToInt() < right.ToInt(),

                _ => ThrowException()
            };

        bool ThrowException()
            => throw new Exception($"Cannot compare types: {left.DataType} and {right.DataType}");
    }

    private static Identifier EvaluateLogicalOperation(Identifier left, Identifier right, Token @operator)
    {
        if (left.DataType != DataTypes.Bool || right.DataType != DataTypes.Bool)
            throw new Exception($"Logical operator {@operator.Type} can only be applied to bool types");

        var result = @operator.Type switch
        {
            TokenType.And => left.ToBool() && right.ToBool(),
            TokenType.Or => left.ToBool() || right.ToBool(),
            _ => throw new Exception($"Unexpected logical operator: {@operator.Type}")
        };

        return new Identifier(DataTypes.Bool, result);
    }

    // private Token Peek() ...

    // private Token NextIfTokenIs(TokenType type) ...
}

Dessa vez, iniciamos o processo validando os operadores lógicos || e &&. E aqui temos uma coisa bem interessante que eu só consegui destravar lendo e relendo a sessão de operadores lógicos do glorioso livro Crafting Interpreters: avaliar ambos os lados da operação priorizando o operador &&.

Dessa forma, mantemos o fluxo parecido com a execução prioritária de operações como * e / além, claro, da prioridade máxima dos ().

E quando eu falar lados, me refiro ao que está à direita e à esquerda do operador. Por exemplo: 1 == 2. Nesse caso, temos o 1 sendo um Identifier numérico que vai ser chamado de left e o 2 que também é um Identifier numérico, mas que será tratado como right. Temos ainda expressões do tipo (1 == 2) || (2 < 4). Nesse caso, teremos o evaluatedo que está entre parênteses, onde temos uma expressão à esquerda e outra à direita. Por fim, o resultado é uma nova expressão, false || true. Esquerda e Direita, para os íntimos. E não, não me refiro à política…

E por qual motivo começamos com o ||? Simples! Pela ordem de prioridade:

EvaluateLogicalOr
└── EvaluateLogicalAnd
    └── EvaluateComparison
        └── EvaluatePlusOrMinus
            └── EvaluateMultiplyOrDivide
                └── EvaluateToken

Basicamente, temos um fluxo encadeado de Evaluates que, antes de ser executado, cada item do fluxo verifica a existência de um próximo fluxo mais prioritário.

Com isso, garantimos a execução evaluate da expressão, seguindo a ordem correta. Por fim, ao chegar no EvaluateToken, todo o processo, que já foi descrito e explicado exaustivamente nos posts anteriores, é efetuado normalmente, fazendo a execução baseada no tipo do token em questão.

Essas regrinhas são chatas demais e o que me ajudou muito foi quebrar cada parte num bloco de código. A reorganização feita no post anterior foi fundamental. Cada coisa está em seu devido lugar, e agora fica fácil visualizar o fluxo.

Aliás, que Odin abençoe o Github Copilot. Pedi a ele para “desenhar o fluxo de execução da expressão
1 == 2 || 4 == pow(2) e ele me retornou essa belezura aqui:

EvaluateLogicalOr
 ├─ EvaluateLogicalAnd (1 == 2)
 │    └─ EvaluateComparison → false
 └─ Como ainda existe um operador lógico, no caso o ||, avalia o lado direito:
     └─ EvaluateLogicalAnd (4 == pow(2))
          └─ EvaluateComparison
               ├─ EvaluateToken (4)
               └─ EvaluateFunction (pow(2)) → 4
               └─ Compara 4 == 4 → true

A primeira parte do processo gerou o seguinte resultado: false || true. E, como estamos em um fluxo recursivo, o processo continua:

EvaluateLogicalOr
 ├─ EvaluateLogicalAnd (false)
 │    └─ EvaluateComparison → false
 └─ Como ainda existe um operador lógico, no caso o ||, avalia o lado direito:
     └─ EvaluateLogicalAnd (true)
          └─ EvaluateComparison
               └─ EvaluateComparison → false
     └─ EvaluateLogicalOperation(left: false, rightt: right, operator: or)
          └─ true

Vocês não têm noção da minha felicidade ao descobrir que posso, de fato, visualizar o fluxo de execução. Depois que descobri isso, minha vida escrevendo esse compilador realmente mudou.

O Immo Landwerth quando criou o minsk fez algo parecido, onde ele imprimia a estrutura da árvore. Eu até pensei em fazer isso, mas por algum motivo passou batido.

Certo. Acredito que o fluxo de execução tenha ficado claro. Aliás, tem vezes em que acho que a pessoa que está lendo os posts, está com o código-fonte debugando, logo assumo que, com a explicação dada, ela consiga se encontrar nas entranhas dos códigos. E tem vezes em que acho que ninguém lê realmente os posts… Faz parte, segue o jogo.

Dentro desse fluxo, novos métodos de evaluateforam criados. Como o EvaluateLogicalOperation que valida se a operação é um || ou && e faz a comparação devida, retornando um Identifier do tipo Bool com o resultado executado.

Já o EvaluateComparison efetua comparação avaliando operadores como ==, !=, >, >=, <, <=. Aqui não tem segredo nenhum! Dado o identificador da esquerda e o da direita, são efetuadas as operações. É claro que o tipo de dado é considerado nesse caso, sendo assim, não é possível fazer algo como bool resultado = "Abacate" > 3.14.

Aliás, para facilitar a validação dos tipos de dados dos identificadores da esquerda e da direita, incluí na classe Identifier os seguintes métodos:

Arquivo Runtime/Identifier.cs

public static void EnsureSameTypes(Identifier left, Identifier right, Token @operator)  
{  
  if (AllAreNumberTypes(left.DataType, right.DataType))  
  return;  

  if (left.DataType != right.DataType)  
  throw new Exception(  
  $"Cannot apply {@operator.Type} operator to different types: {left.DataType} and {right.DataType}");  
}  

public static bool AllAreNumberTypes(params DataTypes[] types)  
  => types.All(type => type is DataTypes.Double or DataTypes.Int);

Basicamente, eu verifico se os tipos são iguais validando seu DataType. Isso ajuda a identificar operações que não podem ser feitas por tipos diferentes. Lembrando que temos casos como, por exemplo, string texto = 3 * "A"onde teremos o retorno AAA. Mas são exceções.

Outra coisa interessante é o fato de tratar como número, tipos de dados Int e Double. Assim, garanto operações matemáticas entre eles, priorizando o resultado como Double.

E para finalizar, os métodos EvaluateMultiplyOrDivide, EvaluatePlusOrMinus, EvaluateComparison, EvaluateLogicalAnd, EvaluateLogicalOr fazem parte do fluxo de execução explicado acima: verifica o operador em questão, obtém o identificador da esquerda e o da direita e invoca o evaluate correspondente, ou comparação, ou operação. Comparação, nada mais é do que ==, !=, >=, etc. e a operação se refere aos famigerados *, /, +, etc.

Agora podemos efetuar vários testes usando operadores lógicos:

> bool valor = 2 == 2 || 3 == 4
True
> bool valor = 1 == 2 && 3 == 4
False
> bool valor = (5 > 1) && (10 > 2)
True
> bool valor = (5 < 1) || (10 < 2)
False
> bool valor = (pow(2) == 4) && (1 < 2)
True
> bool valor = (pow(2) != 4) && (1 > 2)
False
> bool valor = (3 != 4) || (2 == 2)
True
> bool valor = (3 == 4) || (2 != 2)
False

Maravilha! Tudo nos conformes!

Deu trabalho, mas saiu. E ainda estamos no quarto post. Tem muita coisa legal para ser construída.

Espero que você, meu caro leitor, minha cara leitora, esteja curtindo essa série de posts.

Porém, antes de me despedir…

There's one more thing!

Como a cada post estamos evoluindo mais e mais o nosso compilador, é mais do que necessário que tenhamos formas de testar o resultado implementado. Hoje, existem mais de 200 testes unitários que ajudam a garantir que nada foi quebrado a cada linha de código adicionada.

Além disso, temos o nosso querido REPL que facilita a validação de expressões simples, como as que apresentamos acima.

Mas, de agora em diante, nós vamos precisar de algo mais robusto, já que temos a pretensão de escrever códigos como:

int idade = 30
if idade > 18 then
    print("Acesso liberado")
else
    print("Apenas maiores de 18 anos podem acessar..")
end

Usar o REPL é inviável, já que ele executa uma linha por vez. O ideal é que a gente teste utilizando um editor de código. E se for possível ter suporte à coloração e formatação, melhor ainda.

Sendo assim, inclui um novo projeto dentro da nossa solution chamado Pug.Compiler.Editor!

Isso mesmo! Agora temos um editor de código para nos ajudar.

Basicamente, temos um VS Code só para o nosso projeto. E isso é feito utilizando o Monaco Editor, mesmo motor usado pelo VS Code!

O mais maravilhoso é que ele é totalmente extensível, sendo assim, consegui configurá-lo para identificar as palavras reservadas da nossa linguagem.

Olha que coisa linda:

E enfim, encerramos o quarto post. Mais uma feature entregue. Aliás, duas. Operadores lógicos e o Editor.

O próximo post promete.

Código-fonte da parte 4: https://github.com/angelobelchior/Pug.Compiler/tree/parte4

Forte abraço!

Até a próxima!

Criando um compilador em csharp: Parte 3

Angelo Belchior — Mon, 09 Jun 2025 22:30:00 +0000

Para quem estava duvidando, chegamos ao terceiro post! E nele vamos adicionar o suporte a declaração de variáveis.

Para atender essa nova feature foram necessárias algumas alterações e, com isso, precisei dar uma reorganizada no código.

Mas não se preocupe, nós vamos passar por cada arquivo, sempre detalhadamente, cobrindo todos os pontos importantes.

O mais interessante é que, de agora em diante, vamos começar a ter um esboço de como ficará a nossa linguagem de programação. Aliás, existem Programming language designers — uma pessoa que pensa em como deveria ser uma linguagem de programação no que tange à sua escrita. O glorioso Anders Hejlsberg pai do csharp e de outras linguagens, é um bom exemplo disso. Outra figura notória é o grande Eric Lippert cujo blog é simplesmente sensacional. Mais do que recomendo.

Pois bem! Seguindo nessa linha, minha ideia é criar algo simples, com poucos tokens. Por exemplo, para declarar uma variável na nossa linguagem de programação, vai ser bem simples:

int idade
string nome = "Angelo"
bool sucesso = true double altura = 1.4
int valor = idade * pow(altura)

Sem ;, sem se preocupar em quebrar linha, tabs ou espaços.
Podendo ou não informar um valor logo na declaração. Coisa linda…

Mas a ideia nessa série de posts é sempre fazermos o que for mais simples possível e incrementando aos poucos.

Sendo assim, para essa primeira versão teremos os tipos int, double, string e bool.

O tipo bool vai ser o menos explorado hoje, já que ele vai ser muito importante quando adicionarmos suporte a operadores lógicos como ==, !=, >, >=, <, <=, && e ||. Essas implementações estarão no próximo post.

Além disso, nessa parte 3 vamos incluir alguns outros métodos internos, como o print, por exemplo. Com isso, vamos poder brincar com string e concatenação.

Chega de papo, vamos ao que viemos.

Reorganização do código

Mantemos a mesma ideia, porém com uma estrutura mais organizada. Extraímos códigos de Runtime como a execução de métodos internos para um novo namespace chamado, vejam só… Runtime.

A parte de análise de código (CodeAnalysis) continua com a mesma estrutura, porém as classes Lexer e SyntaxParser foram refatoradas. Isso foi necessário já que para incluir mais tokens precisamos criar mais códigos de extração, além de mais validações estruturais das expressões. Porém, nada que não esteja nas ideias apresentadas na parte 1 e na parte 2.

Aliás, na parte 2, eu disse que “depois que entendemos e criamos o lexer e o parser, evoluí-los é algo bem mais tranquilo”. Não sei o que deu em mim para afirmar isso…

Outro ponto muito importante. Temos testes unitários. Ok, não temos uma cobertura gigantesca, mas vou evoluindo isso com o tempo. O fato é que, a cada nova feature, mais complexo fica o debugger e a análise. Testes são fundamentais, independente do cenário.

Sendo assim, temos a seguinte estrutura:

Pug.Compiler
├── CodeAnalysis/
│   ├── Lexer.cs
│   ├── SyntaxParser.cs
│   ├── Token.cs
│   └── TokenType.cs
├── Runtime/
│   ├── BuiltInFunctions.cs
│   ├── DataTypes.cs
│   └── Identifier.cs
└── Program.cs

Bom, se você leu a parte 1 e a parte 2 sabe que o processo se inicia com a extração de tokens efetuada pelo Lexer.

Para suportar a declaração de variáveis, precisamos adicionar novos tokens:

Arquivo CodeAnalysis/TokenType.cs:

public enum TokenType
{
    EndOfFile,

    Number,
    Bool,
    String,

    Plus,
    Minus,
    Multiply,
    Divide,

    Assign,

    OpenParenthesis,
    CloseParenthesis,

    Function,
    Comma,

    Identifier,
    DataType
}

Dessa vez temos Bool, String, Assign, Identifier e DataType.

Você pode estar se perguntando: Cadê os tokens int e double?

Aqui temos um ponto fundamental. int e double, assim como string e bool são tipos de dados e tipos de dados a gente vai mapear como DataType. Além disso, o nome da variável vai ser mapeado como Identifier (talvez num futuro eu mude para que os nomes das funções também sejam mapeados como Identifier).

Certo, mas por quais motivos temos os TokenType Number, String e Bool?
Simples: eles mapeiam constantes. Por exemplo.

123 gera um token do tipo Number com valor 123.
"Olá Mundo" gera um token do tipo String com valor "Olá Mundo".
true gera um token do tipo Bool com valor true.
false gera um token do tipo Bool com valor false.

Com isso, ao executar a expressão: string nome = "Angelo" teremos a seguinte lista de tokens:

> string nome = "Angelo"
TokenType.DataType => string (Position: 0)
TokenType.Identifier => nome (Position: 7)
TokenType.Assign => = (Position: 12)
TokenType.String => Angelo (Position: 14)
TokenType.EndOfFile =>  (Position: 22)
Angelo

Vamos analisar a classe Lexer…

Arquivo CodeAnalysis/Lexer:

public class Lexer
{
    private readonly string _text;

    private int _currentPosition;
    private char _currentChar;

    public Lexer(string text)
    {
        _text = text;
        _currentPosition = 0;
        _currentChar = _text.Length > 0 ? _text[_currentPosition] : Token.END_OF_FILE;
    }

    public List<Token> ExtractTokens()
    {
        var tokens = new List<Token>();

        while (_currentChar != Token.END_OF_FILE)
        {
            if (char.IsWhiteSpace(_currentChar))
            {
                IgnoreWhitespace();
                continue;
            }

            if (char.IsLetter(_currentChar))
            {
                tokens.Add(ExtractKeyword());
                continue;
            }

            if (_currentChar == Token.QUOTE)
            {
                tokens.Add(ExtractString());
                continue;
            }

            if (_currentChar == Token.ASSIGN)
            {
                tokens.Add(Token.Assign(_currentPosition));
                Next();
                continue;
            }

            if (_currentChar == Token.MINUS && char.IsDigit(Peek()) || char.IsDigit(_currentChar))
            {
                tokens.Add(ExtractNumber());
                continue;
            }

            tokens.Add(ExtractSymbols());
        }

        tokens.Add(Token.EndOfFile(_currentPosition));
        return tokens;
    }

    private Token ExtractKeyword()
    {
        var position = _currentPosition;
        var identifier = ExtractIdentifier();

        if (Identifier.ContainsDataType(identifier.Value))
            return Token.DataType(position, identifier.Value);

        if (BuiltInFunctions.Contains(identifier.Value))
            return Token.Function(position, identifier.Value);

        if (identifier.Value is Token.TRUE or Token.FALSE)
            return Token.Bool(position, identifier.Value);

        return Token.Identifier(position, identifier.Value);
    }

    private Token ExtractString()
    {
        var position = _currentPosition;

        Next();
        var stringValue = new StringBuilder();

        while (_currentChar != Token.QUOTE && _currentChar != Token.END_OF_FILE)
        {
            stringValue.Append(_currentChar);
            Next();
        }

        if (_currentChar != Token.QUOTE)
            throw new Exception("String not closed");

        Next();
        return Token.String(position, stringValue.ToString());
    }

    private Token ExtractSymbols()
    {
        var position = _currentPosition;
        var token = _currentChar switch
        {
            Token.PLUS => Token.Plus(position),
            Token.MINUS => Token.Minus(position),
            Token.MULTIPLY => Token.Multiply(position),
            Token.DIVIDER => Token.Divide(_currentPosition),
            Token.OPEN_PARENTHESIS => Token.OpenParenthesis(position),
            Token.CLOSE_PARENTHESIS => Token.CloseParenthesis(position),
            Token.COMMA => Token.Comma(position),
            _ => throw new Exception($"Unexpected character {_currentChar} at position {position}")
        };

        Next();
        return token;
    }

    private Token ExtractNumber()
    {
        var position = _currentPosition;
        var number = new StringBuilder();
        var hasDot = false;

        if (_currentChar == Token.MINUS)
        {
            number.Append(Token.MINUS);
            Next();
        }

        while (char.IsDigit(_currentChar) || _currentChar == Token.DOT)
        {
            if (_currentChar == Token.DOT)
            {
                if (hasDot)
                    throw new Exception("Invalid number format: multiple dots");

                hasDot = true;
            }

            number.Append(_currentChar);
            Next();
        }

        if (hasDot && !double.TryParse(number.ToString(), out _))
            throw new Exception($"Invalid number format: {number}");

        return Token.Number(position, number.ToString());
    }

    private Token ExtractIdentifier()
    {
        var position = _currentPosition;
        var result = new StringBuilder();

        while (char.IsLetter(_currentChar))
        {
            result.Append(_currentChar);
            Next();
        }

        return Token.Identifier(position, result.ToString());
    }

    private char Peek()
    {
        var position = _currentPosition + 1;
        return position < _text.Length ? _text[position] : Token.END_OF_FILE;
    }

    private void Next()
    {
        _currentPosition++;
        _currentChar = _currentPosition < _text.Length ? _text[_currentPosition] : Token.END_OF_FILE;
    }

    private void IgnoreWhitespace()
    {
        while (char.IsWhiteSpace(_currentChar))
            Next();
    }
}

Ela cresceu bastante desde a parte 2, mas, sinceramente, nenhuma mudança brusca.

O que temos de novidade é que cada token agora tem seu próprio método de extração. Isso facilita muito a leitura e a manutenção do código. Antes, o método ExtractTokens continha muitas linhas e a tendência era crescer cada vez mais. Hoje, ele trata somente de identificar qual é o token em questão e mandar para o método que faz sua extração.

Vamos dissecar alguns desses extratores.

ExtractIdentifier: Ele extrai palavras sem espaços. Basicamente, vamos extrair nomes de variáveis (e talvez futuramente nomes de métodos). Aqui não tem segredo.

ExtractSymbols: extrai os tokens de +, -, (, etc. Removi do método ExtractTokens e centralizei aqui.

ExtractString: extrai o conteúdo que estiver entre ". Simples assim.

ExtractKeyword: esse extrator identifica tokens mapeados como true, false, int, double, string. Basicamente, todas as palavras suportadas pela linguagem de programação.

Nesse momento, você pode achar que os métodos ExtractIdentifier e ExtractKeyword fazem o mesmo, mas perceba que o Identifier não valida se aquela palavra existe no conjunto de palavras permitidas pela linguagem de programação. Essa é a principal diferença. Inclusive, eu tinha feito tudo no método ExtractIdentifier, mas quando dei por conta, ele parecia uma curva de rio.

Fazer essa separação vai facilitar quando incluirmos tokens como if e else, por exemplo.

A classe Token não teve nenhuma mudança profunda. Somente a converti de record para class, já que dessa forma consigo criar um construtor privado e com parâmetros opcionais, e adicionei suporte a criação dos novos tokens.

Também criei algumas constantes. Somente isso…

Bem, nesse ponto já conseguimos identificar novos tokens e agora precisamos alterar nosso analisador sintático para ser possível efetuar o evaluate das expressões.

As alterações feitas na classe SyntaxParser seguem a mesma ideia da Parser: quebrar métodos por responsabilidade.

O fluxo de execução não mudou, somente está considerando novas expressões como a declaração e atribuição de valores a variáveis, concatenação e algumas operações entre strings além do suporte ao cálculo de expressões numéricas respeitando a prioridade. Isso está bem detalhado na parte 2.

Dentre as mudanças, destaco a criação do método Evaluate que nada mais é do que o antigo método Parser, porém dessa vez vamos retornar uma lista de Identifier.

Esse é um ponto interessante:

Como podemos ter várias expressões dentro do nosso código, cada expressão vai ter um retorno. Nesse momento centralizei no Identifier e acredito que vamos evoluir isso posteriormente. Antes, retornávamos double já que dávamos apenas suporte a operações matemáticas.

Nessa terceira parte, podemos ter operações entre tipos de dados, além de execuções de funções internas que não retornam valor, como, por exemplo, a print.

Quer um exemplo disso? Saca só:

int idade = 41
string nome = "Angelo"
print(nome + " tem " + idade + " anos de idade")

Resultado do processamento:

> int idade = 41
string nome = "Angelo"
print(nome + " tem " + idade + " anos de idade")
Angelo tem 41 anos de idade
41
Angelo
{espaço em branco}

Basicamente, temos a declaração de duas variáveis — idade e nome - e em seguida nós damos um print num texto.

A execução desse código-fonte resulta no texto "Angelo tem 41 anos de idade".
Em seguida, temos a impressão do evaluate de cada expressão:

41: evaluate de int idade = 41
Angelo: evaluate de string nome = "Angelo"
{espaço em branco}: evaluate de print(nome + " tem " + idade + " anos de idade"). Como print retorna um identifier cujo valor é None (veremos mais para frente), nenhum resultado dessa execução é impresso no console.

Cada expressão dessas é representada por um Identifier. E eu sei que você quer saber que diabos é isso… Sendo assim, antes da gente esmiuçar a classe SyntaxParser vamos olhar com calma algumas coisas do nosso novo namespace Runtime.

Arquivo Runtime/Identifier.cs

public class None
{
    public static readonly None Value = new();
}

public class Identifier(DataTypes dataType, object value)
{
    private const string IntType = "int";
    private const string DoubleType = "double";
    private const string BoolType = "bool";
    private const string StringType = "string";

    private static readonly Dictionary<string, Func<Identifier, Identifier>> TypeConverters = new()
    {
        [IntType] = value => new Identifier(DataTypes.Int, value.ToInt()),
        [DoubleType] = value => new Identifier(DataTypes.Double, value.ToDouble()),
        [BoolType] = value => new Identifier(DataTypes.Bool, value.ToBool()),
        [StringType] = value => new Identifier(DataTypes.String, value.ToString()),
    };

    public static readonly Identifier None = new(DataTypes.None, Pug.Compiler.Runtime.None.Value);

    public DataTypes DataType { get; } = dataType;

    public object Value
        => DataType switch
        {
            DataTypes.Int => ToInt(),
            DataTypes.Double => ToDouble().ToString(CultureInfo.InvariantCulture),
            DataTypes.Bool => ToBool().ToString().ToLower(),
            DataTypes.String => ToString(),
            DataTypes.None => Identifier.None,
            _ => throw new Exception($"Invalid data type: {DataType}")
        };

    public static Identifier Create<T>(DataTypes types, T value)
        => new(types, value is null ? None.Value : value);

    public static Identifier FromToken(Token token)
        => token.Type switch
        {
            TokenType.Number => new Identifier(DataTypes.Double,
                double.Parse(token.Value, CultureInfo.InvariantCulture)),
            TokenType.Bool => new Identifier(DataTypes.Bool, token.Value),
            TokenType.String => new Identifier(DataTypes.String, token.Value),
            _ => throw new Exception($"Invalid token type: {token.Type}")
        };

    public static bool ContainsDataType(string type)
        => TypeConverters.ContainsKey(type);

    public static Identifier Default(string typeName)
        => typeName switch
        {
            IntType => new Identifier(DataTypes.Int, 0),
            DoubleType => new Identifier(DataTypes.Double, 0),
            BoolType => new Identifier(DataTypes.Bool, false),
            StringType => new Identifier(DataTypes.String, string.Empty),
            _ => throw new Exception($"Invalid data type: {typeName}")
        };

    public Identifier Cast(string typeName)
        => DataType switch
        {
            DataTypes.Double when typeName != IntType && typeName != DoubleType
                => throw new Exception($"Invalid type {IntType} or {DoubleType}. Expected a {typeName}"),
            DataTypes.Int when typeName != IntType && typeName != DoubleType
                => throw new Exception($"Invalid type {IntType} or {DoubleType}. Expected a {typeName}"),
            DataTypes.String when typeName != StringType
                => throw new Exception($"Invalid type string. Expected a {typeName}"),
            DataTypes.Bool when typeName != BoolType
                => throw new Exception($"Invalid type bool. Expected a {typeName}"),
            _ => TypeConverters.TryGetValue(typeName, out var cast)
                ? cast(this)
                : throw new Exception($"Unknown type: {typeName}")
        };


    public double ToDouble()
    {
        var @string = ToString();
        var success = double.TryParse(@string, out var result);
        if (!success)
            throw new Exception($"Can't convert {value} to double");

        return result;
    }

    public int ToInt()
    {
        var @string = ToString();
        var success = int.TryParse(@string, out var result);
        if (!success)
            throw new Exception($"Can't convert {value} to int");

        return result;
    }

    public bool ToBool()
    {
        var @string = ToString();
        var success = bool.TryParse(@string, out var result);
        if (!success)
            throw new Exception($"Can't convert {value} to bool");

        return result;
    }

    public override string ToString()
        => value.ToString() ?? string.Empty;
}

Sim, eu sou desses que coloca dois ou mais tipos dentro de um mesmo arquivo… ~~Me julgue~~…

Basicamente, a classe Identifier representa um valor "tipado" (int, double, bool, string ou none) usado na execução do interpretador. Ela encapsula o tipo da variável (DataTypes) — futuramente do retorno de uma função — e o seu valor, além de fornecer métodos utilitários para conversão entre tipos e criação de instâncias a partir de tokens.

Imagine a expressão int idade = 41. O resultado do Parser é:

TokenType.DataType => int (Position: 0)
TokenType.Identifier => idade (Position: 4)
TokenType.Assign => = (Position: 10)
TokenType.Number => 41 (Position: 12)
TokenType.EndOfFile =>  (Position: 14)

Note que essa estrutura de tokens vai resultar no seguinte Identifier no processo de análise sintática:

Identifier(dataType: DataTypes.Int, value: 41)

Como o value é um objeto, logo, existem métodos para converter esse valor em um int, double, bool e string.

Aliás, temos um enum para isso:

Arquivo Runtime/DataTypes.cs:

public enum DataTypes
{
    Int,
    Double,
    Bool,
    String,

    None
}

Aliás… e esse None aí hein…

Pois é...

Como citei acima, em breve teremos suporte a funções. Funções podem retornar valores. Ou não. Esse None indica justamente que aquele identificador — no caso uma função — não retorna valor.

Hoje já temos isso com o método interno print.

Falando em print, uma das mudanças importantes foi justamente extrair a invocação de métodos internos que estavam dentro da SyntaxParser para uma classe própria:

Arquivo Runtime/BuiltInFunctions.cs:

public static class BuiltInFunctions
{
    private static readonly Dictionary<string, Func<List<Identifier>, Identifier>> Functions = new()
    {
        ["sqrt"] = args => args.Count == 1
            ? Identifier.Create(DataTypes.Double, Math.Sqrt(args[0].ToDouble()))
            : throw new Exception("Invalid number of arguments for sqrt"),

        ["pow"] = args => args.Count switch
        {
            1 => Identifier.Create(DataTypes.Double, Math.Pow(args[0].ToDouble(), 2)),
            2 => Identifier.Create(DataTypes.Double, Math.Pow(args[0].ToDouble(), args[1].ToDouble())),
            _ => throw new Exception("Invalid number of arguments for pow")
        },

        ["min"] = args => args.Count == 2
            ? Identifier.Create(DataTypes.Double, Math.Min(args[0].ToDouble(), args[1].ToDouble()))
            : throw new Exception("Invalid number of arguments for min"),

        ["max"] = args => args.Count == 2
            ? Identifier.Create(DataTypes.Double, Math.Max(args[0].ToDouble(), args[1].ToDouble()))
            : throw new Exception("Invalid number of arguments for max"),

        ["round"] = args => args.Count switch
        {
            1 => Identifier.Create(DataTypes.Double, Math.Round(args[0].ToDouble())),
            2 => Identifier.Create(DataTypes.Double, Math.Round(args[0].ToDouble(), args[1].ToInt())),
            _ => throw new Exception("Invalid number of arguments for round")
        },

        ["random"] = args => args.Count switch
        {
            0 => Identifier.Create(DataTypes.Double, Random.Shared.NextDouble()),
            1 => Identifier.Create(DataTypes.Double, Random.Shared.Next(args[0].ToInt())),
            2 => Identifier.Create(DataTypes.Double, Random.Shared.Next(args[0].ToInt(), args[1].ToInt())),
            _ => throw new Exception("Invalid number of arguments for random")
        },

        ["upper"] = args => args.Count == 1
            ? Identifier.Create(DataTypes.Int, args[0].ToString().ToUpperInvariant())
            : throw new Exception("Invalid number of arguments for upper"),

        ["lower"] = args => args.Count == 1
            ? Identifier.Create(DataTypes.Int, args[0].ToString().ToLowerInvariant())
            : throw new Exception("Invalid number of arguments for lower"),

        ["len"] = args => args.Count == 1
            ? Identifier.Create(DataTypes.Int, args[0].ToString().Length)
            : throw new Exception("Invalid number of arguments for len"),

        ["replace"] = args => args.Count == 3
            ? Identifier.Create(DataTypes.String, args[0].ToString().Replace(args[1].ToString(), args[2].ToString()))
            : throw new Exception("Invalid number of arguments for replace"),

        ["substr"] = args => args.Count switch
        {
            2 => Identifier.Create(DataTypes.String, args[0].ToString().Substring(args[1].ToInt())),
            3 => Identifier.Create(DataTypes.String, args[0].ToString().Substring(args[1].ToInt(), args[2].ToInt())),
            _ => throw new Exception("Invalid number of arguments for substr")
        },

        ["print"] = args =>
        {
            if (args.Count != 1)
                throw new Exception("Invalid number of arguments for print");

            Console.WriteLine(args[0].ToString());

            return Identifier.None;
        }
    };

    public static bool Contains(string functionName)
        => Functions.ContainsKey(functionName);

    public static Identifier Invoke(string functionName, List<Identifier> args)
    {
        var result = Functions.TryGetValue(functionName, out var function)
            ? function(args)
            : throw new Exception($"Function {functionName} not found");

        return result;
    }
}

Aqui não tem segredo. Temos um dicionário onde a chave é nome do método e o valor é um delegate que recebe uma lista de Identifier (args) e retorna um Identifier.

Cada delegate cria um Identifier baseado na característica do método.

No caso do print, só é aceito um argumento como parâmetro e não existe um retorno. É aqui onde temos o uso do None.

...

["print"] = args =>
{
    if (args.Count != 1)
        throw new Exception("Invalid number of arguments for print");

    Console.WriteLine(args[0].ToString());

    return Identifier.None;
} 
...

Destaco aqui a tentativa de conversão do valor baseado no tipo do dado para o tipo esperado como argumento no método, além de validar a quantidade de parâmetros aceitos. Isso é feito para poder invocar os métodos do dotnet!!!

Agora sim… podemos navegar nos mares agitados da SyntaxParser.cs.

Vocês costumam sonhar com código? Eu já sonhei com essa classe… foi triste… eu entrava num método recursivo e não conseguia sair… acordei e estava com a testa no teclado e um erro de call stack na tela...

Arquivo CodeAnalysis/SyntaxParser.cs:

public class SyntaxParser(Dictionary<string, Identifier> identifiers, List<Token> tokens)
{
    private Token CurrentToken => tokens[_currentPosition];
    private int _currentPosition;

    public List<Identifier> Evaluate()
    {
        var results = new List<Identifier>();
        while (_currentPosition < tokens.Count && CurrentToken.Type != TokenType.EndOfFile)
        {
            var identifier = EvaluateExpression();
            results.Add(identifier);
        }

        return results;
    }

    private Identifier EvaluateExpression()
    {
        var left = EvaluateExpressionWithPriority();

        while (CurrentToken.Type is TokenType.Plus or TokenType.Minus)
        {
            var @operator = NextIfTokenIs(CurrentToken.Type);
            var right = EvaluateExpressionWithPriority();

            left = EvaluateOperation(left, right, @operator);
        }

        return left;
    }

    private Identifier EvaluateExpressionWithPriority()
    {
        var left = EvaluateToken();

        while (CurrentToken.Type is TokenType.Multiply or TokenType.Divide)
        {
            var @operator = NextIfTokenIs(CurrentToken.Type);
            var right = EvaluateToken();
            left = EvaluateOperation(left, right, @operator);
        }

        return left;
    }

    private Identifier EvaluateToken()
        => CurrentToken.Type switch
        {
            TokenType.DataType => EvaluateDataType(),
            TokenType.Identifier => EvaluateIdentifier(),
            TokenType.Function => EvaluateFunction(),
            TokenType.Plus or TokenType.Minus => EvaluateSignal(),
            TokenType.Number => EvaluateNumber(),
            TokenType.String => EvaluateString(),
            TokenType.Bool => EvaluateBool(),
            TokenType.OpenParenthesis => EvaluateParenthesis(),
            _ => throw new Exception($"Unexpected token in EvaluateToken: {CurrentToken.Type}")
        };

    private Identifier EvaluateDataType()
    {
        var dataTypeToken = NextIfTokenIs(TokenType.DataType);
        if (!Identifier.ContainsDataType(dataTypeToken.Value))
            throw new Exception($"Unknown type: {dataTypeToken.Value}");

        var checkNext = Peek();

        var name = NextIfTokenIs(TokenType.Identifier).Value;
        var identifier = Identifier.Default(dataTypeToken.Value);
        identifiers[name] = identifier;

        if (checkNext.Type != TokenType.Assign)
            return identifier;

        NextIfTokenIs(TokenType.Assign);
        var value = EvaluateExpression();
        identifier = value.Cast(dataTypeToken.Value);

        identifiers[name] = identifier;
        return identifier;
    }

    private Identifier EvaluateIdentifier()
    {
        var checkNext = Peek();
        if (CurrentToken.Type == TokenType.Identifier && checkNext.Type == TokenType.Assign)
            return EvaluateAssignment();

        var token = NextIfTokenIs(TokenType.Identifier);

        if (!identifiers.TryGetValue(token.Value, out var identifier))
            throw new Exception($"Unknown identifier: {token.Value}");

        return identifier;
    }

    private Identifier EvaluateFunction()
    {
        var token = NextIfTokenIs(TokenType.Function);
        NextIfTokenIs(TokenType.OpenParenthesis);

        var args = new List<Identifier>();
        if (CurrentToken.Type != TokenType.CloseParenthesis)
        {
            args.Add(EvaluateExpression());
            while (CurrentToken.Type == TokenType.Comma)
            {
                NextIfTokenIs(TokenType.Comma);
                args.Add(EvaluateExpression());
            }
        }

        NextIfTokenIs(TokenType.CloseParenthesis);
        return BuiltInFunctions.Invoke(token.Value, args);
    }

    private Identifier EvaluateSignal()
    {
        var token = NextIfTokenIs(CurrentToken.Type);
        var result = EvaluateToken();
        var value = token.Type == TokenType.Minus
            ? -result.ToDouble()
            : result.ToDouble();

        return new Identifier(result.DataType, value);
    }

    private Identifier EvaluateNumber()
    {
        var token = NextIfTokenIs(TokenType.Number);
        return Identifier.FromToken(token);
    }

    private Identifier EvaluateString()
    {
        var token = NextIfTokenIs(TokenType.String);
        return new Identifier(DataTypes.String, token.Value);
    }

    private Identifier EvaluateBool()
    {
        var token = NextIfTokenIs(TokenType.Bool);
        return new Identifier(DataTypes.Bool, token.Value);
    }

    private Identifier EvaluateParenthesis()
    {
        NextIfTokenIs(TokenType.OpenParenthesis);
        var result = EvaluateExpression();
        NextIfTokenIs(TokenType.CloseParenthesis);
        return result;
    }

    private static Identifier EvaluateOperation(Identifier left, Identifier right, Token @operator)
    {
        if (left.DataType == DataTypes.String || right.DataType == DataTypes.String)
            return EvaluateStringOperation(left, right, @operator);

        if (left.DataType == DataTypes.Double ||
            right.DataType == DataTypes.Double ||
            left.DataType == DataTypes.Int ||
            right.DataType == DataTypes.Int)
            return EvaluateNumberOperation(left, right, @operator);

        throw new Exception($"Unexpected token: {@operator.Type}");
    }

    private static Identifier EvaluateStringOperation(Identifier left, Identifier right, Token @operator)
    {
        var value = @operator.Type switch
        {
            TokenType.Plus => left.ToString() + right.ToString(),
            TokenType.Minus => Minus(left.ToString(), right.ToString()),
            TokenType.Multiply => Multiply(),
            _ => throw new Exception($"Unexpected token: {@operator.Type}")
        };

        return new Identifier(DataTypes.String, value);

        static string Minus(string @string, string value)
            => @string.Replace(value, string.Empty);

        string Multiply()
        {
            string @string;
            int count;

            if (left.DataType == DataTypes.String)
            {
                @string = left.ToString();
                count = right.ToInt();
            }
            else
            {
                @string = right.ToString();
                count = left.ToInt();
            }

            var result = new StringBuilder();
            for (var i = 0; i < count; i++)
                result.Append(@string);

            return result.ToString();
        }
    }

    private static Identifier EvaluateNumberOperation(Identifier left, Identifier right,
        Token @operator)
    {
        var value = @operator.Type switch
        {
            TokenType.Plus => left.ToDouble() + right.ToDouble(),
            TokenType.Minus => left.ToDouble() - right.ToDouble(),
            TokenType.Multiply => left.ToDouble() * right.ToDouble(),
            TokenType.Divide => left.ToDouble() / right.ToDouble(),
            _ => throw new Exception($"Unexpected token: {@operator.Type}")
        };

        return new Identifier(DataTypes.Double, value);
    }

    private Identifier EvaluateAssignment()
    {
        var variableName = NextIfTokenIs(TokenType.Identifier).Value;
        NextIfTokenIs(TokenType.Assign);
        var value = EvaluateExpression();

        if (!identifiers.ContainsKey(variableName))
            throw new Exception($"Unknown identifier: {variableName}");

        identifiers[variableName] = value;
        return value;
    }

    private Token Peek()
    {
        var nextPosition = _currentPosition + 1;
        return nextPosition < tokens.Count ? tokens[nextPosition] : tokens.Last();
    }

    private Token NextIfTokenIs(TokenType type)
    {
        if (CurrentToken.Type != type)
            throw new Exception($"Unexpected token: {CurrentToken.Type}, expected: {type}");

        var token = CurrentToken;
        _currentPosition++;
        return token;
    }
}

Como citei acima, refatorei o código para poder suportar os novos tokens e o resultado é um código um pouco mais legível.

Ainda temos os métodos EvaluateExpression e EvaluateExpressionWithPriority e eles seguem fazendo o mesmo explicado na parte 2.

Já o método NextIfTokenIs retorna o CurrentToken. Fiz isso para facilitar o uso do método.

Foi criado o método Peek para "olhar" o próximo token em questão. Esse método vai ser muito útil em cenários como quando preciso saber se existe uma atribuição de valor a uma variável no momento da sua declaração. Nesse caso, se existir o token Assing (=) na declaração, significa que é necessário fazer todo o processo de parser dessa expressão já que é possível passar uma constante ou uma expressão. Exemplos:

int idade: nesse caso o Peek() vai indicar fim da expressão.
int valor = pow(3+5): nesse caso o Peek() vai indicar que existe um = e o processo vai precisar efetuar o evaluate dos próximos tokens.

O método EvaluateToken evoluiu para direcionar para o método de evaluate atrelado ao tipo do CurrentToken (se for Number chama o EvaluateNumber, se for String chama o EvaluateString e por aí vai…)

Acredito que somente alguns novos métodos devam ser explicados, já que eles dão suporte a nossa nova feature de declaração de variáveis. O resto é mais do mesmo e já foi explicado na parte 2.

Vou começar pelo EvaluateDataType. Esse método é onde fazemos a "declaração da variável". E começamos pelo tipo. Só que aqui temos uma coisa interessante.

Na nossa linguagem de programação, uma variável já nasce com um valor default, isto é, mesmo que a gente não informe o valor no momento da declaração, ela vai receber um valor default baseado no seu tipo.

Entendo que isso não seja comum nas linguagens de programação, já que na teoria estaríamos alocando um valor em memória, porém, os compiladores podem remover variáveis declaradas e não usadas. Eu não me preocupei com isso, foquei em deixar as coisas simples e fáceis para usar…

Lá na classe Runtime/Identifier.cs temos um método chamado Default que deixei para explicar agora propositalmente:

public static Identifier Default(string typeName)
    => typeName switch
    {
        IntType => new Identifier(DataTypes.Int, 0),
        DoubleType => new Identifier(DataTypes.Double, 0),
        BoolType => new Identifier(DataTypes.Bool, false),
        StringType => new Identifier(DataTypes.String, string.Empty),
        _ => throw new Exception($"Invalid data type: {typeName}")
    };

Caso na declaração um = for encontrado (e é aqui que usamos o Peek()) atribuímos o valor da expressão seguinte. Caso contrário, atribuímos o valor default. Nada de nulo. Isso é por definição da linguagem. E nada de forçar a atribuição de valores antes de usar a variável (algo que poderia ter no csharp né?). Isso deixa a linguagem mais clean… Virei designer… de linguagens… vou até atualizar o meu Curriculum.

Ao obter o Identifier da variável, armazenamos o objeto num dicionário onde a chave é o nome da variável e o valor é o próprio Identifier.

E aqui temos uma coisa um pouco estranha e um pouco interessante: para manter o valor da variável em memória, é preciso manter esse dicionário em memória e repassá-lo toda vez que iniciarmos o processo de análise sintática. Logo, em nosso Program.cs esse dicionário é criado e repassado no construtor do SyntaxParser.

É por isso que podemos executar expressões do tipo:

> int idade = random(1, 50)
27
> string nome = "Angelo"
Angelo
> print(nome + " tem " + idade + " anos de idade")
Angelo tem 27 anos de idade

Cada linha de execução (que começa com >) é uma expressão. E a cada expressão, uma instância do SyntaxParser é criada.

Lembrando que esse processo existe somente para suportar o REPL. Aliás, se eu passar o conteúdo todo de uma vez, o nosso compilador vai funcionar normalmente. Em breve, vou adicionar um projeto onde teremos um editor de código baseado no VSCode, o famigerado Monaco Editor. Dessa forma, nós vamos poder escrever código normalmente, como se estivéssemos usando um "IDE"… no caso estaremos… não é "aquela" "IDE", mas é uma "IDE modesta e que nos atende bem…

Na boa, não vou entrar na discussão "IDE" x "Editor de Código"...

Enfim… é estranho… mas é necessário…

Já o método EvaluateAssignment somente atribui valor a uma variável já declarada. Algo como idade = 28.

Esses métodos por si só suportam nossa feature de criação de variáveis. Porém, temos mais algumas coisinhas legais.

EvaluateOperation! Podemos efetuar operações usando +, -, * e / com números e com… string. Bom… você já presenciou isso em print(nome + " tem " + idade + " anos de idade"). Basicamente, estou somando string com int.

Esse método valida se ambos Identifiers recebidos são de tipos numéricos, (se esquerda e direita são do Double ou Int — isso num fluxo de operação, algo como idade + 1). Se sim, invoca o método EvaluateNumberOperation, que faz o cálculo matemático trivial de soma, subtração, divisão e multiplicação. Nada de novo no front…

Porém, caso algum dos Identifiers seja uma string vamos poder fazer manipulações usando os operadores - e *, além do +, claro.

Se o operador for +, concatena a string:

> "Angelo" + " Belchior"
Angelo Belchior

Até aqui, beleza.

E se o operador for -? Eu decidi, como designer de linguagens que agora sou, que nesse caso, eu removo um conteúdo da string. Exemplo:

> "Angelo Belchior Br" - " Belchior "
AngeloBr

Dada a string "Angelo Belchior Br", ao "subtrair" o texto " Belchior" temos como resultado "AngeloBr". Legal, né?

Já o operador * basicamente multiplica (repete x vezes) a string em questão. Por exemplo:

> "A" * 3
AAA

Um ponto importante aqui é que, como tratamos dois Identifiers, o da esquerda e o da direita da expressão, precisamos validar qual é o valor numérico e qual é o valor alfanumérico justamente para podermos executar expressões do tipo "A" * 3 e 3 * "A" e obtermos o valor AAA.

No futuro, caso tenhamos suporte a arrays podemos implementar o operador / para expressões do tipo "A;B;C" / ";" e obtermos ["A", "B", "C"]. Quem sabe...

Lexer e SyntaxParser explicados. Nova estrutura do projeto apresentada. O que resta agora é mostrar como ficou nosso Program.cs

Arquivo Program.cs:

Dictionary<string, Identifier> identifiers = new();

var printTokens = false;

while (true)
{
    try
    {
        Console.ForegroundColor = ConsoleColor.Green;
        Console.Write("> ");

        var line = Console.ReadLine() ?? string.Empty;

        Console.ResetColor();

        if (line.Equals("/quit", StringComparison.CurrentCultureIgnoreCase))
            return;

        if (line.Equals("/cls", StringComparison.CurrentCultureIgnoreCase))
        {
            Console.Clear();
            continue;
        }

        if (line.Equals(":t", StringComparison.CurrentCultureIgnoreCase))
        {
            printTokens = !printTokens;
            Console.WriteLine($"Print tokens: {printTokens}");
            continue;
        }

        if (string.IsNullOrEmpty(line))
            break;

        var lexer = new Lexer(line);
        var tokens = lexer.ExtractTokens();

        if (printTokens)
            PrintTokens(tokens);

        var syntaxParser = new SyntaxParser(identifiers, tokens);
        var results = syntaxParser.Evaluate();

        foreach (var result in results)
            if (result.DataType != DataTypes.None)
                WriteLine(result.Value, ConsoleColor.Blue);
    }
    catch (Exception ex)
    {
        WriteLine(ex.Message, ConsoleColor.Red);
    }
}

static void WriteLine(object message, ConsoleColor color)
{
    Console.ForegroundColor = color;
    Console.WriteLine(message);
    Console.ResetColor();
}

static void PrintTokens(IEnumerable<Token> tokens)
{
    foreach (var token in tokens)
        Console.WriteLine(token);
}

Firulas… apenas firulas… Uma corzinha aqui, outra ali…

As duas únicas novidades que devemos citar são a criação do dicionário de Identifiers (explicado acima o motivo para ter essa variável) e o resultado do syntaxParser.Evaluate que agora vem em uma lista e efetuamos o print de cada um deles. O resto é perfumaria…

Código Fonte: https://github.com/angelobelchior/Pug.Compiler

Mais uma feature entregue. Seguimos avançando. Próximo post promete!

Forte abraço e até lá!

Criando um compilador em csharp: Parte 2

Angelo Belchior — Mon, 26 May 2025 22:30:00 +0000

Voltamos!

E dessa vez prometo que o post vai ser mais simples e direto.
Era impossível fazer isso na parte 1 da série Criando um compilador em csharp já que era importante apresentar motivações e introduzir conceitos.

Fora que o objetivo do primeiro post era resolver expressões matemáticas. Mas para construirmos isso, precisávamos implementar um analisador léxico e um analisador sintático. Foi o que fizemos: Lexer e Parser.

E para avançar, assumo que você leu e entendeu a implementação desses dois conceitos, pois a partir de agora vamos apenas adicionar features nessas implementações.

Dito isso, podemos e devemos ser mais objetivos!

Pega aquele café e vem comigo!

Adicionando métodos internos à nossa linguagem.

Como citei acima, hoje temos um "resolvedor" de expressões matemáticas, porém a ideia agora é adicionar algumas funções internas como calcular raiz quadrada, potência, obter o maior ou o menor valor dentre dois números, além de poder arredondar um número a uma determinada quantidade de casas. E for fun, adicionei um método para retornar um valor aleatório.

Basicamente, temos que interpretar expressões do tipo funcao(param1, param2) ou ainda funcao().

É o que faremos.

Para isso, precisamos mapear dois novos tokens: Function e Comma.

Vamos começar adicionando esses dois novos tokens ao nosso enum TokenType:

Arquivo CodeAnalysis/TokenType.cs

namespace Pug.Compiler.CodeAnalysis;

public enum TokenType
{
    ...

    Function,
    Comma
}

Em seguida, vamos até o record Token e incluir métodos auxiliares para a criação dos novos mapeamentos:

Arquivo CodeAnalysis/Token.cs

namespace Pug.Compiler.CodeAnalysis;

public record Token(TokenType Type, string Value, int Position)
{

    ...

    public static Token Function(int position, string value) 
    => new(TokenType.Function, value, position);

    public static Token Comma(int position) 
    => new(TokenType.Comma, ",", position);

}

Certo. Já temos como mapeá-los.

O processo é bem parecido com o que já existe. Na classe Lexer precisamos identificar a vírgula e a função. A função nada mais é do que um conjunto de caracteres onde não são aceitos espaços ou números. Basicamente, uma função só pode conter letras. Essa foi a regra que defini.

Para isso, vamos ter que criar um método para extrair a função, assim como fizemos para extrair números e invocá-lo na ordem apropriada no método CreateTokens.

Arquivo CodeAnalysis/Lexer.cs

public List<Token> CreateTokens()
{
    var tokens = new List<Token>();

    while (_currentChar != EOF)
    {
        if (char.IsWhiteSpace(_currentChar))
        {
            IgnoreWhitespace();
            continue;
        }

        if (char.IsLetter(_currentChar))
        {
            tokens.Add(ExtractFunction());
            continue;
        }

        if (_currentChar == '-' && char.IsDigit(Peek()))
        {
            tokens.Add(ExtractNumber());
            continue;
        }

        if (char.IsDigit(_currentChar))
        {
            tokens.Add(ExtractNumber());
            continue;
        }

        var token = _currentChar switch
        {
            '+' => Token.Plus(_currentPosition),
            '-' => Token.Minus(_currentPosition),
            '*' => Token.Multiply(_currentPosition),
            '/' => Token.Divide(_currentPosition),
            '(' => Token.OpenParenthesis(_currentPosition),
            ')' => Token.CloseParenthesis(_currentPosition),
            ',' => Token.Comma(_currentPosition),
            _ => throw new Exception($"Unexpected character: {_currentChar}")
        };
        tokens.Add(token);

        Next();
    }

    tokens.Add(new Token(TokenType.EOF, string.Empty, _currentPosition));
    return tokens;
}

Podemos notar no método CreateTokens que logo após o processo para ignorar espaços em branco começamos a procurar tokens que podem ser considerados uma função: if (char.IsLetter(_currentChar)).

Mais abaixo temos o mapeamento da vírgula: ',' => Token.Comma(_currentPosition). Ele é feito logo após o mapeamento e criação do Token.CloseParenthesis.

Para extrair a função, temos o método:

private Token ExtractFunction()
{
    var result = new StringBuilder();
    while (char.IsLetter(_currentChar))
    {
        result.Append(_currentChar);
        Next();
    }
    var value = result.ToString();
    return Token.Function(_currentPosition, value);
}

É bem tranquilo… Vou avançando entre os caracteres até que encontre um que não seja uma letra.

O segredo do processo para mapear e extrair funções está justamente no momento em que a gente faz essa extração. Começo removendo caracteres que são ignoráveis (no nosso caso temos somente o espaço), depois extraio tokens cujo valor são conjuntos de caracteres, no nosso caso temos o nome de função e seus argumentos, além de valores numéricos (que podem ou não conter o sinal de +, ou de -, além de .), e por fim, caracteres "soltos" como (, ), +, -, etc.

Essa ordem é fundamental.

Habemus Papam e Habemus novos tokens.

Bora fazer a análise sintática.

Primeiro começo dizendo que fiz uma mudança em um método.

O CheckToken virou NextIfTokenIs. Para mim, faz muito mais sentido agora — e espero que para você também — afinal, é isso que ele faz: avança ao próximo token caso ele seja do tipo especificado.

Dito isto, vamos à implementação. Basicamente, mudamos o método EvaluateToken incluindo o processamento dos novos tokens e criamos uma nova função chamada InvokeMethod. Vamos ver na prática:

Arquivo CodeAnalysis/SyntaxParser

private double EvaluateToken()
{
    var token = CurrentToken;

    if (token.Type == TokenType.Function)
    {
        NextIfTokenIs(TokenType.Function);
        NextIfTokenIs(TokenType.OpenParenthesis);

        var args = new List<double>();

        if (CurrentToken.Type != TokenType.CloseParenthesis)
        {
            args.Add(Parse());

            while (CurrentToken.Type == TokenType.Comma)
            {
                NextIfTokenIs(TokenType.Comma);
                args.Add(Parse());
            }
        }

        NextIfTokenIs(TokenType.CloseParenthesis);

        return InvokeMethod(token, args);
    }

    if (token.Type == TokenType.Plus)
    {
        NextIfTokenIs(TokenType.Plus);
        return EvaluateToken();
    }

    if (token.Type == TokenType.Minus)
    {
        NextIfTokenIs(TokenType.Minus);
        return -EvaluateToken();
    }

    if (token.Type == TokenType.Number)
    {
        NextIfTokenIs(TokenType.Number);
        return double.Parse(token.Value, System.Globalization.CultureInfo.InvariantCulture);
    }

    if (token.Type == TokenType.OpenParenthesis)
    {
        NextIfTokenIs(TokenType.OpenParenthesis);
        var result = Parse();
        NextIfTokenIs(TokenType.CloseParenthesis);
        return result;
    }

    throw new Exception($"Unexpected token in Evaluate Token: {token.Type}");
}

Ao iniciar o processo de Evaluate dos tokens, começamos procurando por um token do tipo Function e, caso encontre, começamos a validar a estrutura da função. Avançamos (NextIfTokenIs(TokenType.Function)), e na sequência vamos ao encontro da abertura dos parênteses (NextIfTokenIs(TokenType.OpenParenthesis)).

O próximo passo é preparar uma lista para armazenar os valores dos argumentos caso existam (por enquanto, só são aceitos argumentos numéricos. Num futuro, isso vai mudar).

Para saber se existem ou não argumentos, verificamos se o token atual é um "Fecha Parênteses" (TokenType.CloseParenthesis). Se sim, a função não recebe nenhum valor como parâmetro. Caso contrário, fazemos o processo de validar argumentos separados por vírgula.

Espero que você tenha entendido bem a ideia do looping que acontece aqui e da recursividade. Isso foi explicado no post anterior, mas pense sempre que temos um cursor sendo executado, varrendo todos os tokens sempre para a frente. Sendo assim, quando falo token atual, eu me refiro ao token no qual o cursor está apontando no momento.

Os argumentos de uma função são processados recursivamente pelo método Parse e seu resultado é armazenado na lista de argumentos args.Add(Parse()). Esse método Parse resolve operações, dessa forma podemos ter algo como round(sqrt(max(4, random(5, 9876))))!

Em seguida, em forma de lopping, eu valido se tem outros argumentos separados por vírgula NextIfTokenIs(TokenType.Comma). Se sim, o processo é o mesmo: efetuo o parse e jogo o valor na lista.

Por fim, valido o fechamento dos parênteses NextIfTokenIs(TokenType.CloseParenthesis) e chamo a função InvokeMethod responsável por invocar o método mapeado no token passando a lista de argumentos.
Essa invocação nada mais é do que um "atalho" para um método existente do csharp. É assim que a gente faz o nosso evaluate:

private static double InvokeMethod(Token token, List<double> args)
=> token.Value.ToLower() switch
{
    "sqrt" => args.Count == 1
        ? Math.Sqrt(args[0])
        : throw new Exception("Invalid number of arguments for sqrt"),

    "pow" => args.Count switch
    {
        1 => Math.Pow(args[0], 2),
        2 => Math.Pow(args[0], args[1]),
        _ => throw new Exception("Invalid number of arguments for round")
    },

    "min" => args.Count == 2
        ? Math.Min(args[0], args[1])
        : throw new Exception("Invalid number of arguments for min"),

    "max" => args.Count == 2
        ? Math.Max(args[0], args[1])
        : throw new Exception("Invalid number of arguments for max"),

    "round" => args.Count switch
    {
        1 => Math.Round(args[0]),
        2 => Math.Round(args[0], Convert.ToInt32(args[1])),
        _ => throw new Exception("Invalid number of arguments for round")
    },

    "random" => args.Count switch
    {
        0 => Random.Shared.NextDouble(),
        1 => Random.Shared.Next(Convert.ToInt32(args[0])),
        2 => Random.Shared.Next(Convert.ToInt32(args[0]), Convert.ToInt32(args[1])),
        _ => throw new Exception("Invalid number of arguments for random")
    },

    _ => throw new Exception($"Unknown function: {token.Value}")
};

Acredito que o método seja bem simples de se entender. Eu pego o valor do token Function — que no caso é o nome da função — e testo para ver se ele é alguma das funções mapeadas da linguagem. No nosso caso, temos sqrt, pow, min, max, round e random.

Uma coisa interessante é que a quantidade de parâmetros também é validada. Podemos ter funções cujos parâmetros não são obrigatórios, como a round ou a pow.
No caso da pow, se o usuário omitir o segundo argumento, eu assumo ser 2. No csharp sou obrigado a informar dois parâmetros.

Além disso, validamos se a quantidade de parâmetros passada corresponde com a quantidade aceita pelo método.

O Pattern Matching do csharp é coisa linda. Deixa o código bem mais legível.

E, no fim, caso o nome da função não esteja mapeado, ocorre uma exceção.

Pronto! Podemos executar nossas funções juntamente com outras operações matemáticas. Ou chamar uma função dentro de uma função. Da para passar horas testando e o melhor é que você já sabe o caminho para adicionar mais funções, não é mesmo?

Então, bora testar!

Se tudo der certo e nada der errado, podemos executar as seguintes operações:

> sqrt(4)
2
> min(1, 2)
1
> max(8, 0)
8
> pow(3)
9
> pow(2, 3)
8
> round(1.234)
1
> round(1.234, 2)
1,23
> round(1.234, 1)
1,2
> random()
0,5424186829640589
> random(1, 10)
7
> sqrt(4) + min(2, -3)
-1
> 1 + pow(5, sqrt(4))
26
> ihuuuu(pow(2,4))
Unknown identifier: ihuuuu

E aí, curtiu?

Depois que entendemos e criamos o lexer e o parser, evoluí-los é algo bem mais tranquilo.

Segunda feature do nosso incrível compilador pug entregue.
Para ver o código-fonte, acesse https://github.com/angelobelchior/Pug.Compiler/tree/parte2.

Agora é só aguardar a terceira parte!

Forte abraço e te vejo no próximo post!

Criando um compilador em csharp: Parte 1

Angelo Belchior — Wed, 14 May 2025 21:55:00 +0000

Por que devemos criar um compilador?

Eu acredito piamente em duas coisas:

Todo Corintiano e toda Corinthiana deve assistir ao jogo do Colossal de Itaquera no Santiago Bernaleste (aka Neoquímica Arena) pelo menos uma vez na vida…

E toda pessoa desenvolvedora deve criar seu próprio compilador.

E você pode estar se perguntando: mas por quê?

A resposta é simples: porque é difícil.

Sim, é difícil. Para mim, então… vixi… é algo extremamente difícil…

E antes que você desista da ideia de criar o seu próprio compilador, ou simplesmente não ligue para isso, gostaria de apresentar esse vídeo incrível do incrível professor Clóvis de Barros Filho…

Esse vídeo rodou a internet. Acredito até que você já tenha assistido. Mas eu o acho muito inspirador, tanto que separei dois trechos maravilhosos que eu gostaria de compartilhar/reforçar:

“Você precisa sentar a bunda na cadeira e melhorar a tua capacidade de pensamento…”

“É esse brio que levará você a progredir intelectualmente. Estudar, aperfeiçoar a capacidade intelectiva e pensar com competência é tão esforçado quanto ter músculos, correr, nadar travessias: exige empenho, exige dedicação, exige bunda na cadeira.”

É isso. Quanto mais você estudar, quanto mais você se dedicar, mais você vai progredir. Acredite em mim. Não sou coach…

Sendo assim, hoje começo uma série de posts que tem data para começar, mas não tem data para terminar: criando um compilador em csharp!

Mas não se preocupe e não tenha pressa. Post a post vamos evoluindo, explicando e principalmente aprendendo.

Aliás, no momento em que ler esse post, saiba que tem mais dois aguardando a publicação. Quis criar um buffer justamente para não perder o ritmo e espero a cada 15 dias publicar um novo conteúdo.

A motivação

Quando fui escrever o post .NET Source Generators: gerando código em tempo de escrita de código! dediquei muito tempo lendo o código-fonte do Roslyn (compilador do csharp escrito em csharp) e isso me ajudou a entender algumas poucas coisas. Mas foi muito útil.

Porém, foi assistindo o grande Immo Landwerth(Product manager no time do .NET na Microsoft) que eu simplesmente fiquei bestificado! O cara simplesmente criou um compilador na mão usando csharp. Do começo ao fim: https://github.com/terrajobst/minsk!

E o melhor, ao vivo: https://www.youtube.com/live/wgHIkdUQbp0?si=lwLSg28EJPXHE96z. São 28 vídeos fantásticos. Fiz questão de assistir um por um. Duas vezes. Para poder acreditar que era possível… Esse conteúdo é uma fonte extraordinária de estudos.

Suponho que você saiba minimamente o que é um compilador. É importante que você tenha isso em mente. Existem muitos artigos na internet e ainda temos o chat GPT onde podemos buscar ajuda.

Aliás, você pode acessar o https://github.com/terrajobst/minsk/tree/master/docs e ver a lista de todos os episódios, além de ter acesso ao Pull Request de cada implementação. Trabalho fino, trabalho garboso do Immo…

Além disso, conheci o blog do dr. Brian Robert Callahan, onde ele fez uma série maravilhosa chamada Let's write a compiler. É uma aula. Uma não, 8! São 8 posts bem detalhados e muito bem escritos. O cara é sensacional… SEN-SA-CI-O-NAL. Um dia chego lá! Um dia chego…

Isso me motivou a criar meu próprio compilador.

Pug?

Senhoras e senhores, vos apresento Pug: Programming Understandable Global.

Sei que o nome não faz o mínimo sentido, mas a vida é assim mesmo e eu gosto muito de Pugs. Tenho dois, inclusive. Além disso, o nome é simples: pug.

pug build
pug run

Viu só… não é tão ruim quanto parecia… Ou não…

Dado e explicado o nome, é hora de começar a nossa caminhada.

Porém, antes de tudo, gostaria de destacar que essa não será uma caminhada simples, será uma jornada.

Vamos construir um compilador pecinha por pecinha, código por código, tudo de forma didática e tranquila. E durante essa odisseia o resultado que vamos obter a cada post talvez não possa ser classificado como um compilador ou até mesmo um interpretador na essência da concepção computacional. A ideia aqui é ser prático e objetivo quanto às entregas. Cada post revela uma nova funcionalidade. Degrau por degrau. Sem pressa, na tranquilidade…

E tem que ser assim, afinal, entre escrever o código-fonte, parsear e gerar o arquivo binário da aplicação, existe uma distância quase que intergalática. Por isso que não adianta ter pressa. E talvez no meio desse processo, vou precisar parar e explicar (e aprender) mais sobre IL. Opto por IL pelo simples fato de me manter no ecossistema dotnet e por ter bibliotecas que auxiliam na geração de código IL em csharp (tanto a System.Reflection.Emit da própria Microsoft, quanto a Sigil do lendário Kevin Montrose).

Aliás, não sei se ficou claro, mas além do compilador, criaremos uma linguagem de programação. Isso mesmo!

Minha ideia não é criar algo rebuscado, complexo, e sim criar uma linguagem que suporte comandos suficientes para a gente criar um Hello World e fazer algumas operações matemáticas.

~~Também não quero criar algo como aquela linguagem que não devemos pronunciar o nome, que ao executar null >= [] dá true como resultado…~~

Um ponto importante para destacar é que a primeira entrega (esse post) trata somente da interpretação de expressões matemáticas simples utilizando e respeitando a ordem dos parênteses, multiplicação, divisão, soma e subtração. Aquelas regrinhas que a gente aprendeu no primário…

Sendo assim, a nossa primeira entrega consegue resolver questões como:

> -(1+(2*3)/4)
-2,5

Devagar e sempre…

Alguns conceitos importantes

Existem muitos conceitos importantes quando falamos de um compilador e dois deles são Lexer e Parser.

O Lexer, ou Analisador Léxico, é responsável por ler todo o código-fonte e extrair tokens.
Para isso, é necessário que o Lexer conheça todas as “palavras reservadas” e as classifique. O resultado dessa classificação é um Token, uma estrutura de dados que informa qual é o tipo, valor e em qual posição da string ela se encontra.

Já o Parser, ou Analisador Sintático, recebe a lista de tokens e analisa se a estrutura sequencial gramatical extraída do código-fonte segue as regras da linguagem de programação.
Feita essa validação, é possível transformar a lista de tokens em uma árvore sintática (AST – Abstract Syntax Tree) ou outro tipo de representação estrutural.

No nosso caso, não vamos gerar uma AST. Pelo menos nesse momento. E quando gerarmos, dedicaremos tempo para explicar o que é, como funciona e traremos, inclusive, exemplos da própria árvore gerada pelo Roslyn a partir de um código csharp.

Além disso, dentro do nosso Parser teremos a execução das expressões (Evaluate) o que o torna quase que um REPL. Isso vai ser bem útil, afinal, podemos interagir com o console escrevendo expressões e validando o resultado.

Uma coisa interessante e importante

Se fizermos um paralelo entre um idioma, como o português, e uma linguagem de programação, a análise léxica seria responsável por identificar as palavras em um texto, ou código-fonte. Vejamos o seguinte “poema” em “português”:

Ojnwerun escola daef fds xçã
Uolasda cachorro aksdmasd da
Bicicleta as asdasda a
Olapasdm rabanada asdasdasm

Como pode notar, a nossa análise consegue identificar somente poucas palavras (escola, cachorro, bicicleta e rabanada). Cognitivamente, não conseguimos absorver/compreender nada desse conteúdo, já que ele não faz sentido, mesmo tendo palavras conhecidas.

Isso pode parecer óbvio quando falamos de idiomas!

Porém, assim como nosso senso de interpretação de texto, o Lexer não tem capacidade de extrair (reconhecer) tokens não mapeados.
Isso explica o motivo pelo qual o compilador do Java não reconhece um código-fonte escrito em Csharp, por exemplo, da mesma forma que se você fala somente português, não vai conseguir entender nada ao ouvir uma frase em russo. Se bem que talvez nem os russos entendam o idioma russo… sei lá… mas enfim… acho que você entendeu…

E quando falamos de análise sintática, basicamente temos uma avaliação do sentido das palavras conhecidas em um texto ou código-fonte.

Não adianta o texto ter somente palavras conhecidas se o conjunto não fizer sentido. Por exemplo:

Abacate jacaré ketchup na pizza
Mundial 51 Palmeiras Romarinho
Lanterna gato escola abacaxi
Incrível correr maionese lambari

Todas as palavras acima são conhecidas do nosso idioma, porém, ao analisar cada frase, notamos que não existe um sentido.

A análise sintática nos traz essa sensação, e no caso de um compilador, nos gera erro.

Agora, outro ponto muito importante é a desambiguação:

A manga tem a cor da manga

O que você entendeu? Que a fruta manga tem a cor da manga da camisa, ou que a manga da camisa tem a cor da fruta? Ou ainda, que tanto faz, já que ambas têm a mesma cor?

No csharp podemos cair em cenários como esses, porém, o compilador consegue resolver da melhor forma, afinal, o idioma (linguagem de programação) é muito mais rígido.

public class async
{
    public async Task<async> Task()
    {
        await System.Threading.Tasks.Task.Delay(10);
        return new async();
    }
}

O código não faz sentido, não é esse o objetivo. Mas ele compila. O compilador sabe exatamente o que cada palavra faz, não somente pelo seu significado em si, mas pela ordem em que ela aparece.

Não é genial?

Essa relação entre linguagem de programação e idioma é muito próxima que às vezes até se confunde.

Chega… Vamos ver código…

Criando um Analisador Léxico

Café… pega um café…

Considere a expressão abaixo:

1+2-  3

Ao efetuar a extração dos tokens, obtemos a seguinte lista:

Token 1 - Type: Number, Position: 1, Value: 1
Token 2 - Type: Plus, Position: 2, Value: "+"
Token 3 - Type: Number, Position: 3, Value: "2"
Token 4 - Type: Minus, Position: 4, Value: "-"
Token 5 - Type: Space, Position: 5, Value: "  "
Token 6 - Type: Number, Position: 7, Value: "3"

Nesse caso simplista, temos somente quatro tipos diferentes de tokens (Number, Plus, Minus e Space). Caso fosse colocado algum caractere fora desses tipos, o lexer apontaria erro, já que ele não o tem mapeado.

O lexer vai varrer o código-fonte, avaliando se um ou mais caracteres estão mapeados na linguagem de programação. Esse mapeamento se dá através de um enum contendo todos os tipos aceitos de token!

Interessante, não? Quando a gente escreve nosso código, nem sequer pensa nisso…

Beleza, agora é para valer!

Crie um projeto dotnet do tipo console application e dê o nome que quiser. Nomeei como Pug.Compiler.

Crie uma pasta chamada CodeAnalysis. Todas as classes que vamos criar ficarão dentro dessa pasta.

A primeira coisa que vamos fazer é criar um enum que vai servir para registrar todos os tipos de tokens que suportaremos:

Arquivo CodeAnalysis/TokenType.cs

namespace Pug.Compiler.CodeAnalysis;

public enum TokenType
{
    EOF,

    Number,

    Plus,
    Minus,
    Multiply,
    Divide,

    OpenParenthesis,
    CloseParenthesis
}

Basicamente, temos as quatro operações básicas, um tipo numérico, abre e fecha parênteses e um EOF que indica o fim do arquivo. Esse token é importante, pois define o fim da cadeia de interpretação dos tokens pelo Parser. Veremos isso mais adiante. E diferente do exemplo citado acima, eu não estou mapeando espaços. Durante o desenvolvimento, percebi serem inúteis e simplesmente os ignoro…

Arquivo CodeAnalysis/Token.cs

namespace Pug.Compiler.CodeAnalysis;

public record Token(TokenType Type, string Value, int Position)
{
    public static Token EOF(int position) 
        => new(TokenType.EOF, string.Empty, position);

    public static Token Number(int position, string value) 
        => new(TokenType.Number, value, position);

    public static Token Plus(int position) 
        => new(TokenType.Plus, "+", position);
    public static Token Minus(int position) 
        => new(TokenType.Minus, "-", position);
    public static Token Multiply(int position) 
        => new(TokenType.Multiply, "*", position);
    public static Token Divide(int position) 
        => new(TokenType.Divide, "/", position);

    public static Token OpenParenthesis(int position) 
        => new(TokenType.OpenParenthesis, "(", position);
    public static Token CloseParenthesis(int position) 
        => new(TokenType.CloseParenthesis, ")", position);
}

Esse record não tem segredo. Ele é uma estrutura de dados que armazena informações do token. Quando o Lexer for executado, ele vai extrair uma lista marota de tokens que serão processados pelo Parser. Destaque para o Number que armazena o valor numérico mapeado. Esse valor pode ter um sinal de mais ou de menos, além de ter um ponto para separação decimal. Por exemplo, -1.23, +4.56, 7.89 ou ainda 77.

Além disso, temos métodos auxiliares para a criação de tokens, isso facilita a escrita de código.

Em seguida, um dos principais pilares do nosso compilador: o analisador léxico:

Arquivo CodeAnalysis/Lexer.cs

using System.Text;

namespace Pug.Compiler.CodeAnalysis;

public class Lexer
{
    private readonly string _text;

    private int _currentPosition;
    private char _currentChar;

    private const char EOF = '\0';

    public Lexer(string text)
    {
        _text = text;
        _currentPosition = 0;
        _currentChar = _text.Length > 0 ? _text[_currentPosition] : EOF;
    }

    public List<Token> CreateTokens()
    {
        var tokens = new List<Token>();

        while (_currentChar != EOF)
        {
            if (char.IsWhiteSpace(_currentChar))
            {
                IgnoreWhitespace();
                continue;
            }

            if (_currentChar == '-' && char.IsDigit(Peek()))
            {
                tokens.Add(ExtractNumber());
                continue;
            }

            if (char.IsDigit(_currentChar))
            {
                tokens.Add(ExtractNumber());
                continue;
            }

            var token = _currentChar switch
            {
                '+' => Token.Plus(_currentPosition),
                '-' => Token.Minus(_currentPosition),
                '*' => Token.Multiply(_currentPosition),
                '/' => Token.Divide(_currentPosition),
                '(' => Token.OpenParenthesis(_currentPosition),
                ')' => Token.CloseParenthesis(_currentPosition),
                _ => throw new Exception($"Unexpected character: {_currentChar}")
            };
            tokens.Add(token);

            Next();
        }

        tokens.Add(new Token(TokenType.EOF, string.Empty, _currentPosition));
        return tokens;
    }

    private Token ExtractNumber()
    {
        var result = new StringBuilder();

        if (_currentChar == '-')
        {
            result.Append('-');
            Next();
        }

        var hasDot = false;
        while (char.IsDigit(_currentChar) || _currentChar == '.')
        {
            if (_currentChar == '.')
            {
                if (hasDot)
                    throw new Exception("Invalid number format: multiple dots");

                hasDot = true;
            }

            result.Append(_currentChar);
            Next();
        }

        var value = result.ToString();
        return Token.Number(_currentPosition, value);
    }

    private char Peek()
    {
        var peekPos = _currentPosition + 1;
        return peekPos < _text.Length ? _text[peekPos] : EOF;
    }

    private void Next()
    {
        _currentPosition++;
        _currentChar = _currentPosition < _text.Length ? _text[_currentPosition] : EOF;
    }

    private void IgnoreWhitespace()
    {
        while (char.IsWhiteSpace(_currentChar))
            Next();
    }
}

Vamos analisar passo a passo com muita calma.

Essa implementação não é complexa. Ela talvez não é tão natural para você que está lendo, mas acredite, a extração de tokens é algo razoavelmente tranquilo de se fazer.

O primeiro ponto que precisamos entender é que, essa análise percorre do primeiro ao último caractere do nosso código-fonte. Um por um.

Podemos notar que a nossa classe recebe por parâmetro uma variável chamada _text e em seguida iniciamos duas variáveis, a _currentPosition e a _currentChar.

Os nomes por si só já definem a responsabilidade de cada uma delas. Ao percorrer o nosso texto, teremos um cursor que sempre vai apontar para o caractere atual. E como a nossa leitura é sempre feita para frente, isto é, avançando caractere por caractere, foi criado um método chamado Next que faz esse avanço tomando cuidado para não ultrapassarmos o último caractere ao chegar no final do texto.

Outro método interessante é o Peek. Em alguns casos, é necessário observar o próximo caractere a partir do caractere atual para saber se o fluxo segue avançando ou não. Esse método também assegura que não vamos ultrapassar o último caractere.

Sendo assim, imagine que eu tenha a seguinte expressão: -1234.
Ao percorrer esse texto, eu começo identificando um token chamado Minus. Porém, esse token pode ser usado em dois cenários: para identificar que um número é negativo ou para identificar que existe uma conta de subtração. Lembram daquele lance de desambiguação que eu disse logo acima? Então, temos um exemplo aqui…

Por isso é importante, a partir desse token Minus saber se o próximo caractere é um número ou não.

Nesse momento temos já explicados dois métodos fundamentais para o funcionamento do analisador léxico.

Agora podemos adentrar ao método CreateTokens. Como o próprio nome diz, ele inicializa o processo de varredura (do caractere com índice 0 até o final, EOF) e retorna uma lista de tokens.

Esse é o tipo de método que geralmente não fica bonito. É cheio de if e geralmente é um dos que têm mais linhas no código-fonte do compilador.

Um exemplo parecido, num o contexto um pouco diferente, é o método ScanSyntaxToken do Roslyn ou o método ReadToken do minks criado pelo Immo Landwerth.

O nosso extrator de tokens ainda é modesto perto dos dois citados acima…

Certo, avançamos.

A primeira validação que efetuo é a de verificação se o caractere atual é um espaço em branco. Se sim, inicio o processo que ignora todos os caracteres seguintes que forem espaços.

if (char.IsWhiteSpace(_currentChar))
{
    IgnoreWhitespace();
    continue;
}

Essa validação utiliza o método IgnoreWhitespace que vai avançando caso o próximo caractere em questão seja um espaço vazio.
Isso é para casos do tipo "1 + 3 - 4 *2.

Aliás, curiosamente, em algumas linguagens existem tokens que mapeiam esse caractere, eu resolvi remover para poder diminuir a quantidade de objetos. Não por uma questão de memória — afinal nem me importo aqui com isso — e sim para facilitar o debug.

Um ponto interessante nessas extrações de tokens é que primeiro verifica se o caractere corresponde a algum token type e em seguida caminha para a extração desse token.

Tecnicamente falando, primeiro verifico dentro do while principal if (char.IsWhiteSpace(_currentChar)). Se der match invoco o método IgnoreWhitespace que por sua vez faz a varredura dos próximos caracteres a partir do atual: while (char.IsWhiteSpace(_currentChar)).

Esse é um padrão que se repete…

A seguir temos mais duas validações para números, sendo que a primeira verifica o uso do sinal de negativo no número, e a segunda não.

if (_currentChar == '-' && char.IsDigit(Peek()))
{
    tokens.Add(ExtractNumber());
    continue;
}

if (char.IsDigit(_currentChar))
{
    tokens.Add(ExtractNumber());
    continue;
}

Sei que você pode ter torcido o nariz ao ver essas duas condições que poderiam se tornar uma só. Sim, faz sentido unificá-las, mas eu quis separar em duas, justamente para deixar claro a verificação feita no próximo caractere caso a expressão comece com o sinal de menos. Aquele Peek é muito importante nesse momento e para mim a facilidade na leitura ajuda muito ao debugar o código. Debugar um processo de análise sintática e léxica não é algo tão simples... às vezes dá um brainfuck na gente...

O método ExtractNumber usa o mesmo padrão adotado na validação de espaços em branco. Só que nesse caso verifica se na sequência de caracteres temos números, sinal de menos e ponto separador de decimais. Inclusive, é validado se consta mais de um ponto, se sim, lança uma exceção.

Essa parte do processo valida expressões do tipo -1.234.

A seguir caímos num cenário onde, se não é espaço e se não é número, só pode ser algum desses caracteres: +, -, *, / ( e ). Caso não seja nenhum deles… booooommmm… é lançada uma exception.

Nessa situação nosso querido pattern matching é uma mão na roda…

Considero seriamente rever a ideia de lançar exceções durante a análise léxica e sintática…

Por fim, após percorrer todo o nosso texto, adicionamos o token de EOF(End of File) e finalizamos nossa extração de tokens.

Se você fez faculdade de "Ciências da Computação" e/ou estudou "Autômatos", saiba que a implementação acima nada mais é do que um AFD (Autômato Finito Determinístico (AFD)).

Pensei em falar um pouco sobre ele no momento que eu estava explicando os conceitos de análise léxica e sintática, mas percebi que isso ia deixar o post ainda mais extenso… Mas vale muito a pena estudar isso e destaco aqui alguns links interessantes:

https://home.uevora.pt/~fc/alp/02-automatos_finitos/02.01-afd.html

https://www.youtube.com/watch?v=0W_HK4MYKL8&ab_channel=CarlaQuemDisse

https://www.bcc.unifal-mg.edu.br/~humberto/disciplinas/2011_1_lfa/aulas/aula_06_AutomatosFinitosDeterministicos.pdf

Tokens criados! Agora vamos para a nossa análise sintática.
Nesse caso, eu dei o nome de SyntaxParser para a classe que faz essa análise e execução da expressão. (Muito inspirado por https://github.com/dotnet/roslyn/blob/main/src/Compilers/CSharp/Portable/Parser/SyntaxParser.cs)

Arquivo CodeAnalysis/Parser.cs

namespace Pug.Compiler.CodeAnalysis;

public class SyntaxParser(List<Token> tokens)
{
    private Token CurrentToken => tokens[_currentPosition];

    private int _currentPosition;

    public double Parse()
    {
        var result = EvaluateExpressionWithPriority();

        while (CurrentToken.Type is TokenType.Plus or TokenType.Minus)
        {
            if (CurrentToken.Type == TokenType.Plus)
            {
                CheckToken(TokenType.Plus);
                result += EvaluateExpressionWithPriority();
            }
            else if (CurrentToken.Type == TokenType.Minus)
            {
                CheckToken(TokenType.Minus);
                result -= EvaluateExpressionWithPriority();
            }
        }

        return result;
    }

    private double EvaluateExpressionWithPriority()
    {
        var result = EvaluateToken();

        while (CurrentToken.Type is TokenType.Multiply or TokenType.Divide)
        {
            if (CurrentToken.Type == TokenType.Multiply)
            {
                CheckToken(TokenType.Multiply);
                result *= EvaluateToken();
            }
            else if (CurrentToken.Type == TokenType.Divide)
            {
                CheckToken(TokenType.Divide);
                result /= EvaluateToken();
            }
        }

        return result;
    }

    private double EvaluateToken()
    {
        var token = CurrentToken;

        if (token.Type == TokenType.Plus)
        {
            CheckToken(TokenType.Plus);
            return EvaluateToken();
        }

        if (token.Type == TokenType.Minus)
        {
            CheckToken(TokenType.Minus);
            return -EvaluateToken();
        }

        if (token.Type == TokenType.Number)
        {
            CheckToken(TokenType.Number);
            return double.Parse(token.Value, System.Globalization.CultureInfo.InvariantCulture);
        }

        if (token.Type == TokenType.OpenParenthesis)
        {
            CheckToken(TokenType.OpenParenthesis);
            var result = Parse();
            CheckToken(TokenType.CloseParenthesis);
            return result;
        }

        throw new Exception($"Unexpected token in Evaluate Token: {token.Type}");
    }

    private void CheckToken(TokenType type)
    {
        if (CurrentToken.Type == type)
            _currentPosition++;
        else
            throw new Exception($"Unexpected token: {CurrentToken.Type}, expected: {type}");
    }
}

É meus amigos e minhas amigas. Foi aqui que a porca torceu o rabo. Suei sangue…

Tudo começa com o método Parse onde temos uma varredura de todos os tokens recebidos no construtor da classe.

Da mesma forma que temos um _currentChar na classe de lexer, temos uma propriedade aqui chamada CurrentToken. O conceito aqui é razoavelmente parecido no que diz respeito a avançar entre os tokens. E esse percurso é linear, e não em árvore (AST – Abstract Syntax Tree).

A ideia aqui é fazer avaliação direta (interpretação ou Evaluate, como preferir) durante a análise sintática, ou seja, ele não constrói uma AST, mas já calcula os valores no momento do parsing.

Essa avaliação direta é condicionada a prioridade de execução, tanto que tenho um método que trata somente de expressões e/ou tokens prioritários, EvaluateExpressionWithPriority.

Antes de explicar o fluxo de processamento, quero detalhar o que cada método faz.

CheckToken: valida se o token atual é o esperado durante o processo - aonde vamos avançando dentro de um looping —, se não for, uma exceção é lançada. A cada verificação avanço o ponteiro _currentPosition. Resolvi criar esse método já que ele é muito usado e o código ficou muito repetitivo. Na explicação mais abaixo, vai ficar claro o uso dele, quando eu usar o termo "avança".

EvaluateToken: avança recursivamente na lista de tokens.
Ao encontrar um token do tipo Plus, avança e aplica a recursão. No caso do token Minus faz o mesmo, porém invertendo o sinal do valor do token (-EvaluateToken).
O próximo token a ser tratado é o Number. Ao encontrá-lo, transforma em um tipo double e retorna (durante a recursão, se o token anterior fosse um Minus, seu valor será invertido pelo -.
Por fim, o método avança para encontrar parênteses. Basicamente ele, ao encontrar um token OpenParenthesis, avança e recomeça o processo invocando o método Parse.
Depois do fluxo terminar, ele avança até o CloseParenthesis e retorna o valor processado.

Parse e EvaluateExpressionWithPriority tem um fluxo parecido. A diferença está na ordem de execução. O Parse inicia invocando o EvaluateExpressionWithPriority para efetuar o processo descrito acima pelo método EvaluateToken. Em seguida ele executa as operações de soma e subtração. Nesse ponto já temos a execução do cálculo que vai se agregando a cada iteração.

Talvez não tenha ficado tão claro explicando método por método, porém agora, acredito que vai ficar mais simples "visualizar" esse processo.

Mas antes bora voltar uns 20 anos no tempo… ou mais… enfim…

Logo no primário a gente aprende que "Primeiro se resolve o que está entre parênteses e depois o que está fora" e depois que "Operações de multiplicação e divisão se resolvem antes que operações de soma e subtração" e ainda que a ordem de resolução segue a ordem descrita na expressão (da esquerda para a direita).

Por exemplo, na expressão 1 + 2 * (3 - 4) temos a seguinte ordem de execução:

Primeiro passo, calcula o que está entre parênteses: 3-4=−1
Segundo passo, efetua a multiplicação: 2*−1=−2
Terceiro passo, faz a soma: 1+(−2)=−1

Sendo assim, o fluxo de execução ficou:

Parse chama EvaluateExpression que chama EvaluateToken.
EvaluateToken consome 1.
De volta ao EvaluateExpressionWithPriority, não há * ou / logo, retorna 1.
De volta ao Parse, avança até +, consome e chama EvaluateExpressionWithPriority novamente.
EvaluateExpressionWithPriority chama EvaluateToken dessa vez consumindo o 2.
Avançando encontra *, consome e chama EvaluateToken que consome (, entra recursivamente em Parse para reiniciar um processo, dessa vez com prioridade.
Avança, abre o parêntese e temos 3 - 4. EvaluateExpression consome 3e avança até -, consome e avança até 4, consome e processa o valor retornando -1
Fecha parêntese e retorna -1

Nesse momento executamos o primeiro passo descrito acima. Olha o trabalho gigantesco para chegar no resultado prioritário! Seguindo...

Consome 2, avança até * e efetua o cálculo com o -1 processado gerando -2

Fechamos os segundo passo…

Consome 1, avança até + e efetua o cálculo com o (-2) resultando o valor de -1.

Todo esse trabalho para executar uma tarefa "simples"…
Espero que você tenha entendido a sacada da recursividade. Debugar esse processo ajuda a gente a entender o fluxo. Demorei horas para ajustar esse código. Inclusive acho que o nome dos métodos poderiam ser melhores, talvez eu ajuste isso num futuro…

Enfim, fechamos o fluxo. Agora precisamos testar!

Arquivo Program.cs

using Pug.Compiler.CodeAnalysis;

while (true)
{
    try
    {
        Console.Write("> ");
        var input = Console.ReadLine();
        if (string.IsNullOrEmpty(input) || input.Equals(":q", StringComparison.CurrentCultureIgnoreCase))
            break;

        var lexer = new Lexer(input);
        var tokens = lexer.CreateTokens();

        var parser = new SyntaxParser(tokens);
        var result = parser.Parse();

        Console.WriteLine(result);
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex.Message);
    }
}

A ideia aqui é criar um REPL simples que obtém um texto escrito via console, valida se não é um comando para sair :q e começa a jornada de "interpretação" e "execução" de expressões.

Primeiro invocamos o método CreateTokens do lexer e depois repassamos a lista para o nosso Parser que por sua vez nos dá o resultado da operação:

Se tudo der certo e nada der errado, temos o nosso interpretador de expressões numéricas!

> 1+2+3
6
> -1+-2
-3
> --1
1
> (1+2) * (3+4)
21
> ((((((1+2)
Unexpected token: EOF, expected: CloseParenthesis
> \o/
Unexpected character: \

Chegamos ao fim da primeira parte do post.
Você vai poder acessar o repositório clicando em: https://github.com/angelobelchior/Pug.Compiler/tree/parte1

Essa primeira parte foi densa, com muito conteúdo. Mas eu preferi assim, para pavimentar a escrita dos próximos posts de forma mais direta.

Eu precisava passar por alguns conceitos, principalmente de lexer e parser e espero que você, meu caro leitor, minha cara leitora, tenha entendido.

Vocês não imaginam a minha felicidade ao conseguir construir isso. Sério. É um pequeno avanço, de uma longa jornada.

E eu me divirto! Muito!!!

E espero que vocês também!

Caso tenham alguma dúvida, por favor, deixem nos comentários.

Forte abraço, até a próxima, bebam água e cuidado que está rolando muito caso de Dengue…

Reinventando a Roda: Criando seu próprio MediatR - Parte 3

Angelo Belchior — Wed, 30 Apr 2025 00:25:00 +0000

No caminho o que importa é o caminho...
...e não o porto e ponto final!

Chegamos ao fim da série. Mas a Ave Sangria nos ensina que o mais importante é a jornada. E de fato é isso. Foram três posts destrinchando trechos de código e explicando decisões técnicas, porém o mais importante não é o resultado, já que temos inúmeras bibliotecas que fazem a mesma coisa, e sim entender que é possível resolver problemas de forma efetiva. E a gente só consegue fazer isso codando! Pensando e codando!

É isso que eu gostaria que você meu caro leitor, minha cara leitora entendesse. Por mais que tenhamos um monte de ferramentas com inteligência artificial nos ajudando, precisamos saber bem como resolver problemas. Precisamos entender bem como as coisas funcionam. E, acima de tudo, precisamos usar as ferramentas que temos em mãos, mas com a certeza do seu entendimento, da sua aplicabilidade.

Bom, a única feature faltante em nossa biblioteca é a de notificações. A principal diferença entre um handler e uma notification é que o request/command aciona apenas um request handler. Já a notification pode ser "ouvida" por inúmeros notification handlers.

As notificações servem para propagar eventos de forma totalmente desacoplada. Quando uma parte da aplicação quer informar que algo aconteceu, ela pode publicar essa mensagem e quem estiver ouvindo pode executar uma ação.

Vamos imaginar que um usuário acabe de efetuar uma compra no seu sistema de e-commerce.
Nesse momento pode-se emitir uma mensagem "Pedido efetuado com sucesso". Essa é a notificação.
Podemos ter três partes distintas do próprio sistema que ouvem essa mensagem:

A primeira vai enviar um e-mail com todas as informações da compra.
A segunda interage com um sistema externo para obter informações sobre rastreio.
A terceira registra o evento em um sistema interno de auditoria para manter o histórico das operações realizadas pelos usuários.

Se você trabalha com sistemas de mensageria como RabbitMQ por exemplo, pode achar que esse processo poderia enviar a mensagem para um tópico ou fila e ter background services efetuando o processamento etc. Você está certo! Mas esse foi o exemplo que achei ser mais didático para explicar a parte de notificações...

Se você acompanhou essa trilogia (parte 1 e parte 2), já deve imaginar como implementar isso. Se não consegue imaginar, não tem problema, eu explico. A ideia é seguir o mesmo conceito do RequestHandler, a diferença é que não podemos ter mais de um RequestHandler para um Request/Response e no caso do NotificationHandler podemos ter isso.

Antes de avançar, pegue aquela Fanta Uva misturada com Yakult e vem comigo.

Bora relembrar a estrutura do nosso projeto?

TheMediator.Core
├── DependencyInjection/
│   └── DependencyInjection.cs
├── Executors/
│   ├── FilterExecutor.cs
│   └── HandlerExecutor.cs
├── Inspectors/
│   └── ServiceInspector.cs
├── Models/
│   ├── ServiceCategory.cs
│   ├── ServiceDescriptor.cs
│   └── Void.cs
├── Registries/
│   ├── FilterRegistry.cs
│   └── HandlerRegistry.cs
├── IRequestFilter.cs
├── IRequestHandler.cs
├── ISender.cs
└── Usings.cs

Posto isso, precisamos criar nossa interface principal, um registrador e um executor de Notification Handlers além de ajustar nossa classe de injeção de dependência para suportar o registro de notificações.

A interface é simples e objetiva:

public interface IRequestHandler<in TRequest, TResponse>  
  where TRequest : notnull  
{  
    Task<TResponse> HandleAsync(TRequest request, CancellationToken cancellationToken);  
}  

public interface IRequestHandler<in TRequest>  
  where TRequest : notnull  
{  
    Task HandleAsync(TRequest request, CancellationToken cancellationToken);  
}

Basicamente temos duas interfaces, uma para handlers com TRequest e outra para Handlers com TRequest e TResponse. A essa altura do campeonato, com dois posts falando exaustivamente disso, acredito que não preciso explicar o motivo, certo? ;p

Agora vamos implementar nosso querido NotifierRegistry...

Arquivo Registries/NotifierRegistry.cs:

public class NotifierRegistry(IServiceCollection services)
{
    private readonly List<Models.ServiceDescriptor> _notifications = new();

    [ExcludeFromCodeCoverage]
    public NotificationConfiguration Configurations { get; set; } = NotificationConfiguration.None;

    public void Add<TService>()
        where TService : notnull
    {
        var mainType = typeof(TService);
        var service = ServiceInspector.CreateService(mainType, ServiceCategory.Notification);
        Add(service);
    }

    internal void Add(Models.ServiceDescriptor serviceDescriptor)
    {
        if (serviceDescriptor.Category != ServiceCategory.Notification)
            throw new InvalidOperationException($"{serviceDescriptor.MainType} is not a notification type!");

        var current = _notifications.FirstOrDefault(s =>
            s.MainType == serviceDescriptor.MainType &&
            s.RequestType == serviceDescriptor.RequestType &&
            s.ResponseType == Models.Void.Type &&
            s.Category == serviceDescriptor.Category);
        if (current is not null)
            throw new InvalidOperationException(
                $"Cannot register {serviceDescriptor.MainType}!.\n" +
                $"The Notification {current.MainType} is already registered");

        _notifications.Add(serviceDescriptor);
        services.AddSingleton(serviceDescriptor.MainType);
    }

    internal IReadOnlyCollection<Models.ServiceDescriptor> ListNotifiersByMessageType<TMessageType>()
        => _notifications.Where(s => s.RequestType == typeof(TMessageType) &&
                                     s.ResponseType == Models.Void.Type &&
                                     s.Category == ServiceCategory.Notification).ToList();
}

Essa classe é bem simples de se entender. Ela armazena uma lista de ServiceDescriptor através de dois métodos: Add<TService>() e Add(Models.ServiceDescriptor serviceDescriptor). O primeiro cria um ServiceDescriptor a partir do tipo de serviço (TService) e repassa ao segundo que por sua vez valida se esse mesmo já não foi registrado, caso não tenha sido, adiciona na lista. E ao armazenar, adiciona no sistema de injeção de dependências o tipo inserido.

Note que é possível ter vários tipos de Notification Handlers associados a uma mensagem, mas não podemos ter dois Notification Handlers iguais, isto é, como mesmo MainType.
Se não ficou claro, explico: Não é possível ter dois Notification Handlers do tipo EnviaEmailDeBoasVindasHandler registrados. A mesma classe não pode ser registrada duas vezes, é isso...

NotificationConfiguration é uma classe para configurar como a notificação vai ser enviada (e num futuro ter outras opções). Explico mais abaixo.

E por fim temos ListNotifiersByMessageType<TMessageType>() que retorna uma lista de Notification Handlers a partir do TMessageType. Esse é o método usado pelo executor no momento de envio da notificação.

Um ponto importante é que não é necessário executar uma notificação em uma ordem específica, diferente dos filtros.

Arquivo Models/NotificationConfiguration.cs:

public class NotificationConfiguration(NotificationDeliveryMode deliveryMode)  
{  
  public NotificationDeliveryMode DeliveryMode { get; set; } = deliveryMode;  

  //TODO: implementar outras configurações...
}

public enum NotificationDeliveryMode  
{  
  FireAndForget,  
  WaitAll  
}

Ao enviar uma notificação podemos optar se esse envio vai ser FireAndForget, isto é, eu envio a notificação, mas não aguardo seu retorno, ou se eu espero todos os Notification Handlers executarem suas ações, WaitAll.

Esse comportamento é importante já que tem casos que eu não preciso me preocupar com quem está consumindo a mensagem, logo, seu retorno é indiferente.
Porém existem casos que é necessário aguardar o processamento da mensagem.
No caso da nossa biblioteca, a pessoa desenvolvedora escolhe...

Um ponto mais do que importante: Ao utilizar o modo FireAndForget caso o Notification Handler lance uma exception não tem como efetuar a captura por parte de quem enviou a notificação. Isso acontece pelo fato de não aguardarmos a finalização do método. Logo, é importante efetuar o tratamento de exceções dentro do Notification Handler...

E...

Outro ponto não menos importante: Caso escolha WaitAll tenha em mente que o processo todo pode demorar muito dependendo da quantidade Notification Handlers registrados. O lado positivo é que caso algum deles lance uma exceção é possível capturá-la. Não tem mágica: Chora Agora ou Ri depois...

Vamos ao executor...

Arquivo Executors/NotifierExecutor.cs:

public class NotifierExecutor(
    ILogger<NotifierExecutor> logger,
    IServiceProvider serviceProvider,
    NotifierRegistry notifierRegistry)
{
    public async Task PublishAsync<TMessage>(TMessage message, CancellationToken cancellationToken)
        where TMessage : notnull
    {
        var services = notifierRegistry.ListNotifiersByMessageType<TMessage>();
        var channel = Channel.CreateBounded<Func<Task>>(new BoundedChannelOptions(services.Count));

        var sender = Task.Run(() => SendNotificationsAsync(message, services, channel, cancellationToken), cancellationToken);
        var receiver = Task.Run(() => ExecuteHandlersAsync(channel, cancellationToken), cancellationToken);

        await Task.WhenAll(sender, receiver);
    }

    private async Task ExecuteHandlersAsync<TMessage>(
        TMessage message,
        IReadOnlyCollection<Models.ServiceDescriptor> services,
        Channel<Func<Task>> channel,
        CancellationToken cancellationToken)
        where TMessage : notnull
    {
        logger.LogInformation("Publishing message {MessageType} to {NotificationCount} notifications",
            typeof(TMessage).Name, notificationsType.Count);

        try
        {
            foreach (var serviceDescriptor in services)
            {
                var handler = (INotificationHandler<TMessage>)serviceProvider.GetRequiredService(serviceDescriptor.MainType);
                await channel.Writer.WriteAsync(() =>
                {
                    logger.LogInformation("Sending message {MessageType} to {HandlerType}",
                        typeof(TMessage).Name, serviceDescriptor.MainType.Name);

                    return handler.HandleAsync(message, cancellationToken);
                }, cancellationToken);
            }
        }
        finally
        {
            channel.Writer.Complete();
        }
    }

    private async Task ReceiveNotificationsAsync(
        Channel<Func<Task>> channel,
        CancellationToken cancellationToken)
    {
        while (await channel.Reader.WaitToReadAsync(cancellationToken))
        {
            while (channel.Reader.TryRead(out var handlerTask))
            {
                if (notifierRegistry.Configurations.DeliveryMode == NotificationDeliveryMode.FireAndForget)
                    _ = Task.Run(handlerTask, cancellationToken).ConfigureAwait(false);
                else
                    await handlerTask();
            }
        }
    }
}

Como você pode imaginar, a classe NotifierExecutor é responsável por publicar mensagens para notificações registradas, utilizando um mecanismo de processamento assíncrono baseado em channels. O uso de channels permite gerenciar a comunicação entre produtores (quem envia as notificações) e consumidores (quem processa as notificações) de forma eficiente e segura em cenários concorrentes, que é o nosso caso.

Eu fiz um post falando sobre channels: Você já usou o System.Threading.Channels?. Recomendo muito a leitura desse post...

Caso você não tenha lido o post, vou fazer um resumo resumido aqui sobre channels:

O Channel é uma estrutura do dotnet que fornece um buffer seguro para comunicação entre tarefas assíncronas, thread-safe na veia! Ele é composto por dois componentes principais: Writer, componente usado para adicionar itens ao canal e o Reader, usado para, vejam só, consumir itens do canal.

Basicamente, essa biblioteca permite que a gente transmita dados de forma segura e sincronizada entre threads, tudo isso com muita performance. Muita mesmo. Aliás, esse é um dos segredos por de trás da performance absurda do Asp.Net Core.

O mais legal é que com Channels podemos desacoplar a produção e o consumo de tarefas, permitindo que ambas as operações sejam executadas em velocidades diferentes sem bloquear diretamente uma à outra.
No caso do NotifierExecutor, isso é essencial para gerenciar múltiplos handlers de notificações de forma eficiente.

Avançando, temos um método chamado PublishAsync<TMessage>. É aqui que o canal é criado e delimitamos a sua capacidade (Channel.CreateBounded) para a quantidade de handlers registrados para a mensagem. Cada item no canal é uma função (Func<Task>) que representa a execução de um handler de notificação.

O método SendNotificationsAsync é responsável por "varrer" os serviços registrados e adicionar as Func<Task> ao canal que, quando executadas, chamam o método HandleAsync de cada handler. Isso é feito de forma assíncrona, garantindo que o canal seja preenchido com as tarefas a serem processadas. Aqui temos o Write.

Já o Reader é feito dentro do método ExecuteHandlersAsync. Nele as Func<Task> são recebidas e executadas. Dependendo da configuração de entrega (NotificationDeliveryMode, lembra?), as tarefas podem ser executadas no modo FireAndForget, não aguardando a conclusão, ou WaitAll, aguardando a conclusão de cada tarefa.

Aliás, na parte do FireAndForget você notou o .ConfigureAwait(false)? Sabe pra que ele serve? Se não sabe, fiz um post garboso demais sobre o assunto: Async/Await: Task.ConfigureAwait, Deadlock e Pink Floyd.

Uma coisa que eu acho super bacanuda é o fato de ser muito simples resolver esse problema de envio de mensagens para inúmeros handlers usando channels. Nós temos uma classe simples, com umas 60 linhas e que resolve de forma muito performática esse problema.

O dotnet tem um conjunto de ferramentas espetaculares e é por isso que eu sempre recomendo ir a fundo no framework. É possível criar qualquer coisa com muita performance. Qualquer coisa mesmo!

Avancemos!

Agora precisamos criar a interface para publicação e sua implementação.

Arquivo IPublisher.cs:

public interface IPublisher  
{  
    Task PublishAsync<TMessage>(TMessage message, CancellationToken cancellationToken)  
      where TMessage : notnull;  
}  

internal class Publisher(NotifierExecutor notifierExecutor) : IPublisher  
{  
    public Task PublishAsync<TMessage>(TMessage message, CancellationToken cancellationToken)  
      where TMessage : notnull  
      => notifierExecutor.PublishAsync(message, cancellationToken);  
}

O código é autoexplicativo. Pegamos o NotifierExecutor e invocamos o método PublishAsync. Simples assim. A lógica toda foi explicada logo acima.

Certo, chegamos à parte final do post. E consequentemente da série.

Para fechar a conta e passar a régua precisamos ajustar nossa classe de injeção de dependência.

Arquivo DependencyInjection/DependencyInjection.cs:

No método AddTheMediator adicionamos o NotifierRegistry e o IPublisher no sistema de injeção de dependências :

...
services.AddSingleton<NotifierRegistry>(_ => configuration.Notifiers);

...

services.AddSingleton<IPublisher, Publisher>();

E na classe Configuration que fica dentro da classe DependencyInjection temos:

...

public NotifierRegistry Notifiers { get; } = new(services);

public Configuration AddServicesFromAssemblies(params Assembly[] assemblies)  
{  
    if (assemblies is null || assemblies.Length == 0)  
       throw new ArgumentNullException(nameof(assemblies), "Assemblies cannot be null or empty.");  

    assemblies .Select(ServiceInspector.GetServicesByAssembly)  
               .SelectMany(serviceType => serviceType)  
               .ToList()  
               .ForEach(serviceDescriptor =>  
               {  
                   if (serviceDescriptor.Category == ServiceCategory.Handler)  
                       Handlers.Add(serviceDescriptor);  
                   if (serviceDescriptor.Category == ServiceCategory.Notification)  
                       Notifiers.Add(serviceDescriptor);  
               });  
    return this;  
}

Criamos uma propriedade chamada Notifiers que nada mais é que o NotifierRegistry e no método AddServicesFromAssemblies incluímos o serviceDescriptor na lista de notificações. Não tem segredo!

Fechamos a conta. Agora vamos passar a régua!

Vamos configurar nosso playground para emitir notificações.

Arquivo Program.cs:

builder.Services.AddTheMediator(configuration =>  
{  
    configuration.AddServicesFromAssemblies(typeof(Program).Assembly);  

    configuration.Notifiers.Configurations.DeliveryMode = NotificationDeliveryMode.FireAndForget;  

    configuration.Filters.Add<MeasureTimeRequestFilter>();  
    configuration.Filters.Add<LoggerRequestFilter>();  
});

A única diferença é o NotificationDeliveryMode configurando o modo de envio como FireAndForget.

Agora vamos criar nosso primeiro Notification Handler:

Arquivo Notifications/CreateProductNotification.cs:

public class CreateProductNotification(ILogger<CreateProductNotification> logger)  
    : INotificationHandler<ProductResponse>  
{  
    public async Task HandleAsync(ProductResponse notification, CancellationToken cancellationToken)  
    {  
        logger.LogInformation("{Class} Product {ProductName} created", nameof(CreateProductNotification),  
 notification.Name);  
        await Task.Delay(1500, cancellationToken);  
    }
 }

E para fechar, vamos alterar nosso handler CreateProductRequestHandler:

public class CreateProductRequestHandler(IPublisher publisher, IProductsRepository repository)  
    : IRequestHandler<ProductRequest, ProductResponse>  
{  
    public async Task<ProductResponse> HandleAsync(ProductRequest request, CancellationToken cancellationToken)  
    {  
        var response = await repository.Create(request, cancellationToken);  
        await publisher.PublishAsync(response, cancellationToken);  
        return response;  
 }}

Injetamos o IPublisher e invocamos o método PublishAsync passando o Response. Simples, simples, simples!

Agora dê um F5 e veja a mágica acontecer no console da aplicação.

...
info: TheMediator.Core.Executors.HandlerExecutor[0]
      Handler CreateProductRequestHandler for request type ProductRequest and response type ProductResponse executed successfully
info: TheMediator.Core.Executors.NotifierExecutor[0]
      Publishing message ProductResponse to 1 notifications
info: TheMediator.Core.Executors.NotifierExecutor[0]
      Sending message ProductResponse to CreateProductNotification
info: TheMediator.Playground.Notifications.CreateProductNotification[0]
      CreateProductNotification Product Playstation 5 created
...

Lindo, não? Eu omito alguns logs para poder focar no que importa: O envio da notificação.

Ahhh, você deve ter reparado naquele await Task.Delay(1500, cancellationToken) da classe CreateProductNotification, certo?

Faça o seguinte teste: Configure o NotificationDeliveryMode para WaitAll e rode novamente o Playground. Você vai notar que o processo vai esperar pela execução da notificação.

Brinque com o playground. Crie outras notificações. Mude o NotificationDeliveryMode e lance exceções dentro dos Handler Notifications. Acompanhe o fluxo da informação. Isso vai te ajudar muito a entender como as coisas funcionam.

E chegamos ao fim da nossa saga (aventura e não o padrão de transação entre microservices). Espero que todo esse conteúdo tenha sido útil para você. Para mim foi muito divertido, muito mesmo.

Lembrando que o código fonte está disponível em https://github.com/angelobelchior/TheMediator.

Um ponto interessante é que o código do repositório está mais atualizado do que o código do post. Não tem nada de tão relevante, apenas pequenos ajustes e outras melhorias...

Divirta-se e forte abraço.

Reinventando a Roda: Criando seu próprio MediatR - Parte 2

Angelo Belchior — Sat, 19 Apr 2025 15:13:13 +0000

Nada do que foi será...
De novo do jeito que já foi um dia...

Confesso que não conheço muito a carreira do Lulu Santos, mas esse trecho define bem o que apresentaremos nesse post!

Eu recomendo muito que você leia o post anterior Reinventando a Roda: Criando seu próprio MediatR - Parte 1. Nele eu explico a ideia por trás dessa implementação. Eu não vou explicar coisas que foram explicadas lá justamente para não deixar o post gigante!!!!

Assumo aqui que você, de fato, leu o post anterior. Sendo assim, saiba que tudo aquilo que eu fiz foi refeito. Praticamente todo código que eu escrevi, foi reescrito. E o motivo talvez não seja forte o suficiente, mas é o que tem para hoje: Eu comecei com a ideia de criar um Mediator da forma mais simples possível - o que foi entregue no primeiro post - porém, ao avançar para a criação dos filtros de handlers percebi que precisava deixar o código mais organizado, limpo e acima de tudo testável. Pois bem, é o que será entregue nesse segundo post.

Mas não se preocupe, eu vou repassar por todas as classes novamente, explicando as definições e decisões, e no fim tenho certeza de que você meu caro leitor, minha cara leitora, vai concordar que ficou melhor. (Inclusive me atiça a ideia de empacotar essa lib e distribuir... não sei... se você gosta da ideia, poste aí nos comentários...)

Café tá caro... pega um Kisuco de Morango e vem comigo...

Primeiramente, temos a seguinte estrutura do projeto:

TheMediator.Core
├── DependencyInjection/
│   └── DependencyInjection.cs
├── Executors/
│   ├── FilterExecutor.cs
│   └── HandlerExecutor.cs
├── Inspectors/
│   └── ServiceInspector.cs
├── Models/
│   ├── ServiceCategory.cs
│   ├── ServiceDescriptor.cs
│   └── Void.cs
├── Registries/
│   ├── FilterRegistry.cs
│   └── HandlerRegistry.cs
├── IRequestFilter.cs
├── IRequestHandler.cs
├── ISender.cs
└── Usings.cs

Note que agora temos clareza de todos os componentes do nosso Mediator.

DependencyInjection/DependencyInjection.cs: Configura a injeção de dependências do nosso querido TheMediator.Core.
Executors/FilterExecutor.cs: Executa os filtros registrados para processar requisições antes ou depois de serem manipuladas.
Executors/HandlerExecutor.cs: Executa os handlers registrados para processar as requisições (com ou sem retorno TRequest). O HandlerExecutor utiliza o FilterExecutor no processo de execução da request.
Inspectors/ServiceInspector.cs: Inspeciona os tipos obtidos pelos assemblies passados como parâmetro e cria os seus respectivos serviços.
Models/ServiceCategory.cs: Representa uma categoria de serviço, usada para organizar ou classificar serviços (Handler, Filter e no futuro Notification).
Models/ServiceDescriptor.cs: Descreve um serviço. MainType, RequestType, ResponseType e ServiceCategory.
Registries/FilterRegistry.cs: Registra e gerencia os filtros disponíveis no sistema.
Registries/HandlerRegistry.cs: Registra e gerencia os handlers de requisições disponíveis no sistema.
IRequestFilter.cs: Define a interface para filtros que podem ser aplicados às requisições.
IRequestHandler.cs: Define a interface para os handlers de requisições.
ISender.cs: Define a interface para enviar requisições e obter respostas. Dentro desse arquivo temos a implementação dessa mesma interface. A ideia é que o Sender consiga invocar os handlers utilizando o HandlerExecutor e enviar notificações utilizando um NotificationExecutor. Como pode notar nós não temos nada de notificação nessa versão. No próximo post nós vamos efetuar essa implementação.
Usings.cs: Centraliza os using comuns para facilitar a manutenção e reduzir redundâncias no código.

Seguindo essa estrutura, para adicionarmos um sistema de notificação, precisamos basicamente criar um Registry para registar todas as classes que enviam notificação, e um Executor para propagar todas as mensagens. Próximo post vai ficar show de bola, garanto!

De qualquer forma, vamos passar classe a classe explicando tudinho.

Os arquivos IRequestFilter.cs, IRequestHandler.cs e ISender.cs são praticamente iguais. Se você leu o post anterior já sabe o que eles fazem, inclusive o IRequestFilter que segue a mesma ideia do IRequestHandler.

A principal diferença é que o IRequestFilter tem um argumento chamado Func<Task> next no método FilterAsync. Mais a frente eu explico o que ele faz.

O Usings.cs já foi descrito acima...

Arquivo DependencyInjection/DependencyInjection.cs

public static class DependencyInjection
{
    public static IServiceCollection AddTheMediator(
        this IServiceCollection services,
        Action<Configuration> configurator)
    {
        var configuration = new Configuration(services);
        configurator(configuration);

        services.AddSingleton<HandlerRegistry>(_ => configuration.Handlers);
        services.AddSingleton<FilterRegistry>(_ => configuration.Filters);
        //services.AddSingleton<NotificationRegistry>(_ => configuration.Notifications);

        services.AddSingleton<FilterExecutor>();
        //services.AddSingleton<NotificationExecutor>();
        services.AddSingleton<HandlerExecutor>();

        services.AddSingleton<ISender, Sender>();

        return services;
    }

    public class Configuration(IServiceCollection services)
    {
        internal HandlerRegistry Handlers { get; } = new(services);
        internal FilterRegistry Filters { get; } = new(services);
        //internal NotificationRegistry Notifications { get; } = new(services);

        public Configuration AddServicesFromAssemblies(params Assembly[] assemblies)
        {
            if (assemblies is null || assemblies.Length == 0)
                throw new ArgumentNullException(nameof(assemblies), "Assemblies cannot be null or empty.");

            assemblies
                .Select(ServiceInspector.GetServicesByAssembly)
                .SelectMany(serviceType => serviceType)
                .ToList()
                .ForEach(serviceDescriptor =>
                {
                    if (serviceDescriptor.Category == ServiceCategory.Handler)
                        Handlers.Add(serviceDescriptor);

                    //TODO: Incluir notificações...
                    // if (serviceDescriptor.Category == ServiceCategory.Notification)
                    //     Notifications.Add(serviceDescriptor);
                });

            return this;
        }

        public Configuration AddFilter<TFilter>()
            where TFilter : class, IRequestFilter
        {
            Filters.Add<TFilter>();
            return this;
        }
    }
}

A classe DependencyInjection adiciona o método de extensão AddTheMediator ao ServiceCollection. Isso é bem comum de se ver em bibliotecas. Dentro dessa classe temos uma outra classe chamada Configuration que como o nome sugere, ajuda na configuração do nosso Mediator. Gosto dessa abordagem de uma classe dentro da outra.

Logo, o uso da nossa biblioteca se inicia à partir do método AddTheMediator. Ao invocá-lo devemos passar uma Action onde podemos acionar métodos da classe Configuration. É nesse momento que nós informamos ao nosso Mediator quais são os handlers e filters existentes no sistema. Esse processo mudou pouco em relação ao post anterior.

Note que podemos adicionar handlers e no futuro notifications de duas formas:

Varrendo os assemblies, identificando e registrando os tipos respectivos;
Ou informando manualmente através dos métodos Handlers.Add<THandler> e futuramente Notifications.Add<TMessage>;

Na teoria, é mais simples usar o AddServicesFromAssemblies, mas obviamente informar tipo por tipo acaba sendo mais performático. Não que carregar a partir de assemblies seja tããão ruim, mas o processo abre o objeto a procura de tipos de dados específicos e osso tem um custo. Eu particularmente não vejo problema nisso...

O método AddServicesFromAssemblies percorre a lista de assemblies e invoca o ServiceInspector.GetServicesByAssembly criando uma lista de Services com os tipos pré-estabelecidos. Abaixo veremos como isso é feito.

Com o Service criado, enviamos ele ou ao HandlerRegistry ou futuramente ao NotificationRegistry onde serão devidamente registrados no sistema de injeção de dependência.

Além dos Handlers também podemos informar os Filters. Só que manualmente, um por um!

E talvez aqui surja uma pergunta: Eu não poderia carregar os filtros da mesma forma que eu faço com os Handlers?

A resposta é não!

Os filtros precisam manter uma ordem sequencial de execução. Logo, eu preciso registrá-los um a um na ordem que eu quero que eles sejam executados.

Handlers e Notifications podem ser registrados em qualquer ordem, já que eles são invocados diretamente.

Arquivo Inspectors/ServiceInspector.cs

internal class Void;

internal static class ServiceInspector
{
    private static readonly List<Type> HandlerTypes =
    [
        typeof(IRequestHandler<,>),
        typeof(IRequestHandler<>)
    ];

    private static readonly List<Type> FilterTypes =
    [
        typeof(IRequestFilter)
    ];


    public static IEnumerable<Models.ServiceDescriptor> GetServicesByAssembly(
        Assembly assembly)
    {
        var types = assembly.GetTypes()
            .Where(t => t.IsClass && t is { IsAbstract: false, IsGenericType: false });

        foreach (var type in types)
        {
            var interfaces = type.GetInterfaces().Where(i => i.IsGenericType);
            foreach (var @interface in interfaces)
            {
                var genericType = @interface.GetGenericTypeDefinition();
                if (HandlerTypes.Contains(genericType))
                    yield return CreateService(type, ServiceCategory.Handler);
                if (FilterTypes.Contains(genericType))
                    yield return CreateService(type, ServiceCategory.Filter);
                //TODO: Incluir Notifications
                // if (NotificationTypes.Contains(genericType))
                //     yield return CreateService(type, ServiceCategory.Notification);
            }
        }
    }

    public static Models.ServiceDescriptor CreateService(
        Type mainType,
        ServiceCategory serviceCategory)
    {
        var types = serviceCategory == ServiceCategory.Filter ? FilterTypes : HandlerTypes;

        foreach (var type in types)
        {
            var interfaceType = GetMatchingInterface(mainType, type);
            if (interfaceType is null)
                continue;

            return CreateServiceFromInterface(mainType, interfaceType, serviceCategory);
        }

        throw new InvalidOperationException(
            $"The type {mainType} does not implement a valid handler or filter handler interface.");
    }

    internal static Models.ServiceDescriptor CreateServiceFromInterface(
        Type mainType,
        Type interfaceType,
        ServiceCategory serviceCategory)
    {
        var @void = typeof(Void);
        var genericArguments = interfaceType.GetGenericArguments();

        return genericArguments.Length switch
        {
            0 => new Models.ServiceDescriptor(mainType, @void, @void, serviceCategory),
            1 => new Models.ServiceDescriptor(mainType, genericArguments[0], @void, serviceCategory),
            _ => new Models.ServiceDescriptor(mainType, genericArguments[0], genericArguments[1], serviceCategory)
        };
    }
}

internal static Type? GetMatchingInterface(Type mainType, Type type)
{
    var allInterfaces = mainType.GetInterfaces();

    return allInterfaces.FirstOrDefault(i =>
               i.IsGenericType && i.GetGenericTypeDefinition() == type) ??
           allInterfaces.FirstOrDefault(i => i == type);
}

Esse arquivo segue a mesma ideia do famigerado TypeInspector.cs apresentado no post anterior. Aliás, eu apenas renomeei.

O método GetServicesByAssembly tem como finalidade abrir um Assembly e procurar por uma lista específica de tipos, nesse momento IRequestHandler e IRequestFilter.
Ao obter um tipo que implemente alguma dessas interfaces, ele cria um ServiceDescriptor (antigo ServiceTypes) informando qual é a categoria desse serviço:

internal enum ServiceCategory  
{  
  Handler,  
  Filter,  
  //Notification  
}

Dessa maneira, numa passada só pelos assemblies, eu tenho uma lista de handlers e futuramente uma lista de Notifications.

CreateService é um método utilizado no momento que se registra um Service manualmente, já que eu preciso informar o mainType e o serviceCategory. A partir do mainType sabemos qual interface de serviço ele implementa (IRequestHandler<,>, IRequestHandler<>, IRequestFilter e no futuro INotificationHandler) e com isso temos nosso ServiceDescriptor preenchido bonitinho com tudo que precisamos!

Inclusive temos o tipo Void! Olha ele aí novamente!!! Se você leu o post anterior sabe para que ele serve :)

Já o método GetMatchingInterface verifica se o tipo principal (mainType) implementa uma interface que corresponde ao tipo genérico ou não genérico especificado (type). Ele retorna a primeira interface correspondente ou null caso nenhuma seja encontrada.

Por fim, temos o método CreateServiceFromInterface que serve para criar de fato o objeto ServiceDescriptor obtendo da interface de serviço quais tipos genéricos ela espera. A partir deles sabemos qual é o MainType, RequestType, ResponseType e, claro, temos já em mãos o ServiceCategory.

Lembrando que um Filter não tem nem RequestType e nem ResponseType, sendo assim, esses tipos vão receber o glorioso Void!

Já os Handlers podem ter RequestType e/ou ResponseType e futuramente as Notifications terão apenas um MessageType.

O ServiceDescriptor tende a mudar no próximo post, mas não vai ser nada tão grande, é mais para poder abrigar um TMessage também.

Fechamos ServiceInspector!

Registries/FilterRegistry.cs e Registries/HandlerRegistry.cs servem como repositórios de ServiceDecriptors.
Além de armazenar essas informações, esses Registries adicionam o tipo principal (MainType) ao serviço de injeção de dependência.

O HandlerRegistry armazena os ServiceDecriptors num HashSet e no post anterior eu expliquei o motivo.

Já no FilterRegistry eu uso uma Stack! Interessante, não? Quando eu for falar sobre FilterExecutor eu explico o motivo. Mas vai pensando ai...

Arquivo Executors/HandlerExecutor.cs

internal class HandlerExecutor(
    IServiceProvider serviceProvider,
    HandlerRegistry handlerRegistry,
    FilterExecutor filterExecutor)
{
    public Task<TResponse> SendAsync<TRequest, TResponse>(TRequest request,
        CancellationToken cancellationToken)
        where TRequest : notnull
    {
        cancellationToken.ThrowIfCancellationRequested();

        var handlerType = handlerRegistry.GetHandler<TRequest, TResponse>(ServiceCategory.Handler);
        var handlerService = (IRequestHandler<TRequest, TResponse>)serviceProvider.GetRequiredService(handlerType.MainType);

        return filterExecutor.Execute(
            request,
            () => handlerService.HandleAsync(request, cancellationToken),
            cancellationToken);
    }

    public Task SendAsync<TRequest>(TRequest request, CancellationToken cancellationToken)
        where TRequest : notnull
    {
        cancellationToken.ThrowIfCancellationRequested();

        var handlerType = handlerRegistry.GetHandler<TRequest, Void>(ServiceCategory.Handler);
        var handlerService = (IRequestHandler<TRequest>)serviceProvider.GetRequiredService(handlerType.MainType);

        return filterExecutor.Execute(
            request,
            () => handlerService.HandleAsync(request, cancellationToken),
            cancellationToken);
    }
}

Essa classe espera por injeção de dependência um IServiceProvider, HandlerRegistrye umFilterExecutor que são injetados lá no método DependencyInjection.AddMediator.

Os métodos SendAsync<TRequest, TResponse> e SendAsync<TRequest> fazem a mesma coisa. A diferença é que um espera um retorno e o outro não. E o que eles fazem é bem simples!!!

Começamos o método verificando se um cancelamento de token foi solicitado: cancellationToken.ThrowIfCancellationRequested();.

Se você não sabe para que serve um CancellationToken fiz um post exclusivamente para você: # Async/Await: Para que serve o CancellationToken?.

Em seguida eu utilizo o handlerRegistry para obter o handlerType correspondente ao TRequest e/ou TResponse.
Com o handlerType consigo pedir para o sistema de injeção de dependências que obtenha o Handler injetado. Simples assim!

Aliás, se a gente parar para analisar com calma, a mágica toda só acontece porque temos um sistema de injeção de dependências sensacional no dotnet. Se a gente precisasse criar na mão, já sabem, né?

O próximo passo é invocar o filterExecutor.Execute passando a função handlerService.HandleAsync como parâmetro (Func<Task<TResponse>> ou Func<Task> dependendo se tem ou não retorno).
Essa função será executada após todos os filtros registrados serem invocados.

Viu que simples?

Arquivo Executors/FilterExecutor.cs

internal class FilterExecutor(
    IServiceProvider serviceProvider,
    FilterRegistry filterRegistry)
{
    public Task Execute<TRequest>(
        TRequest request,
        Func<Task> function,
        CancellationToken cancellationToken)
        where TRequest : notnull
    {
        var task = filterRegistry.ListFilters()
            .Select(f => (IRequestFilter)serviceProvider.GetRequiredService(f.MainType))
            .Aggregate(
                function,
                (acc, source) => () =>
                {
                    cancellationToken.ThrowIfCancellationRequested();
                    return source.FilterAsync(
                        request,
                        async () =>
                        {
                            await acc();
                            return Models.Void.Null;
                        }, cancellationToken);
                });
        return task();
    }

    public Task<TResponse> Execute<TRequest, TResponse>(
        TRequest request,
        Func<Task<TResponse>> function,
        CancellationToken cancellationToken)
        where TRequest : notnull
    {
        var task = filterRegistry.ListFilters()
            .Select(f => (IRequestFilter)serviceProvider.GetRequiredService(f.MainType))
            .Aggregate(
                function,
                (acc, source) => () =>
                {
                    cancellationToken.ThrowIfCancellationRequested();
                    return source.FilterAsync(request, async () => response = await acc(), cancellationToken);
                });
        return task();
    }
}

Essa classe tem uma estrutura parecida com a HandlerExecutor. Logo, os métodos Execute<TRequest, TResponse> e Execute<TRequest> fazem a mesma coisa, a diferença está no fato de ter ou não retorno da execução. Acho que nessa altura do campeonato você já deve ter entendido isso :)

Quando o handler não tem o retorno de uma execução, o valor padrão devolvido é Void.Null. Como os filtros atendem qualquer tipo de handler (com ou sem retorno), essa foi a forma encontrada para ter um tipo de retorno específico. Para você que utliza o filtro, isso é completamente transparente já que nesse caso o retorno passa a ser apenas uma Task.

A gente começa obtendo todos os filtros registrados no nosso sistema. Em seguida nós usamos o serviceProvider para obter o objeto construído pelo sistema de injeção de dependência.

Depois disso, Aggregate! Eu particularmente acho que essa implementação ficou realmente elegante. Ela conseguiu ficar mais elegante do que o Zidane jogando bola!

O método Aggregate é usado para transformar uma lista de filtros em uma cadeia de execução.

Lembra que eu disse que o FilterRegistry armazenava os services numa Stack?

Eu usei uma Stack para garantir que os Filters sejam invocados na ordem inversa à qual foram adicionados. Isso é importante porque, ao usar uma pilha (estrutura LIFO - Last In, First Out), o último filtro registrado será o primeiro a ser executado pelo FilterExecutor.

Isso influencia diretamente na ordem de execução dos filtros. Eu não gostaria de usar um Reverse toda vez que um Handler fosse executado. Isso seria custoso.

Pense que o último filtro incluído vai invocar o penúltimo que por sua vez vai invocar o antepenúltimo e por aí vai.

Sendo assim, ao registrar filtros dessa forma:

configuration.AddFilter<Filter1>();
configuration.AddFilter<Filter2>();
configuration.AddFilter<Filter3>();

Eles serão representados da seguinte forma na Stack:

Filter3, 
Filter2, 
Filter1

E a invocação segue o seguinte fluxo:

Filter3
└── Filter2
    └── Filter1

Em resumo, o Filter3 só vai ser executado após o Filter2 ser executado que só será executado após o Filter1 ser executado. Cascata... ~~melhor que Agile~~...

Seguimos...

Lembram do Func<Task> next da interface IRequestFilter que eu citei no começo do post?
Então... Ele é essencial no processo de execução dos filtros pois representa a próxima etapa na cadeia de execução.

Cada filtro pode decidir se vai ou não invocá-lo - await next() - determinando se o fluxo é interrompido ou vai continuar executando...

Imagine que podemos ter um Filter que valide se o request contém valores válidos. Se for válido, podemos simplesmente dizer ao fluxo: vá em frente - await next() - ou podemos interromper lançando uma exceção ou algo do tipo.

Eu acho que essa é a parte mais chatinha do código. Mas não é algo tããão complexo... Se analisar com atenção o código vai perceber isso...

Com isso terminamos a nossa implementação. Já temos nossa biblioteca Mediator linda e maravilhosa. Funcionando Like a charm! Handlers e Filters. Que maravilha. Falta pouco para termos a v1 com todas as funcionalidades propostas implementadas.

É claro que eu vou mostrar como ficou a utilização dessa nossa belezura.
A gente vai criar dois filters, um para medir o tempo de execução e o outro para logar a execução. E também teremos um handler básico. Saca só...

No projeto de Playgorund, vamos alterar nossa Program:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddTheMediator(configuration =>
{
    configuration.AddServicesFromAssemblies(typeof(Program).Assembly);
    configuration.AddFilter<MeasureTimeRequestFilter>();
    configuration.AddFilter<LoggerRequestFilter>();
});

builder.Services.AddOpenApi();

var app = builder. Build();
app.MapOpenApi();
app.MapScalarApiReference();

app.MapGet("/products/{id:guid}",
        async (
            [FromServices] ISender sender,
            [FromRoute] Guid id,
            CancellationToken cancellationToken) =>
        {
            var response = await sender.SendAsync<Guid, ProductResponse?>(id, cancellationToken);
            return Results.Ok(response);
        })
    .WithName("Products.Get.ProductByIdQuery");

app.Run();

public class GetByIdProductRequestHandler
    : IRequestHandler<Guid, ProductResponse?>
{
    public Task<ProductResponse?> HandleAsync(Guid request, CancellationToken cancellationToken)
    {
        return request == Guid.Empty 
            ? Task.FromResult<ProductResponse?>(null) 
            : Task.FromResult<ProductResponse?>(new ProductResponse(request, "Playstation 5", 4500));
    }
}

public class MeasureTimeRequestFilter(ILogger<MeasureTimeRequestFilter> logger)
    : IRequestFilter
{
    public Task FilterAsync<TRequest>(TRequest request, Func<Task> next, CancellationToken cancellationToken)
        where TRequest : notnull
    {
        logger.LogInformation("Started measuring time for Request type {Type} at {Time}", request.GetType().Name, DateTime.Now);

        var stopwatch = new Stopwatch();
        stopwatch.Start();

        var response = next();

        stopwatch.Stop();
        logger.LogInformation("Request type {Type} execution time: {Time} ms", request.GetType().Name, stopwatch.ElapsedMilliseconds);

        return response;
    }
}

public class LoggerRequestFilter(ILogger<LoggerRequestFilter> logger)
    : IRequestFilter
{
    public Task FilterAsync<TRequest>(TRequest request, Func<Task> next,
        CancellationToken cancellationToken)
        where TRequest : notnull
    {
        logger.LogInformation("Request type {Type} execution started: {Time}", request.GetType().Name, DateTime.Now);

        var response = next();

        logger.LogInformation("Request type {Type} execution finished: {Time}", request.GetType().Name, DateTime.Now);
        return response;
    }
}

Se tudo der certo e nada der errado, eu executar a aplicação e acessar o endpoint http://localhost:<<PORTA>>/products/52603dac-cd0d-4bcf-afad-f6e7fdb5f54f, vamos receber as seguintes informações no console:

info: MeasureTimeRequestFilter[0]
      Started measuring time for Request type Guid at 04/18/2025 16:47:53
info: LoggerRequestFilter[0]
      Request type Guid execution started: 04/18/2025 16:47:53
info: LoggerRequestFilter[0]
      Request type Guid execution finished: 04/18/2025 16:47:53
info: MeasureTimeRequestFilter[0]
      Request type Guid execution time: 3 ms

Chegamos ao final da parte 2 do post Reinventando a Roda: Criando seu próprio MediatR!

Você pode acessar o código fonte dessa implementação nesse link: https://github.com/angelobelchior/TheMediator

Espero que vocês tenham curtido esses posts. Eu me diverti muito implementando o código e escrevendo!!!

Em breve a gente passa a régua no assunto!!

Forte abraço e até mais!!!

Reinventando a Roda: Criando seu próprio MediatR - Parte 1

Angelo Belchior — Fri, 11 Apr 2025 00:15:50 +0000

Quando o homem inventou a roda
Logo Deus inventou o freio,
Um dia, um feio inventou a moda
E toda roda amou o feio.

Zeca Baleiro é um gênio. Se você discorda, você está errado.

A roda toda abraçou o MediatR. Virou moda. É uma das bibliotecas mais usadas no mundo do dotnet.
Porém Jimmy Bogard, autor da lib resolveu colocar um freio na nossa alegria e resolveu transformar essa biblioteca em um produto pago: https://www.jimmybogard.com/automapper-and-mediatr-going-commercial/.

Não critico. Open Source geralmente é um belo de um "Venha a nós e ao Vosso Reino, nada!": Centenas de milhares de empresas usando, milhões de desenvolvedores reclamando e ninguém contribuindo. Simples assim.

Nem eu, nem você e muito menos as nossas empresas pensam nisso. É fato!

Para manter uma biblioteca como essa, o autor ou a autora (e sim, geralmente é uma pessoa só ou um grupo bem pequeno de pessoas) despende horas e horas e horas de trabalho e muita dedicação, dividindo seu tempo entre a empresa, projeto e a familia.

"Nem relógio trabalha de graça!" já diria meu velho pai! Nem ele, nem eu e nem você. A conta chegou e o grande Jimmy Bogard tomou a decisão que só ele poderia tomar. Eu apoio! E, acima de tudo agradeço por todo excelente trabalho feito. Coloquei muito sistema em produção usando o MediatR. Sou grato por isso. E acredito que você também seja.

Pois bem, seguimos.

Antes de tudo preciso destacar aqui que esse é o primeiro de uma série de três posts. Preferi dividir o assunto em três partes pois fiquei traumatizado com o post Reinventando a Roda: Criando uma Rede Neural com csharp já que foram muitos e muitos dias de estudo que se transformaram em muitos dias de escrita de código e que acarretaram num post que leva aproximadamente 35 minutos para a leitura completa. Oremos.

Nessa primeira parte quero abordar a criação e invocação do Command Handler (IHandler e ISender) apenas. E quero trazer algumas melhorias que eu julguei interessantes. Pelo menos para mim são interessantes.

No segundo post nós vamos avançar incluindo um Filter Handler, equivalente ao Pipeline Behavior.

E por fim, na terceira parte, vamos adicionar a feature de envio de notificações, o famigerado Publish!

Eu sei... existem várias outras features como stream por exemplo, mas quero focar nessas três apenas!

Se tudo der certo e nada der errado, crio uma DLC do post incluindo um sistema automágico de validação de Request. É algo que eu já poderia entregar na primeira parte, mas acho que o post ficaria grande demais (e eu nem sei se essa é uma boa ideia. Veremos...).

Certo, eu acredito que nem todo mundo está familiarizado com a biblioteca MediatR e com o pattern Mediador. Esse post não vai abordar o conceito em si, para isso acesse https://refactoring.guru/design-patterns/mediator - um dos sites mais incríveis que eu já vi na vida. Aliás, a imagem de capa desse post foi usurpada e modificada digitalmente pelo ChatGPT. Espero que eles não me processem, mas o crédito é todo, todinho deles!

Eu também não vou me aprofundar na biblioteca, vou falar apenas superficialmente, porém caso queira saber mais sobre, recomendo esse post Playground: MediatR do grande William Santos.

É importante destacar que o código abaixo - apesar de achar ele bem escrito e funcional - não foi feito para ser usado em produção. Pelo menos nesse estágio de desenvolvimento. Aliás, em nenhum estágio, já que eu não tenho nenhum interesse de manter esse código. E esse é um dos fatores fundamentais para a escolha de um produto/framework/serviço: alguém vai precisar manter, atualizar, corrigir erro e acima de tudo, evoluir o código. Não é o meu caso.

Ok, vamos ao que viemos. Pegue aquela xícara de café marota e vem comigo.

Crie um projeto do tipo Class Library. Dê o nome que preferir, mas escolha um nome pomposo. Eu dei o nome de TheMediator.Core. Robusto.

Certo! Vamos começar com o Handler. Um handler recebe um command (no nosso caso chamaremos de request) e pode ou não devolver um Response. Logo, precisamos ter dois métodos, um que retorna valor e o outro retorna void.

Para representar esse Handler criaremos duas interfaces:

Arquivo IHandler.cs:

public interface IHandler<in TRequest, TResponse>  
{  
  Task<TResponse> HandleAsync(TRequest request, CancellationToken cancellationToken);  
}  

public interface IHandler<in TRequest>  
{  
  Task HandleAsync(TRequest request, CancellationToken cancellationToken);  
}

A primeira interface recebe dois tipos genéricos que vão representar o request (TRequest) e o response (TResponse). A outra interface espera apenas o request.

E é aqui que temos uma grande mudança em relação ao MediatR: Por design, ele espera que o request implemente uma interface chamada IRequest ou IRequest<TResponse>. Dessa forma temos duas limitações: a primeira é que eu não posso utilizar um tipo primitivo como request (int, string, etc.) e segundo que, caso o handler retorne um valor (response), essa informação precisa estar definida no request.

A minha abordagem deixa livre para que possamos utilizar qualquer tipo de dado como request. Isso diminui a verbosidade do código já que, no caso do MediatR precisaríamos de algo como:

public record ProductResponse(Guid Id, string Name, decimal Price);

public record SearchProductRequest(string Filter) : IRequest<IReadOnlyCollection<ProductResponse>?>;

public class SearchProductHandler(IProductsRepository repository)
    : IHandler<SearchProductRequest, IReadOnlyCollection<ProductResponse>?>
{
    public Task<IReadOnlyCollection<ProductResponse>?> HandleAsync(
        SearchProductRequest request,
        CancellationToken cancellationToken)
    {
        return repository.Search(request.Filter, cancellationToken);
    }
}

Gosto pero no mucho...

No meu caso temos:

public record ProductResponse(Guid Id, string Name, decimal Price);

public class SearchProductHandler(IProductsRepository repository)
    : IHandler<string?, IReadOnlyCollection<ProductResponse>>
{
    public Task<IReadOnlyCollection<ProductResponse>> HandleAsync(
        string? query,
        CancellationToken cancellationToken)
    {
        return repository.Search(query, cancellationToken);
    }
}

Isso me dá mais flexibilidade. E temos menos código.

Gosto.

Avancemos!

O próximo passo é começarmos a implementar o nosso dispatcher ou o famigerado ISender. Essa interface representa o processo de envio do comando. Dado um request encontra-se o handler correspondente:

Arquivo ISender:

public interface ISender
{
    Task<TResponse> SendAsync<TRequest, TResponse>(TRequest request,
        CancellationToken cancellationToken);

    Task SendAsync<TRequest>(TRequest request, CancellationToken cancellationToken);
}

Repararam que essa interface segue a mesma ideia do IHandler tendo dois métodos, um para quando o processo retornar um resultado e outro para quando o resultado é um void? E todos utilizam um CancellationToken. E se você não sabe para que serve um CancellationToken eu fiz um post explicando: Async/Await: Para que serve o CancellationToken?. Divirta-se!

No MediatR, caso você utilize um request em mais de um handler ele vai executar o primeiro handler registrado e ignorar o restante (acho que tem como configurar para gerar uma exception caso mais de um handler seja registrado com um request. Apenas acho. Se souber de algo, poste aí nos comentários).

Sinceramente no me gusta...

Na minha implementação é possível sim ter mais de um handler usando o mesmo request contanto que o response seja diferente.

Para isso, precisamos ter um controle de todos os handlers registrados pela aplicação.
Minha ideia aqui é ter uma representação da estrutura de tipos de um Handler. Basicamente podemos ter um Handler com um TRequest e TResponse ou apenas com um TResponse.

Sendo assim, criei um record para representar essa estrutura de dados:

Arquivo TypeInspector.cs

internal record ServiceTypes(Type MainType, Type RequestType, Type ResponseType);

A primeira pergunta que você deve estar fazendo é: ResponseTypenão poderia aceitar nulo?
Sim, poderia. Mas sempre que posso eu evito o uso do null. Existem inúmeros motivos para isso, porém não vou trazê-los agora. Sendo assim, para atender esse cenário, criei um tipo vazio - Void - para representar situações onde o Handler não tem um TResponse:

Arquivo TypeInspector.cs

internal class Void;

Uma outra pergunta que surge é, por que não deu o nome de HandlerType para a propriedade MainType?
Simples: Essa estrutura vai ser usada em outras frentes como por exemplo no IFilterHandler que veremos na parte 2 desse post.

Certo! Agora precisamos criar uma classe onde vamos obter informações sobre os tipos de serviço registrados pelo sistema.

Arquivo TypeInspector.cs

internal static class TypeInspector
{
    public static IEnumerable<Type> GetTypesByAssembly(Assembly assembly, params Type[] types)
    {
        var handlerTypes = assembly.GetTypes()
            .Where(t => t.IsClass && t is { IsAbstract: false, IsGenericType: false })
            .Where(t => t.GetInterfaces().Any(i =>
                i.IsGenericType &&
                types.Contains(i.GetGenericTypeDefinition())));

        return handlerTypes;
    }

    public static ServiceTypes GetServiceTypes(
        Type mainType,
        params Type[] types)
    {
        foreach (var type in types)
        {
            var interfaceType = mainType.GetInterfaceType(type);
            if (interfaceType is null) continue;

            var genericArguments = interfaceType.GetGenericArguments();
            if (genericArguments.Length == 1) // IHandler<TRequest>
                return new(mainType, genericArguments[0], typeof(Void));

            return new(mainType, genericArguments[0], genericArguments[1]); // IHandler<TRequest, TResponse>
        }

        throw new InvalidOperationException(
            $"The handler {mainType} does not implement IHandler<TRequest,TResponse> or IHandler<TRequest>.");
    }

    private static Type? GetInterfaceType(this Type interfaceType, Type mainType)
        => interfaceType
            .GetInterfaces()
            .FirstOrDefault(i =>
                i.IsGenericType &&
                i.GetGenericTypeDefinition() == mainType);
}

Vou explicar método a método o que a classe estática TypeInspector faz.

O método GetTypesByAssembly vai ser usado para obter todas as classes que implementam uma ou mais interfaces pré-definidas. Imagine que, ao carregar nossa aplicação, nós vamos varrer os assemblies à procura de classes que implementam IHandler<,> e IHandler<> (no próximo post vamos incluir o IFilterHandler<,> e IFilterHandler<>).

Talvez você não esteja acostumado com a notação <,> ou <>, mas isso é simples. A primeira define uma interface com dois tipos genéricos, e a segunda define uma interface com um tipo genérico apenas. Logo, consigo fazer esse filtro nos tipos do assembly obtendo uma lista de interfaces que o tipo implementa, e dentro dessa lista é verificado se os tipos são iguais aos que foram informados como parâmetro do método.

Esse método vai facilitar muito a nossa vida. Não vamos precisar registrar os Handlers um por um.

Já o método GetServiceTypes retorna uma estrutura com os tipos genéricos do nosso Handler. A gente informa o tipo do Handler e obtemos os tipos do TRequest e TResponse passados na interface IHandler<TRequest, TResponse>, ou ainda, obtemos apenas o tipo TRequest passado na interface IHandler<TRequest>.

Em resumo, se eu tenho um Handler public class CreateProductHandler : IHandler<ProductRequest, ProductResponse>, esse método vai retornar um ServiceTypes com os valores MainType= CreateProductHandler, RequestType = ProductRequest e ResponseType = ProductResponse;

Caso o Handler não tenha um response, o ResponseType vai ser Void. Sacaram o motivo de eu ter criaro a classe Void?

Por fim temos o método GetInterfaceType que é uma extensão incluída no tipo Type para nos ajudar a trazer uma a interface que o Handler implementou. Por exemplo, ao passarmo typeof(CreateProductHandler) o retorno seria IHandler<ProductRequest, ProductResponse> e a partir disso podemos seguir a diante e obter os tipos do TRequest e do TResponse que no caso são ProductRequest e ProductResponse.

Por hora fechamos nossa classe TypeInspector.

Nesse momento precisamos ter uma classe para registrar no sistema de injeção de dependências todos os serviços que foram encontrados na nossa aplicação. Para tal, criaremos uma classe HandlerTypeManager:

Arquivo HandlerTypeManager.cs

public class HandlerTypeManager(IServiceCollection services)
{
    private readonly HashSet<ServiceTypes> _handlersServiceTypes = new();

    public void AddServicesFromAssemblies(params Assembly[] assemblies)
    {
        if (assemblies is null || assemblies.Length == 0)
            throw new ArgumentNullException(nameof(assemblies), "Assemblies cannot be null or empty.");

        var handlerTypes = assemblies
            .Select(assembly => TypeInspector.GetTypesByAssembly(assembly, typeof(IHandler<,>), typeof(IHandler<>)))
            .SelectMany(handlers => handlers);

        foreach (var handlerType in handlerTypes)
            AddHandler(handlerType);
    }

    internal Type GetHandler<TRequest, TResponse>()
        => GetHandlerTypeByRequestResponse<TRequest, TResponse>();

    internal Type GetHandler<TRequest>()
        => GetHandlerTypeByRequestResponse<TRequest, Void>();

    private void AddHandler(Type handlerType)
    {
        var handlerServiceTypes = TypeInspector.GetServiceTypes(handlerType, typeof(IHandler<,>), typeof(IHandler<>));

        var notExists =  _handlersServiceTypes.Add(handlerServiceTypes);
        if(!notExists)
            throw new InvalidOperationException(
                $"Cannot register {handlerType}!.\nThe handler {handlerServiceTypes.MainType} is already registered with the same request {handlerServiceTypes.RequestType} and response {handlerServiceTypes.ResponseType} types.");

        services.AddSingleton(handlerType);
    }

    private Type GetHandlerTypeByRequestResponse<TRequest, TResponse>()
    {
        var requestType = typeof(TRequest);
        var responseType = typeof(TResponse);
        var type = _handlersServiceTypes.FirstOrDefault(h => h.RequestType == requestType && h.ResponseType == responseType);
        if (type is null)
            throw new InvalidOperationException(
                $"No handler found for request type {typeof(TRequest)} and response type {typeof(TResponse)}.");

        return type.MainType;
    }
}

Vamos destrinchá-la:

Recebemos um IServiceCollection services no construtor primário. Vamos utilizar esse services para efetuar a injeção de dependência.
Em seguida temos um HashSet<ServiceTypes> _handlersServiceTypes. É aqui que vamos armazenar todos os ServiceTypes encontrados nos assemblies informados pela aplicação. O HashSet é uma opção muito interessante pelo fato de não permitir a inserção de dois items iguais. Isso é muito importante para nós.

O método AddServicesFromAssemblies recebe uma lista de assemblies onde vamos obter todos os serviços que implementamIHandler<,> e IHandler<>. Os serviços encontrados serão incluídos na estrutura de dados do tipo HashSet _handlersServiceTypes pelo método AddHandler. Esse método vai ser muito importante. Ele é a porta de entrada para o nosso Mediator...

O método AddHandler como o próprio nome sugere, utiliza o TypeInspector para obter o ServiceTypes. Vimos como isso é feito logo acima. Em seguida tentamos incluir no nosso HashSet. Caso já exista um ServiceType com o mesmo MainType, RequestType e ResponseType, eu lanço uma exceção. Como informei anteriormente, é possível que um mesmo request seja utilizado em vários handlers contanto que seu response seja diferente. E por fim, incluo o tipo no sistema de injeção de dependência utilizando um services.AddSingleton(handlerType). (Se fosse necessário criar esse sistema de DI na mão a gente tava ~~fudido~~ ferrado)

Os métodos GetHandler<TRequest, TResponse>() e GetHandler<TRequest>() invocam o método GetHandlerTypeByRequestResponse<TRequest, TResponse>(). Nesse momento acredito que você tenha percebido a utilidade do Void. Eu recomendo muito: páre de usar null...

O método GetHandlerTypeByRequestResponse<TRequest, TResponse>() é bem simples, ele tenta encontrar o MainType no HashSet _handlersServiceTypes usando o FirstOrDefault do Linq. Caso não encontre, lança uma exceção.

Os métodos de Get serão utilizados na implementação do ISender. Guenta ae que você vai ver a utilidade deles logo mais...

Beleza. Temos todo mecanismo necessário para registrar e obter os Handlers. A seguir precisamos criar uma implementação para a interface ISender. Essa implementação é bem simples mas muito eficaz e acima de tudo performática.

Arquivo ISender.cs

internal class Sender(IServiceProvider serviceProvider, HandlerTypeManager handlerTypeManager) : ISender
{
    public Task<TResponse> SendAsync<TRequest, TResponse>(TRequest request,
        CancellationToken cancellationToken)
    {
        var handlerType = handlerTypeManager.GetHandler<TRequest, TResponse>();
        var service = (IHandler<TRequest, TResponse>)serviceProvider.GetRequiredService(handlerType);
        return service.HandleAsync(request, cancellationToken);
    }

    public Task SendAsync<TRequest>(TRequest request, CancellationToken cancellationToken)
    {
        var handlerType = handlerTypeManager.GetHandler<TRequest>();
        var service = (IHandler<TRequest>)serviceProvider.GetRequiredService(handlerType);
        return service.HandleAsync(request, cancellationToken);
    }
}

No construtor primário recebemos um IServiceProvider serviceProvider e um HandlerTypeManager handlerTypeManager.

Os métodos Task<TResponse> SendAsync<TRequest, TResponse>(TRequest request, CancellationToken cancellationToken) e Task SendAsync<TRequest>(TRequest request, CancellationToken cancellationToken) fazem praticamente a mesma coisa, sendo que um retorna um TResponse e o outro não.
Eles obtem o handlerType utilizando o handlerTypeManager.GetHandler (viu para que serve? ;p) e usam o IServiceProvider para obter do sistema de injeção de dependência uma instância correspondente ao tipo do handler informado.
Eu falei algumas vezes desse sistema de injeção de dependência acreditando que você aí saiba para que ele serve e como ele funciona. Se não sabe, recomendo muito a leitura desse post: https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection.

Pronto! A classe Sender é "apenas" isso. sem mágicas ou malabarismos. Utilizamos apenas csharp na sua mais pura essência. Temos nosso Mediator praticamente finalizado. Falta apenas uma coisa...

Para facilitar o uso do nosso Mediator vamos criar um método de extensão que adiciona uma funcionalidade no IServiceCollection. É bem simples e fácil de entender. E o melhor, ajuda muito quem vai consumir nossa lib.

Arquivo DependencyInjection.cs

public static class DependencyInjection
{
    public static IServiceCollection AddTheMediator(
        this IServiceCollection services, Action<HandlerTypeManager> configurator)
    {
        var handlerTypeManager = new HandlerTypeManager(services);
        configurator(handlerTypeManager);

        services.AddSingleton<HandlerTypeManager>(_ => handlerTypeManager);
        services.AddSingleton<ISender, Sender>();

        return services;
    }
}

Esse método é bem simples, ele recebe o IServiceCollection services e uma Action<HandlerTypeManager> que eu chamei de configurator.

Eu crio uma instância do HandlerTypeManager passando o services e repasso essa instância para o configurador. Esse configurador será utilizado pela aplicação que vai usar o Mediator. Abaixo eu mostro isso na prática.

Em seguida eu registro o HandlerTypeManager como singleton no sistema de injeção de dependência, retornando o handlerTypeManager que foi configurado pela aplicação.
E por último eu adiciono o ISender no sistema de injeção de dependência onde ele vai receber uma instância da classe Sender. Também como singleton.

Aqui temos um caso interessante: Na classe Sender eu espero um IServiceProvider serviceProvider. Para muitos pode ser uma novidade, mas o próprio sistema de injeção de dependência injeta uma instância do ServiceProvider para nós. Isso facilita muito nosso desenvolvimento.

Pronto!!! Temos nosso próprio Mediator. Que maravilha. E nem doeu. Não tem todas as funcionalidades ainda, mas já podemos usar ~~em produção~~ no nosso playground.

Bora testar?

Crie um projeto Web Minimal API. Melhor escolha para desenvolver APIs em dotnet.

Referencie a nossa super lib. Vamos adicionar e configurar nosso Mediator.

Arquivo Program.cs

using TheMediator.Core;

var builder = WebApplication.CreateBuilder(args);  

builder.Services.AddTheMediator(configurator =>  
{  
    configurator.AddServicesFromAssemblies(typeof(Program).Assembly);  
});

Viu que simples. Aquela Action lá de cima nos possibilita configurar nossa biblioteca de uma forma mais simples. Num futuro podemos expor mais configurações como por exemplo o ciclo de vida dos Handlers, ou a forma que vamos despachar as Notifications ou ainda qual implementação podemos usar de validação de commands. Dá para fazer muita coisa.
Aliás, essa abordagem não é nada original. É um padrão, se você for ver...

// Esse código não precisa ser adicionado nos testes... serve apenas para exemplo...
builder.Services.AddOpenApi("Minha API", configurator =>  
{  
    configurator.OpenApiVersion = OpenApiSpecVersion.OpenApi2_0;  
});

Pronto, configuramos nossa biblioteca. Vamos criar nosso primeiro Handler?

Arquivo HelloHandler.cs

public class HelloHandler : IHandler<string, string>
{
    public Task<string> HandleAsync(string request, CancellationToken cancellationToken)
    {
        return Task.FromResult($"Hello {request}");
    }
}

Nesse momento eu recomendo que você coloque um break point na linha configurator.AddServicesFromAssemblies(typeof(Program).Assembly); rode a aplicação e vá executando passo-a-passo. Isso vai te ajudar a compreender todo o fluxo, desde o carregamento dos tipos, até a inclusão deles na nossa lista de Handlers. É bem divertido e mostra como o sistema de gestão de tipos do csharp é muito flexível.

Beleza. Tudo certo, nada resolvido! Vamos criar um endpoint maroto para testar de verdade.

app.MapGet("/hello",
        async (
            [FromServices] ISender sender,
            CancellationToken cancellationToken) =>
        {
            var request = "Mediator!!!!!";
            var response = await sender.SendAsync<string, string>(request, cancellationToken);
            return new { message = response };
        })
    .WithName("hello");

Boa! Agora é rodar a aplicação, invocar o endpoint http://localhost:<PORTA>/hello e correr para o abraço. Mas antes eu recomendo colocar um break point na linha var request = "Mediator!!!!!"; e um outro break point na linha return Task.FromResult($"Hello {request}"); do handler HelloHandler.

Se tudo der certo e nada der errado, teremos a seguinte saída:

{
  "message": "Hello Mediator!!!!!"
}

Viu só? Recomendo que crie vários handlers e brinque debugando o código. Crie handlers com e sem TResponse, crie com tipos primitivos, tipos complexos, tente registrar mais de um handler com o mesmo TRequest, enfim, teste bastante. Brinque bastante! No repositório eu deixei um playground pronto com vários handlers. Recomendo dar uma olhadinha com calma!!

Enfim chegamos ao final da primeira parte do post Reinventando a Roda: Criando seu próprio MediatR. O que foi feito aqui já é algo muito útil. Ainda temos melhorias para fazer, então aguarde a parte 2 e 3 do post.

E caso queira baixar o projeto, acesse https://github.com/angelobelchior/TheMediator!

Críticas, dúvidas e sugestões são aceitas. ~~Se serão respondidas, aí é uma outra história...~~

Forte abraço, até a próxima!

Reinventando a Roda: Criando uma Rede Neural com csharp

Angelo Belchior — Wed, 26 Feb 2025 00:23:15 +0000

Por que causa, motivo, razão ou circunstância um ser humano em sã consciência escreveria uma Rede Neural do Zero, sem o uso de bibliotecas de terceiros e usando csharp?

Eu gostaria de dar a você meu caro leitor, minha cara leitora, uma resposta mais embasada ou até mesmo poética. Mas o fato é que eu queria apenas me desafiar a construir algo que não faz parte do meu dia a dia e que me fizesse pensar, estudar. Redes Neurais, IA, Machine Learning, Deep Learning, etc... todas essas palavrinhas sempre me soaram como Mágica ~~e hoje eu descobri que tudo isso não passa de Regex e um monte de ifs aninhados...~~

Sendo assim, me propus o desafio de estudar o tema e tentar implementar algo, mesmo que básico, para compreender verdadeiramente o processo de ponta a ponta.
A grande questão é que esse tema é absurdamente complexo, denso e demanda muito, mas muito estudo. Muito mesmo!

O que eu apresentarei aqui é algo tratado como muito básico. É o "Hello World" dos cientistas de dados. É apenas uma fração desse universo gigantesco chamado Inteligência Artificial. Sinceramente, é o que eu consegui entender e implementar. Apenas isso.
E, olha... suei sangue para entender alguns conceitos... Talvez você que é mais inteligente ache que eu estou fazendo drama, mas não... foram dias e dias de estudo, mas no fim foi um baita aprendizado. Na verdade, ainda está sendo...

Começando pelo começo!

Quando eu conheci o canal Universo Programado eu pirei. Simplesmente pirei. Que conteúdo espetacular, senhoras e senhores. Os vídeos beiram o estado da arte. Aliás, alguns são, de fato, o estado da arte.
Eu achei incrível o fato do Victor Dias escrever os algoritmos na mão e pensei: Se ele consegue, eu também consigo!

Fui tentar e quebrei a cara. O buraco era muito mais embaixo... Precisava estudar muitas coisas antes de escrever a primeira linha de código.

Foi aí que eu decidi me desafiar. Apanhei mais que atacante de time de várzea, mas valeu a pena.

Eu já tinha uma certa noção de como as coisas aparentemente funcionavam pelo fato de ter estudado o ML.Net, porém, por ser uma biblioteca, ela abstrai praticamente tudo. A gente precisa apenas saber como configurar e qual algoritmo utilizar. O resto ela faz sozinha.
Eu queria evitar ao máximo isso. Queria escrever linha a linha e entender passo-a-passo o que estava acontecendo.

Apelei ao youtube e logo de cara descobri um curso SENSACIONAL chamado Rede neural do zero em Python.
Além desse curso também tem esse Rede neural do zero em Python: Modelo básico que é muito bom e que me abriu muito a mente sobre o que é e como funciona uma Rede Neural.

Esses dois cursos são do canal Machine Learning para Humanos. Se inscreva! Vale muito a pena!!

Dentre meus estudos eu precisei focar em algumas frentes. Não dava para estudar todas as arquiteturas de Redes Neurais e, sendo assim, decidi escolher a Feed-Forward. O motivo é que, naquele momento, me parecia ser a mais simples de ser implementada. Não sei se foi a melhor escolha. Mas acho que deu certo... acho...

Sendo assim, vamos avançar. Quero fazer uma breve introdução sobre o que é uma Rede Neural, e explicar um pouco sobre o Feed-Forward.

O que é uma Rede Neural Artificial

Uma Rede Neural Artificial é um sistema de computação inspirado no cérebro humano. Ela é composta por várias camadas de "neurônios artificiais" interconectados que processam informações e aprendem com os dados.

Essa é a definição que qualquer ChatGPT da vida vai te dar.

Porém, dois pontos na afirmação acima me intrigam:

Como uma Rede Neural aprende?
E o que é essa aprendizagem? (Como eu consigo salvar esse resultado para que depois seja possível utilizá-lo para fazer a predição de um determinado valor?)

Quando a gente começa a ler sobre o tema, se depara com argumentos do tipo:

"Uma Rede Neural aprimora seu aprendizado ajustando os pesos das conexões entre os neurônios para minimizar o erro entre a saída prevista e a saída esperada."...

E ainda...

"O resultado da aprendizagem são os padrões e as relações identificadas entre os dados de entrada e saída."...

É nesse momento que a gente precisa ter calma e se aprofundar um pouco mais.

Como de costume pegue aquele café quentinho. Aliás, recomendo deixar a térmica do seu lado porque a jornada do post vai ser, digamos.... um pouco longa.

Mas não se preocupe meu amigo com os horrores que eu lhe digo, quando a gente se deparar com o código, vamos começar a ter aquela sensação de:

"Nossa... então são essas três linhas simples de código que ajustam o peso das conexões?".

"Caramba, então essa matriz de pesos contém todo aprendizado?"

As coisas tendem a ficar mais claras e simples no decorrer do post...

Certo, mas como, de fato, uma Rede Neural funciona?
Eu vou tentar ser o mais didático possível...

Nós já sabemos que uma Rede Neural é um processo inspirado no Cérebro Humano. Ela é composta por Neurônios Artificiais, que recebem informações, processam e passam adiante o resultado.

A forma como os Neurônios Artificiais estão dispostos em relação uns aos outros, a quantidade de camadas e os cálculos executados determinam a Arquitetura da Rede Neural.
Logo, temos um conjunto amplo de arquiteturas, dentre elas Perceptron de Camada Única (Single-Layer Perceptron), Redes Neurais Multicamadas (MLP - Multi-Layer Perceptron), Redes Convolucionais (CNN - Convolutional Neural Networks), Redes Recorrentes (RNN - Recurrent Neural Networks) e etc.
Cada uma delas tem um propósito, como por exemplo, Reconhecimento de Imagens (Visão Computacional), Interpretação de Textos (Processamento de Linguagem Natural) etc., e como disse acima, eu precisei focar em algumas para poder avançar nos estudos. Mas esse universo é realmente grande.

Uma das arquiteturas mais simples, é a Feed-Forward. (O que é tratado como simples em Inteligência Artificial é simples apenas no contexto de Inteligência Artificial) Nela, as camadas estão dispostas sequencialmente e a informação flui apenas para frente, sem loops.

Não ficou claro? Explico!

Imagine um fluxo composto por vários passos. No primeiro eu recebo alguns dados, nos seguintes eu efetuo vários cálculos e no passo final é onde eu recebo o resultado desse processamento. Materializando a ideia, imagine que eu passo um conjunto de valores que descrevem um tipo de flor no primeiro passo do processo na expectativa de que no último passo eu receba uma informação que defina (ou tente definir) qual é o tipo da flor.

No caso do Feed-Forward, esse processo envolve basicamente 5 passos: Entrada de Dados, Cálculo dos Pesos, Soma Ponderada, Função de Ativação e Saída.

Entrada de Dados

Tudo começa com uma entrada de dados, que pode ser imagem, texto ou números.
Porém, no final, tudo vai se transformar numa grande matriz de double que vai representar essas informações.

Esses dados de entrada vão servir para treinarmos a nossa Rede! É com as características deles que a Rede Neural vai aprender! Isso é o máximo!

Eu vou utilizar como exemplo um conjunto de dados de flores muito famoso, o Iris Dataset. Esses dados são altura e largura em centímetros das pétalas e das sépalas (eu também não sabia que flor tinha esse negócio aí...). E a partir deles conseguimos saber se determinada flor é da espécie Setosa, Versicolor ou Virginica. (Além de Rede Neural você aprende biologia. É muita informação aleatória para um post só...)

Nesse dataset (que nada mais é do que uma tabela ou matriz, como preferir) temos basicamente as seguintes informações:

Alt.Sep | Larg.Sep | Alt.Pet | Larg.Pet | Esp
-------------------------------------------------------
5.1     | 3.5      | 1.4     | 0.2      | Setosa
4.9     | 3.0      | 1.4     | 0.2      | Setosa
7.0     | 3.2      | 4.7     | 1.4      | Versicolor
6.4     | 3.2      | 4.5     | 1.5      | Versicolor
6.3     | 3.3      | 6.0     | 2.5      | Virginica
5.8     | 2.7      | 5.1     | 1.9      | Virginica

O melhor lugar do mundo para se obter datasets é o https://www.kaggle.com. Lá você pode encontrar o Iris Dataset completo.

Só que temos um problema. Nem todas as informações são do tipo numérico double. A espécie é um texto!!!
E é aqui que entra uma sacada genial! Nós podemos transformar esse texto, num conjunto numérico.

Nós temos três espécies diferentes: Setosa, Versicolor e Virginica.

Logo, podemos afirmar categoricamente que, quando a espécie é Setosa ela não pode ser nem Versicolor e nem Virginica.
Em uma forma mais técnica, podemos afirmar que:

Se "Setosa" = 1, então "Versicolor" = 0 e "Virginica" = 0 => [1, 0, 0]

Se "Setosa" = 0, "Versicolor" = 1 e "Virginica" = 0 => [0, 1, 0]

Se "Setosa" = 0, "Versicolor" = 0 então "Virginica" = 1 => [0, 0, 1]

Sacaram a ideia?

Eu tenho um array com três posições que me define quando uma espécie é Setosa, Versicolor ou Virginica.
Isso é genial. Eu pagaria um Dog de Osasco com uma Tubaína para quem teve essa ideia.

Sendo assim, nossa matriz fica:

Alt.Sep | Larg.Sep | Alt.Pet | Larg.Pet | Setosa | Versicolor | Virginica
-------------------------------------------------------------------------
5.1     | 3.5      | 1.4     | 0.2      | 1.0    | 0.0        | 0.0
4.9     | 3.0      | 1.4     | 0.2      | 1.0    | 0.0        | 0.0
7.0     | 3.2      | 4.7     | 1.4      | 0.0    | 1.0        | 0.0
6.4     | 3.2      | 4.5     | 1.5      | 0.0    | 1.0        | 0.0
6.3     | 3.3      | 6.0     | 2.5      | 0.0    | 0.0        | 1.0
5.8     | 2.7      | 5.1     | 1.9      | 0.0    | 0.0        | 1.0

Porém, é importante destacar que, nossos dados de entrada são apenas as colunas Alt.Sep, Larg.Sep, Alt.Pet e Larg.Pet.
As colunas Setosa, Versicolor e Virginica formam o que a gente chama de saída esperada.

Basicamente, entra porco, sai linguíça! Se a entrada for [5.1, 3.5, 1.4, 0.2], a saída esperada deve ser obrigatoriamente [1.0, 0.0, 0.0].

Pronto, temos nossos dados de entrada!

Pesos e Soma Ponderada

Os pesos são valores que indicam o nível de importância de cada entrada para o neurônio. Eles dizem se um valor deve ser levado mais ou menos em conta no cálculo (veremos mais sobre o cálculo a seguir). No início, esses pesos são definidos aleatoriamente e vão sendo ajustados durante o treinamento.

Cada entrada da Rede passa por um neurônio e é multiplicada pelo seu peso correspondente. Depois, todos esses valores são somados, formando a soma ponderada.

Parece complexo, mas não é muito!

Vamos pegar como exemplo a primeira linha da nossa matriz de entrada (Sem os dados da saída esperada).

Altura da Sépala (x₁ = 5.1)
Largura da Sépala (x₂ = 3.5)
Altura da Pétala (x₃ = 1.4)
Largura da Pétala (x₄ = 0.2)

Os pesos (w) são números ajustáveis durante o treinamento da Rede. Vamos assumir valores iniciais aleatórios:

w1=0.3
w2=0.2
w3=0.8
w4=0.5
Viés b=−0.1 (valor fixo aleatório que ajuda na ativação)

Antes de seguir precisamos adicionar o conceito de Viés!

O Viés (ou Bias) é um parâmetro adicional que ajusta a saída de um neurônio, independentemente dos valores de entrada. Ele é um valor extra adicionado à soma ponderada para garantir que, mesmo que os valores de entrada sejam zero, a saída do neurônio não seja nula, permitindo que o cálculo continue corretamente.

Dito isto, vamos seguir com os cálculos...

Eu acredito que soma ponderada seja algo que você já tenha feito alguma vez no ensino médio, mas não custa nada relembrar a fórmula.

S=(x1×w1)+(x2×w2)+(x3×w3)+(x4×w4)+b

Substituindo os valores...

S = (5.1 * 0.3) + (3.5 * 0.2) + (1.4 * 0.8) + (0.2 * 0.5) + (-0.1)
S = 3.35

Por fim, a soma ponderada do neurônio criado a partir do primeiro registro da nossa entrada de dados é de 3.35!
Com isso podemos aplicar uma função de ativação. O resultado do cálculo da ativação pode ser repassado para o próximo neurônio numa outra camada, ou pode ser usado como resposta final (saída esperada) .

Função de Ativação

A função de ativação nada mais é do que um cálculo que pode definir se o próximo neurônio da próxima camada vai ser ou não ativado ou se o seu valor é a saída final calculada.

E o que significa ser ativado ou não? Significa que se um neurônio tem saída próxima de 0 ou exatamente 0, ele não influencia a rede significativamente. Logo o valor propagado não vai ter nenhum impacto no processamento. É como se aquele processo "morresse" no ponto onde a ativação foi próxima de 0 ou exatamente 0.

A função de ativação é literalmente um método que recebe um double e retorna um double.
Esse valor pode ser um valor de saída definitivo, binário (0 ou 1) ou contínuo (entre -1 e 1), dependendo do tipo de função utilizada.

Existem vários cálculos para a ativação, como Sigmóide, Tangente Hiperbólica, ReLU, Softmax e etc. Eu optei pela função Sigmóide pela característica do nosso problema (classificar um conjunto de dados) já que ela é útil quando a saída precisa ser entre 0 e 1, como em problemas de classificação binária (lembra do Se "Setosa" = 1, então "Versicolor" = 0 e "Virginica" = 0? É isso!).

Vai ficar mais simples de se entender quando começarmos a explicar o código csharp.

Uma coisa interessante é que, dependendo da arquitetura da Rede Neural escolhida, a função de ativação pode ser aplicada em todas as camadas ou exclusivamente na camada de saída. No nosso exemplo, essa função será aplicada apenas na camada de saída.

Saídas

Basicamente são os valores calculados. No nosso exemplo, essa saída é um conjunto de valores binários. Lembram novamente do Se "Setosa" = 1, então "Versicolor" = 0 e "Virginica" = 0? Eu sempre pergunto isso pois eu tenho memória de lesma... O que teremos na posição 0, 1 e 2 do array de saída um valor que vai ser ou muito próximo de 0 ou muito próximo de 1.
Exemplo:

Entrada: [5.1, 3.5, 1.4, 0.2 ] 
Saída: [ 0.9985675612054569, 0.002134671378971386, 6.939394848026144E-10 ]

"Visualizando" a nossa Rede Neural

Após apresentar os 5 passos do processo, acredito que a melhor forma de entendermos como as coisas se conectam é fazer um desenho representando tudo aquilo que dissemos acima.

No desenho temos a representação dos 5 passos dispostos em colunas verticais.
A primeira coluna representa os dados de entrada e nela temos as 4 informações sobre a flor.
Em seguida temos uma coluna que representa basicamente os passos dos cálculos dos Pesos e a Soma Ponderada.
Na próxima coluna temos a função de ativação que recebe o resultado dos cálculos da coluna anterior, e que vai decidir se o neurônio da próxima coluna (camada de saída) vai ser ou não ativado.
Por fim temos a última camada e nela temos 3 neurônios com os valores calculados pelo processo de ativação. Esses 3 valores são os que definem que, dada a entrada [5.1, 3.5, 1.4, 0.2], temos a saída - arredondada - [1.0, 0.0, 0.0], que indica que a flor é da espécie Setosa.

E se você está curioso ou curiosa para saber que raios é essa flor Setosa, toma aqui uma foto da danada...

. Para mais informações, [clique aqui (https://www.picturethisai.com/pt/wiki/Iris_setosa.html).

Biólogos, não me critiquem, eu apenas dei uma googlada e achei essa planta... quer dizer... flor... ahhh sei lá... pra mim é tudo igual...

Um ponto interessante é que, no nosso cenário, não necessitamos de uma ou mais camadas ocultas. Para esse tipo de classificação, as camadas de entrada e de saída bastam.
Problemas mais complexos vão demandar um estudo maior para definir a quantidade de camadas e a quantidade de neurônios. É praticamente outro universo.

Como treinar sua Rede Neural?

O que eu apresentei acima, é uma descrição simples e didática (creio eu) de uma Rede Neural. Inclusive, o desenho serviu mais para dar uma clareada nas ideias, já que para mim, ao estudar o tema, tudo era muito abstrato (e muitas coisas ainda são).
O que me ajudou a fixar alguns conhecimentos foi esse trabalho estupendo do professor Fernando Lucambio Perez do Departamento de Estatística da Universidade Federal do Paraná: http://leg.ufpr.br/~lucambio/Nonparam/NparamV.html.
Eu não vou entrar em detalhes porque o trabalho é razoavelmente longo, e tem muitas informações. Mas a partir da sessão V.2 Redes neurais temos ótimas explicações sobre Redes Neurais e função de ativação Sigmóide com representações visuais e explanação de cálculos.

Esse, para mim, foi o post definitivo. Foi a partir dele que eu comecei a escrever os códigos em csharp.
Que trabalho senhoras e senhores. Que trabalho...

Pois bem! Tendo o desenho acima em mente, quando falamos em treinar a nossa Rede Neural, basicamente estamos falando em pegar os dados de entrada, efetuar os cálculos, passar para a camada de saída e por fim, compará-los com o resultado esperado para calcularmos a taxa de erro.

Lembrando que os cálculos nada mais são do que a soma ponderada e a função de ativação.

E é nesse momento que vamos precisar daqueles conjuntos com três valores, colunas Setosa, Versicolor e Virginica, justamente para validar o quão assertivo está sendo esse processo.

O cálculo de erro é baseado na diferença entre a saída prevista (calculada) e a saída esperada. Nós vamos olhar com calma os detalhes desse cálculo em csharp. Não é complicado, já adianto.
Em seguida temos a multiplicação do erro pela derivada da função de ativação.

Meus amigos e minhas amigas... foi nesse momento que eu simplesmente quis largar tudo e criar um CRUD em Brainfuck com MS Access para relaxar...

Não que calcular uma derivada seja difícil... talvez tenha sido a única coisa que eu aprendi nas aulas de Cálculo I com o professor Cesareo de La Rosa Siqueira.
É que eu jurava que nunca na minha vida eu ia precisar disso. Quebrei a cara!

Certo, mas por qual motivo precisamos usar a derivada da função de ativação (no nosso caso a Sigmóide)?
A derivada da função de ativação é usada para determinar como a saída de um neurônio varia em resposta a mudanças em suas entradas. A partir do momento que estamos efetuando o treinamento, os valores vão variando e sendo repassados de camada para camada (Entrada para Saída). E nesse repasse essa função calcula o "impacto" na atualização dos pesos durante o processo.

Em outras palavras, quando o resultado desse cálculo é grande, pequenas alterações nos pesos resultam em mudanças significativas na saída, acelerando a correção do erro. Quando contrário, indica menor sensibilidade, exigindo ajustes mais sutis. Isso permite que a Rede Neural aprenda de forma mais eficiente. (Deus abençoe Edge Copilot... eu não estava conseguindo expressar em palavras o entendimento que estava na minha mente...).

Nós podemos (e devemos) repetir todo esse processo quantas vezes quisermos! E essa repetição a gente chama carinhosamente de épocas.
A cada época, todo esse processo maroto é executado e os dados são atualizados e repassados de uma camada para outra... e assim vai até terminar...

Eu imagino que essa explicação não tenha ficado tão clara, mas quando a gente analisar o código vamos ter a noção real do que foi explicado acima. Não é um bicho tão feio quanto parece...

Fim da teoria... quero ver código

Essa foi uma breve introdução sobre Redes Neurais. Tentei ser o mais didático possível, mas sinceramente acho que você que está lendo vai conseguir entender melhor quando ver código.
E é agora que a brincadeira começa a ficar séria.

Pega mais um café... eu espero... Se quiser vai no banheiro tirar aquela água do joelho (de onde vem essa expressão??? Se você souber, deixe ai nos comentários) ... pois veremos códigos... \o/
(Eu estava ansioso por esse momento... heheheh)

Porém, preciso fazer alguns disclaimers aqui:

O código a seguir não deve servir de base para nada. Ele foi feito com um único intuito: ser didático!
Eu foquei em resolver o problema e não em criar uma biblioteca ou que as classes tivessem o melhor design do mundo!
Não me importei com performance. Simples assim. Fiz a coisa funcionar, na maioria das vezes debugando e refazendo cálculos manualmente. Isso serviu para que eu entendesse de fato o que estava acontecendo.
Palmeiras não tem mundial!

Posto isso, vamos começar!!!

Criação da Rede Neural

O código gira em torno de 4 classes: RedeNeural, Camada, Neuronio e uma de apoio chamada Funcoes onde eu abstraio o uso das funções de Ativação. Além disso temos um record chamado Dataset que serve apenas para transportar dados de entrada e dados de saída.

A classe RedeNeural contém duas camadas, a Camada de Entrada e a Camada de Saída. É essa classe que orquestra todo o fluxo. Eu vou apresentá-la por partes, mas no código fonte você vai conseguir ver o código por completo:

internal class RedeNeural
{
    private readonly Camada _camadaDeEntrada;
    private readonly Camada _camadaSaida;
    private readonly IFuncoes _funcoes;

    public RedeNeural(
        IFuncoes funcoes,
        int tamanhoDosDadosDeEntrada,
        int tamanhoDosDadosDeSaida,
        int quantidadeDeNeuronios = 3)
    {
        _funcoes = funcoes;

        _camadaDeEntrada = new Camada(quantidadeDeNeuronios, tamanhoDosDadosDeEntrada);
        _camadaSaida = new Camada(quantidadeDeNeuronios, tamanhoDosDadosDeSaida);
    }
    ...
}

Eu inicializo a classe RedeNeural com três informações:

IFuncoes: É uma interface com os métodos Ativar e Derivada. Mais à frente vamos ver com calma eles dois!
tamanhoDosDadosDeEntrada: Basicamente é a quantidade de colunas que temos na nossa matriz de dados de entrada. No exemplo apresentado temos 4: Alt.Sep, Larg.Sep, Alt.Pet e Larg.Pet.
tamanhoDosDadosDeSaida: Aqui nós informamos o tamanho dos dados de saída. No caso o valor é 3, já que esperamos aque array informando se é Setosa, Versicolor ou Virginica.

Esses valores são necessários para a criação das camadas.
Note que temos uma variável chamada quantidadeDeNeuronios onde eu pego a média entre o tamanhoDosDadosDeEntrada e o tamanhoDosDadosDeSaida.

Aqui temos algo bem curioso! Li em alguns lugares que essa seria uma boa prática para se definir a quantidade de neurônios da camada, porém conversando com o grande mestre Diego Nogare ele me explicou que essa definição é um dos grandes desafios existentes dentro da área da Inteligência Artificial, e que inclusive "existem estudos científicos propondo métodos para isso a partir de segmentações dos dados o que ainda é bem difícil de ajustar"!

O fato que para mim isso se tornou uma incógnita, porém, esse cálculo gera uma quantidade de neurônios suficientes para podermos obter o nosso resultado. Fiquei com essa lição de casa: Estudar mais afundo esse assunto.

Vamos seguir para a classe Camada:

internal class Camada
{
    public Neuronio[] Neuronios { get; }

    public Camada(int quantidadeDeNeuronios, int quantidadeDeEntradas)
    {
        Neuronios = new Neuronio[quantidadeDeNeuronios];
        for (var i = 0; i < quantidadeDeNeuronios; i++)
            Neuronios[i] = new Neuronio(quantidadeDeEntradas);
    }

    public double[][] ObterPesos()
    {
        var pesos = new double[Neuronios.Length][];
        for (var i = 0; i < Neuronios.Length; i++) pesos[i] = Neuronios[i].Pesos;
        return pesos;
    }
}

Essa classe é extremamente simples. Nela temos apenas um array de neurônios cujo tamanho é definido pela variável quantidadeDeNeuronios.

O método ObterPesos vai nos auxiliar mais adiantes no processamento dos dados, porém ele serve apenas para retornar uma matriz com os pesos de cada neurônio. É apenas um método facilitador.

Já na classe Neuronio temos:

internal class Neuronio
{
    public double[] Pesos { get; set; }
    public double Vies { get; set; }

    public Neuronio(int quantidadeDeEntradas)
    {
        Pesos = new double[quantidadeDeEntradas];
        for (var i = 0; i < quantidadeDeEntradas; i++)
            Pesos[i] = Funcoes.ObterValorAleatorio();

        Vies = Funcoes.ObterValorAleatorio();
    }
}

Acima temos um for maroto onde são criados os Pesos e o Viés a partir de um valor aleatório.
Os pesos são armazenados num array de double onde cada posição desse array corresponde a uma posição da entrada dos dados.

Basicamente nós teremos algo como:

[5.1   , 3.5   , 1.4   , 0.2   ] -> Dados de entrada
  |       |       |       |     
  v       v       v       v 
[-0.327, -0.124, -0.097, -0.345] -> Pesos

É importante que você consiga mentalizar essa estrutura, pois ela é predominante!

O método ObterValorAleatorio da classe estática Funcoes é algo simples:

public static double ObterValorAleatorio()  
  => (Random.Shared.NextDouble() - 0.5) * 0.1;

Não vou entrar aqui na discussão de que um computador não consegue gerar de números aleatórios e bla, bla, bla. Mas se quiser se aprofundar recomendo começar com o vídeo do Ciência Todo Dia: # Por Que Computadores NÃO PODEM Gerar Números Aleatórios?.

Nesse ponto, temos a nossa estrutura inicializada. Porém, nada acontece. Precisamos começar a treinar nossa Rede Neural.

A partir de agora, todo código está na classe RedeNeural.

Treinando nossa Rede Neural

Para efetuar o treinamento invocamos o método Treinar e passamos o Dataset com dados de entrada e dados de saída.
Essa classe é um record simples:

public record Dataset(double[][] Entrada, double[][] SaidaEsperada);

Além do dataset, informamos a quantidade de épocas e uma taxa de aprendizagem. Eu não citei essa tal taxa de aprendizagem na explanação acima, mas não se preocupe, quando chegar o código de atualização dos Pesos e do Viéseu explico.
Esse método público não tem nada de especial:

public void Treinar(Dataset dataset, int quantidadeDeEpocas, double taxaDeAprendizagem)
{
    for (var epoca = 0; epoca < quantidadeDeEpocas; epoca++)
    {
        for (var i = 0; i < dataset.Entrada.Length; i++)
            Treinar(dataset.Entrada[i], dataset.SaidaEsperada[i], taxaDeAprendizagem);
    }
}

É agora que a coisa começa a esquentar!!!

O método privado Treinar segue um fluxo bem simples, invocando alguns métodos bem importantes:
Ele começa processando a camada oculta, pega o resultado do processamento e repassa para a camada de saída processar.
Em seguida, calcula a taxa de erro de cada camada e atualiza o Peso e Viés com esses valores além da taxa de aprendizagem.
O método em si é muito simples:

private void Treinar(double[] entrada, double[] saidaEsperada, double taxaDeAprendizagem)  
{  
  var resultadoCamadaDeEntrada = Processar(_camadaDeEntrada, entrada);  
  var resultadoCamadaDeSaida = Processar(_camadaSaida, resultadoCamadaDeEntrada);  

  var deltasCamadaDeSaida = CalcularDeltaErroCamadaSaida(resultadoCamadaDeSaida, saidaEsperada);  
  var deltasCamadaDeEntrada = CalcularDeltaErroCamadaDeEntrada(resultadoCamadaDeEntrada, deltasCamadaDeSaida, _camadaSaida.ObterPesos());  

  AtualizarPesosEVies(_camadaSaida, resultadoCamadaDeEntrada, deltasCamadaDeSaida, taxaDeAprendizagem);  
  AtualizarPesosEVies(_camadaDeEntrada, entrada, deltasCamadaDeEntrada, taxaDeAprendizagem);  
}

Se você ainda tiver aquele desenho na cabeça, basicamente o que esse método faz é conectar as camadas, calcular os Pesos e efetuar as ativações dos neurônios para gerar a saída.
Viu, o bixo não era tão feio quanto parecia...

Esse processo é repetido várias vezes, baseado na quantidade de épocas informada.

Ok, agora precisamos se aprofundar mais nos métodos Processar e AtualizarPesosEVies, além dos métodos para cálculo de erro CalcularDeltaErroCamadaSaida e CalcularDeltaErroCamadaDeEntrada. Vamos seguir a ordem apresentada no código!

O processamento da camada nada mais é do que o cálculo da soma ponderada juntamente com a ativação de cada neurônio. Olha que coisa linda:

private double[] Processar(Camada camada, double[] entrada)  
{  
    var saida = new double[camada.Neuronios.Length];  
    for (var i = 0; i < camada.Neuronios.Length; i++)  
    {  
        var somaPonderada = CalcularSomaPonderada(camada.Neuronios[i], entrada);  
        saida[i] = _funcoes.Ativar(somaPonderada + camada.Neuronios[i].Vies);  
    }  
    return saida;  
}

E o cálculo da Soma Ponderada nada mais é do que...

public double CalcularSomaPonderada(double[] entrada)
{
    var soma = 0.0;
    for (var i = 0; i < entrada.Length; i++)
        soma += entrada[i] * Pesos[i];

    return soma;
}

Aquele cálculo S=(x1×w1)+(x2×w2)+(x3×w3)+(x4×w4)+b se resume a um for somando o valor das entradas multiplicados pelo seu peso correspondente e no final, aplicamos a função de ativação que recebe a soma ponderada mais o valor do Viés.

E agora é hora de ver como é a função de ativação Sigmóide em csharp! Tire as crianças da sala!

Na classe Funcoes:

public class Sigmoid : IFuncoes  
{  
  public double Ativar(double valor) 
      => 1.0 / (1.0 + Math.Exp(-valor));  
  ...
}

Em detalhes, temos:

Math.Exp(-valor): Calcula o exponencial de -valor.
1.0 + Math.Exp(-valor): Adiciona 1 ao resultado do exponencial.
1.0 / (1.0 + Math.Exp(-valor)): Calcula o inverso do valor obtido, resultando em um valor entre 0 e 1.

Obrigado Github Copilot \o/

A função de ativação Sigmóide é extremamente simples, como podemos notar!

Nesse ponto ja temos todos os neurônios de cada camada processados. Agora vamos calcular a taxa de erros.

Na classe RedeNeural temos:

private double[] CalcularDeltaErroCamadaSaida(double[] saida, double[] saidaEsperada)  
{  
    var deltas = new double[saida.Length];  
    for (var o = 0; o < saida.Length; o++)  
    {  
        var erro = saida[o] - saidaEsperada[o];  
        deltas[o] = erro * _funcoes.Derivada(saida[o]);  
    }  
    return deltas;  
}

É um processo bem simples também:

O erro é a diferença entre a saída real (saida[o]) e a saída esperada (saidaEsperada[o]).
O delta é o produto do erro e da derivada da função de ativação aplicada à saída real. Isso é feito usando _funcoes.Derivada(saida[o]).

Lembram daquela explicação meio nebulosa sobre o uso da derivada? Então, se resume a isso :)

Vamos olhar o código da função derivada?

Na classe Funcoes:

public double Derivada(double valorDaSigmoide)   
    => valorDaSigmoide * (1 - valorDaSigmoide);

Se você estudou derivada vai notar que é simples, simples, simples. E se você nunca estudou, também vai notar o mesmo...

Eu fiquei horas para achar um erro tosco, no qual eu recalculava o valor da Sigmóide dentro do método, sem perceber que ele já vinha calculado. Faz parte do jogo. Nem tudo é derrota... tem coisas que são apenas humilhações mesmo...

Avançando...

private double[] CalcularDeltaErroCamadaDeEntrada(double[] saida, double[] deltas,  
  double[][] pesos)  
{  
    var delta = new double[saida.Length];  
    for (var i = 0; i < saida.Length; i++)  
    {  
        var erro = 0.0;  
        for (var j = 0; j < deltas.Length; j++)  
            erro += deltas[j] * pesos[i][j]; 
        delta[i] = erro * _funcoes.Derivada(saida[i]);  
    }  
    return delta;  
}

O erro é a soma dos produtos dos deltas da próxima camada e os pesos correspondentes da próxima camada.
O delta é o produto do erro e da derivada da função de ativação aplicada à saída do neurônio.

Os deltas são então retornados e usados para ajustar os Pesos e Viés durante o processo de treinamento.

Seguindo em frente temos o método AtualizarPesosEVies. Esse apenas percorre todos os Pesos do neurônio ajustando seu valor e em seguida faz o mesmo com o Viés.

public void AtualizarPesosEVies(double[] entrada, double delta, double taxaDeAprendizagem)  
{  
    for (var i = 0; i < Pesos.Length; i++)  
      Pesos[i] -= taxaDeAprendizagem * delta * entrada[i];  

    _vies -= taxaDeAprendizagem * delta;  
}

O método acima implementa a atualização dos pesos e do Viés de um neurônio usando o conceito gradiente descendente.

O gradiente descendente é um algoritmo de otimização usado para ajustar os pesos de uma rede neural. Ele minimiza a função de erro calculando o gradiente (a derivada) da função de perda em relação aos pesos e atualizando-os na direção oposta ao gradiente. Isso reduz gradualmente o erro da rede durante o treinamento, permitindo que ela aprenda padrões nos dados.

Nesse cálculo simples, nós podemos notar que a variável taxaDeAprendizagem tem como objetivo controlar o impacto das atualizações dos pesos e do Viés, influenciando a velocidade com que a rede neural aprende. Esse valor pode ser ajustado a fim de se melhorar o aprendizado da Rede Neural.

Basicamente passamos por todos os cálculos. Viu só? Não teve nada de "anormal", ou algum algoritmo "extraordinário".
Quando você debuga esses valores e entende o impacto deles no aprendizado, tudo fica muito mais fácil.

Testando e obtendo Métricas da qualidade da nossa Rede Neural

Após treinarmos nossa Rede, precisamos entender o quão bem ela aprendeu.
Nós repassamos os dados de entrada e os valores esperados de saída. Com isso foi possível treinar.
Agora nós precisamos repassar outro conjunto de dados de entrada e outro conjunto de valores esperados de saída.

Isso é uma informação importante. Nós precisamos separar nossa massa de dados em duas partes: Dados para treinamentos e dados para Teste. Jamais devemos testar nossa Rede Neural com os mesmos dados utilizados para treinamento.

O motivo?

Suponhamos que você esteja ensinando uma pessoa a resolver um tipo específico de problema. Você a treina com vários exemplos e, depois, decide avaliá-la com os mesmos problemas que ela já viu. Logo, obviamente, a pessoa terá um desempenho praticamente perfeito, pois já conhece as respostas! E com a nossa Rede Neural, acontece o mesmo

Se ela aprendeu de verdade, vai conseguir resolver praticamente qualquer problema (dentro do seu propósito, claro)! E é isso que queremos!!!

Vamos ver como funciona o método de Teste.

Na classe RedeNeural temos:

public MatrizDeConfusao Testar(Dataset dataset)  
{  
    var matrizDeConfusao = new MatrizDeConfusao(_tamanhoDosDadosDeSaida);  
    for (var i = 0; i < dataset.Entrada.Length; i++)  
    {  
        var resultadoCamadaDeEntrada = Processar(_camadaDeEntrada, dataset.Entrada[i]);  
        var resultadoCamadaDeSaida = Processar(_camadaSaida, resultadoCamadaDeEntrada);  

        var indiceEsperado = Array.IndexOf(dataset.SaidaEsperada[i], dataset.SaidaEsperada[i].Max());  
        var indicePredito = Array.IndexOf(resultadoCamadaDeSaida, resultadoCamadaDeSaida.Max());  

        matrizDeConfusao.AdicionarResultado(indiceEsperado, indicePredito);  
    }  
    return matrizDeConfusao;  
}

O que fazemos nesse método é obter o processamento da Camada de Entrada e o Processamento da Camada de Saída e utilizamos uma Matriz de Confusão para avaliar o desempenho. Como resultado dessa avaliação teremos uma tabela que compara as previsões da nossa Rede Neural com os valores reais (esperados), facilitando a identificação de acertos e erros para cada classe (Setosa, Versicolor e Virginica).

Em seguida temos indiceEsperado e indicePredito que se referem à identificação da classe correta e da classe que a rede neural previu, respectivamente. O índice esperado é o índice do valor máximo no vetor de saída esperada, enquanto o índice predito é o índice do valor máximo no vetor de saída gerado pela rede neural (Lembrando que os valores podem ser muito próximos de 0, ou muito próximos de 1) . Esses índices são usados para atualizar a matriz de confusão.

Basicamente podemos representar o valor dessa matriz dessa maneira:

Real / Previsto	Previsto: Setosa	Previsto: Versicolor	Previsto: Virginica
Real: Setosa	6	0	0
Real: Versicolor	0	5	0
Real: Virginica	0	0	5

Nesse caso, os valores da diagonal principal indica previsões corretas (6, 5 e 5) e os valores fora da diagonal mostram erros.
Eu tirei esses dados da execução dos testes da nossa Rede Neural.

Em outras palavras temos:

Quantas vezes a nossa Rede Neural previu que era Setosa e foi Setosa? 6!
Quantas vezes a nossa Rede Neural previu que era Versicolor e foi Versicolor? 5!
Quantas vezes a nossa Rede Neural previu que era Virginica e foi Virginica? 5!

Esses são os valores da diagonal principal.
Já nos outros valores temos:

Quantas vezes a nossa Rede Neural previu que era Setosa e foi Versicolor? 0!
Quantas vezes a nossa Rede Neural previu que era Setosa e foi Virginica? 0!
Quantas vezes a nossa Rede Neural previu que era Versicolor e foi Setosa? 0!
Quantas vezes a nossa Rede Neural previu que era Versicolor e foi Virginica? 0!
Quantas vezes a nossa Rede Neural previu que era Virginica e foi Versicolor? 0!
Quantas vezes a nossa Rede Neural previu que era Virginica e foi Setosa? 0!

Essa é a leitura da nossa matriz de confusão!

Esmiuçando o código da nossa classe MatrizDeConfusao temos:

public class MatrizDeConfusao(int numClasses, params string[] nomesDasClasses)  
{  
    private readonly int[,] _matriz = new int[numClasses, numClasses];

    public void AdicionarResultado(int esperado, int predito)  
      => _matriz[esperado, predito]++;

    private double CalcularAcuracia()
    {
        int corretos = 0, total = 0;
        for (var i = 0; i < _numClasses; i++)
        {
            for (var j = 0; j < _numClasses; j++)
            {
                total += _matriz[i, j];
                if (i == j) corretos += _matriz[i, j];
            }
        }

        return total == 0 ? 0.0 : (double)corretos / total;
    }

    private Dictionary<string, double> CalcularPrecisaoPorClasse()
    {
        var precisao = new Dictionary<string, double>(_numClasses);
        for (var i = 0; i < _numClasses; i++)
        {
            var tp = _matriz[i, i];
            var fp = 0;
            for (var j = 0; j < _numClasses; j++)
            {
                if (i != j) fp += _matriz[j, i];
            }

            var valor = (tp + fp) == 0 ? 0.0 : (double)tp / (tp + fp);
            precisao[_nomesDasClasses[i]] = valor;
        }

        return precisao;
    }

    private Dictionary<string, double> CalcularSensibilidadePorClasse()
    {
        var sensibilidade = new Dictionary<string, double>(_numClasses);
        for (var i = 0; i < _numClasses; i++)
        {
            var tp = _matriz[i, i];
            var fn = 0;
            for (var j = 0; j < _numClasses; j++)
            {
                if (i != j) fn += _matriz[i, j];
            }

            var valor = (tp + fn) == 0 ? 0.0 : (double)tp / (tp + fn);
            sensibilidade[_nomesDasClasses[i]] = valor;
        }

        return sensibilidade;
    }

    private Dictionary<string, double> CalcularF1ScorePorClasse()
    {
        var precisao = CalcularPrecisaoPorClasse();
        var sensibilidade = CalcularSensibilidadePorClasse();
        var f1 = new Dictionary<string, double>(_numClasses);

        for (var i = 0; i < _numClasses; i++)
        {
            var soma = precisao[_nomesDasClasses[i]] + sensibilidade[_nomesDasClasses[i]];
            var valor = soma == 0
                ? 0.0
                : 2 * (precisao[_nomesDasClasses[i]] * sensibilidade[_nomesDasClasses[i]]) / soma;
            f1[_nomesDasClasses[i]] = valor;
        }

        return f1;
    }

    public void ExibirMatriz()
    {
        Console.WriteLine("Matriz de Confusão:");
        for (var i = 0; i < _numClasses; i++)
        {
            for (var j = 0; j < _numClasses; j++)
            {
                Console.Write($"{_matriz[i, j],5}");
            }

            Console.WriteLine();
        }

        Console.WriteLine($"\nAcurácia: {CalcularAcuracia():F2}");

        var precisao = CalcularPrecisaoPorClasse();
        Console.WriteLine("Precisão por classe:");
        foreach (var (classe, valor) in precisao)
            Console.WriteLine($"    {classe}: {valor:F2}");


        var sensibilidade = CalcularSensibilidadePorClasse();
        Console.WriteLine("Sensibilidade por classe:");
        foreach (var (classe, valor) in sensibilidade)
            Console.WriteLine($"    {classe}: {valor:F2}");

        var f1 = CalcularF1ScorePorClasse();
        Console.WriteLine("F1-Score por classe:");
        foreach (var (classe, valor) in f1)
            Console.WriteLine($"    {classe}: {valor:F2}");
    }
}

Com a Matriz de Confusão carregada com os dados da predição e dados reais, podemos obter 4 métricas:

Acurácia: Indica a proporção de previsões corretas sobre o total de casos (total de entradas)
Precisão: Mostra a proporção de verdadeiros positivos entre todas as previsões positivas feitas pelaa nossa Rede Neural (quantas vezes eu disse que era Versicolor e, de fato, era Versicolor).
Sensibilidade (Recall): Mede a capacidade da nossa Rede Neural em identificar corretamente os casos positivos. Quando o recall está baixo, isso quer dizer que a nossa Rede Neural está classificando entradas de testes positivas como negativas (Eu passo informações de uma Versicolor, mas os cálculos sugerem que aqueles dados não representam a classe correta).
F1-Score: O F1-Score é a média harmônica entre Precisão e a Sensibilidade, variando de 0 a 1, onde 1 indica o melhor desempenho. Ele é útil quando se busca um equilíbrio entre identificar todos os exemplos positivos e evitar falsos positivos.

Todas essas métricas são fundamentais para que possamos ter uma noção exata de quão assertiva está nossa Rede Neural e, acima de tudo, entender quais pontos estão em desequilíbrio.

Imagine que nossa massa de dados para treinamento tenha muito mais amostras da classe Setosa do que das outras. Com isso, o resultado final pode não ser tão preciso para identificar Versicolor e Virginica, por exemplo. Por isso, é essencial avaliar as métricas de cada classe.

É importante destacar que o método Testar só pode ser invocado após o treinamento, com os dados em memória.
Inclusive, uma coisa que eu poderia ter feito, mas não fiz, é salvar o resultado do treinamento em um arquivo, e carregá-lo no momento de testes ou de predição.

E respondendo aquela pergunta lá do começo do post: - E o que é o resultado dessa aprendizagem? (Como eu consigo salvar esse resultado para que depois seja possível utilizá-lo para fazer a predição de um determinado valor?)

Simples: É toda a estrutura de valores que calculamos, Pesos e Viés de cada Neurônio de cada Camada e o nome da função de ativação, além dos parâmetros tamanhoDosDadosDeEntrada e tamanhoDosDadosDeSaida. Basicamente, tudo que pudesse inicializar a classe RedeNeural sem precisar efetuar todo os cálculos.

Será que funciona?

Vamos colocar para rodar tudo?

Na classe Program temos:

using RedeNeural.FeedForward;
using RedeNeural.FeedForward.Calculos;

double[][] dadosDeTreino =
[
    [5.1, 3.5, 1.4, 0.2],
    [4.9, 3.0, 1.4, 0.2],
    [4.7, 3.2, 1.3, 0.2],
    [4.6, 3.1, 1.5, 0.2],
    [5.0, 3.6, 1.4, 0.2],

    ...
];

double[][] dadosDeSaidasEsperadas =
[
    [1.0, 0.0, 0.0],
    [1.0, 0.0, 0.0],
    [1.0, 0.0, 0.0],
    [1.0, 0.0, 0.0],
    [1.0, 0.0, 0.0],

    ...
];

double[][] testData =
[
    [5.1, 3.8, 1.9, 0.4], // Iris-setosa       [1.0, 0.0, 0.0]
    [4.8, 3.0, 1.4, 0.3], // Iris-setosa       [1.0, 0.0, 0.0]
    [5.1, 3.8, 1.6, 0.2], // Iris-setosa       [1.0, 0.0, 0.0]
    [4.6, 3.2, 1.4, 0.2], // Iris-setosa       [1.0, 0.0, 0.0]
    [5.3, 3.7, 1.5, 0.2], // Iris-setosa       [1.0, 0.0, 0.0]
    [5.0, 3.3, 1.4, 0.2], // Iris-setosa       [1.0, 0.0, 0.0]
    [5.7, 3.0, 4.2, 1.2], // Iris-versicolor   [0.0, 1.0, 0.0]
    [5.7, 2.9, 4.2, 1.3], // Iris-versicolor   [0.0, 1.0, 0.0]
    [6.2, 2.9, 4.3, 1.3], // Iris-versicolor   [0.0, 1.0, 0.0]
    [5.1, 2.5, 3.0, 1.1], // Iris-versicolor   [0.0, 1.0, 0.0]
    [5.7, 2.8, 4.1, 1.3], // Iris-versicolor   [0.0, 1.0, 0.0]
    [6.7, 3.0, 5.2, 2.3], // Iris-virginica    [0.0, 0.0, 1.0]
    [6.3, 2.5, 5.0, 1.9], // Iris-virginica    [0.0, 0.0, 1.0]
    [6.5, 3.0, 5.2, 2.0], // Iris-virginica    [0.0, 0.0, 1.0]
    [6.2, 3.4, 5.4, 2.3], // Iris-virginica    [0.0, 0.0, 1.0]
    [5.9, 3.0, 5.1, 1.8], // Iris-virginica    [0.0, 0.0, 1.0]
];

double[][] dadosDeSaidasEsperadasDeTestes =
[
    [1.0, 0.0, 0.0],
    [1.0, 0.0, 0.0],
    [1.0, 0.0, 0.0],
    [1.0, 0.0, 0.0],
    [1.0, 0.0, 0.0],
    [1.0, 0.0, 0.0],
    [0.0, 1.0, 0.0],
    [0.0, 1.0, 0.0],
    [0.0, 1.0, 0.0],
    [0.0, 1.0, 0.0],
    [0.0, 1.0, 0.0],
    [0.0, 0.0, 1.0],
    [0.0, 0.0, 1.0],
    [0.0, 0.0, 1.0],
    [0.0, 0.0, 1.0],
    [0.0, 0.0, 1.0]
];

string[] classes = ["Setosa", "Versicolor", "Virginica"];  

var tamanhoDosDadosDeEntrada = dadosDeTreino[0].Length;  
var tamanhoDosDadosDeSaida = classes.Length;  
var nn = new RedeNeural.FeedForward.RedeNeural(  
    funcoes: Funcoes.Sigmoid,  
    tamanhoDosDadosDeEntrada: tamanhoDosDadosDeEntrada,  
     tamanhoDosDadosDeSaida: tamanhoDosDadosDeSaida); 

var datasetDeTreino = new Dataset(dadosDeTreino, dadosDeSaidasEsperadas);  
nn.Treinar(datasetDeTreino, 1000, 0.1);  

var datasetDeTeste = new Dataset(testData, dadosDeSaidasEsperadasDeTestes);  
var matrizDeConfusao = nn.Testar(datasetDeTeste);  
Console.WriteLine("\nMatriz de Confusão:");  
for (var i = 0; i < tamanhoDosDadosDeSaida; i++)  
{  
    for (var j = 0; j < tamanhoDosDadosDeSaida; j++)  
        Console.Write(matrizDeConfusao[i, j] + " ");  

    Console.WriteLine();  
}

var resultado = nn.Predizer([5.1, 3.5, 1.4, 0.2]);  
Console.WriteLine($"\nPredição: {string.Join(',', resultado)}");

Os dados de treino e teste utilizados pelas variáveis podem ser obtidos em https://www.kaggle.com/datasets/uciml/iris. No código fonte disponibilizado logo abaixo, temos os dados completos.

Acredito que o código seja bem descritivo, mas basicamente carregamos um datasetde treino e configuramos 1.000 épocas. Esse processo leva poucos segundos, dependendo do seu computador.

E seguida, efetuamos testes para validar o quanto a Rede Neural aprender.

E por fim, efetuamos a predição....

Ué, não vimos esse método...

Na classe RedeNeural temos:

public double[] Predizer(double[] entradas)  
{  
    var saidaCamadaDeEntrada = _camadaDeEntrada.Processar(entradas);  
    var saidaCamadaSaida = _camadaSaida.Processar(saidaCamadaDeEntrada);  
    return saidaCamadaSaida;  
}

👀

Se você entendeu o que o processamento das camadas faz, acredito que não preciso explicar o que é feito acima :)

Vamos ver o resultado dessa execução?

Treinando a rede neural...
...

Época: 1000 | Entrada[111] = 7.7,2.8,6.7,  2 | Saida[111] =   0,  0,  1 
Época: 1000 | Entrada[112] = 6.3,2.7,4.9,1.8 | Saida[112] =   0,  0,  1 
Época: 1000 | Entrada[113] = 6.7,3.3,5.7,2.1 | Saida[113] =   0,  0,  1 
Época: 1000 | Entrada[114] = 7.2,3.2,  6,1.8 | Saida[114] =   0,  0,  1 
Época: 1000 | Entrada[115] = 6.2,2.8,4.8,1.8 | Saida[115] =   0,  0,  1 
Época: 1000 | Entrada[116] = 6.1,  3,4.9,1.8 | Saida[116] =   0,  0,  1 
Época: 1000 | Entrada[117] = 6.4,2.8,5.6,2.1 | Saida[117] =   0,  0,  1 
Época: 1000 | Entrada[118] = 7.2,  3,5.8,1.6 | Saida[118] =   0,  0,  1 
Época: 1000 | Entrada[119] = 7.4,2.8,6.1,1.9 | Saida[119] =   0,  0,  1 

...

Testando a rede neural:

...

Entrada: [4.6,3.2,1.4,0.2] | Esperado: [  1,  0,  0] | Saída: [    0.9838999793395734,  0.016504203805423636, 0.0007969325625330965] 
Entrada: [5.3,3.7,1.5,0.2] | Esperado: [  1,  0,  0] | Saída: [    0.9849103762956705,  0.015523103824749402, 0.0007938171062215532] 
Entrada: [  5,3.3,1.4,0.2] | Esperado: [  1,  0,  0] | Saída: [    0.9844081188881989,   0.01599526311436517, 0.0007933646307086881] 
Entrada: [5.7,  3,4.2,1.2] | Esperado: [  0,  1,  0] | Saída: [  0.020482280154361238,    0.9858580861795864,  0.009577687957636695] 
Entrada: [5.7,2.9,4.2,1.3] | Esperado: [  0,  1,  0] | Saída: [   0.01987709852619787,    0.9855836017043265,  0.010048505871754942] 
Entrada: [6.2,2.9,4.3,1.3] | Esperado: [  0,  1,  0] | Saída: [  0.020092637518271544,    0.9861930905059628,  0.009627392164046341] 
Entrada: [5.1,2.5,  3,1.1] | Esperado: [  0,  1,  0] | Saída: [   0.03859736493992313,    0.9726434568195353,  0.007619628729616546] 
Entrada: [5.7,2.8,4.1,1.3] | Esperado: [  0,  1,  0] | Saída: [  0.020043842942311294,    0.9856808557186106,   0.00988123233268674] 

...

Matriz de Confusão:
    6    0    0
    0    5    0
    0    0    5

Acurácia: 1,00
Precisão por classe:
    Setosa: 1,00
    Versicolor: 1,00
    Virginica: 1,00
Sensibilidade por classe:
    Setosa: 1,00
    Versicolor: 1,00
    Virginica: 1,00
F1-Score por classe:
    Setosa: 1,00
    Versicolor: 1,00
    Virginica: 1,00

Predizer:
Entrada: [5.1,3.5,1.4,0.2] | Saída: [    0.9847084207102101,   0.01572765238679501, 0.0008048791443435225 ]

É isso!

Chegamos ao fim da nossa jornada épica de implementar uma Rede Neural do Zero em Csharp.
Você vai poder acessar o código fonte da aplicação e ver o toda a implementação. Um ponto importante é que eu coloquei no post apenas trechos de código. Você vai encontrar mais códigos no projeto csharp, porém nada que mereça explicações, apenas classes de apoio e métodos para formatação e apresentação de dados.
Recomento que você efetue testes com outras funções de ativação como ReLU e Tangente Hiperbólica e outros datasets como o Red Wine Quality onde é possível avaliar a qualidade de um vinho baseado em alguns parâmetros. A diversão aqui é boa!

Foram aproximadamente 5 semanas de estudos, quase que diários, para chegar nesse resultado.
O caminho foi longo, mas a satisfação é gigantesca.

E eu não posso deixar de agradecer o grande mestre Diego Nogare por todas as explicações.
Se não fosse ele, muitos conceitos não teriam sido esclarecidos!

Aliás, existe uma mina de ouro no seu github https://github.com/diegonogare/machinelearning: Aprendizado de Máquina através de exemplos práticos! Mais do que recomendado!!!

Além de todas as explicações ainda fui brindado com ótimas indicações de livros sobre o assunto:

Eu comprei o Redes Neurais: Princípios e Prática usado no Mercado Livre por um precinho bom. Fica a dica!

E caso queira baixar o código fonte, acesse https://github.com/angelobelchior/RedeNeural

Muito obrigado pela paciência, e caso tenha alguma dúvida, deixe ai nos comentários!

Fontes de Estudo

https://pt.wikipedia.org/wiki/Rede_neural_artificial
https://sites.icmc.usp.br/andre/research/neural/
https://aws.amazon.com/pt/what-is/neural-network/
https://embarcados.com.br/redes-neurais-artificiais/
https://elisaterumi.substack.com/p/redes-neurais-a-ia-inspirada-no-cerebro
http://leg.ufpr.br/~lucambio/Nonparam/NparamV.html
https://github.com/diegonogare/machinelearning
https://diegonogare.net/
https://en.wikipedia.org/wiki/Feedforward_neural_network

https://www.deeplearningbook.com.br/a-arquitetura-das-redes-neurais/

https://en.wikipedia.org/wiki/Activation_function
https://pt.wikipedia.org/wiki/Fun%C3%A7%C3%A3o_sigmoide
https://pt.wikipedia.org/wiki/Tangente_hiperb%C3%B3lica
https://en.wikipedia.org/wiki/Rectifier_(neural_networks)

https://machinelearningmastery.com/implement-backpropagation-algorithm-scratch-python/
https://www.ibm.com/br-pt/think/topics/gradient-descent
https://diegonogare.net/2020/04/performance-de-machine-learning-matriz-de-confusao/

https://dotnet.microsoft.com/en-us/learn/ml-dotnet

https://www.kaggle.com/datasets/uciml/iris
https://www.kaggle.com/datasets/uciml/red-wine-quality-cortez-et-al-2009

https://www.youtube.com/@UniversoProgramado
https://www.youtube.com/@MLparahumanos
https://www.youtube.com/@escoladeinteligenciaartifi6597

Black Sabbath - Live… Gathered In Their Masses FULL CONCERT HD

Rede neural do zero em Python #01

Rede neural do zero em Python: Modelo básico

O que é Rede Neural Artificial e como funciona | Pesquisador de IA explica | IA Descomplicada

Como uma Rede Neural Aprende? Tutorial para Leigos