Brainduck-rs: Turing Machine Interpreter

Um interpretador de alta performance para a linguagem Brainfuck, modelado como uma Máquina de Turing. Este projeto serve como uma prova de conceito para a aplicação de Arquitetura Hexagonal e Estratégias de Despacho Híbrido em Rust.

---

Destaques de Engenharia

Este projeto não é apenas um interpretador, é um exercício de design de sistemas robustos:

• Arquitetura Hexagonal (Ports & Adapters): O núcleo da Máquina de Turing é 100% isolado de efeitos colaterais. Toda a entrada (CLI, arquivos, teclado) e saída é feita através de Ports (Traits).

• Hybrid Dispatch Strategy: * Static Dispatch (Generics): Utilizado no loop crítico do interpretador para garantir performance de tempo de execução igual ao C++.

• Dynamic Dispatch (Box<dyn>): Utilizado na infraestrutura para permitir composição flexível de adaptadores sem poluição de tipos genéricos.

• Composição de Adapters: Uso do padrão Strategy para desacoplar a origem do caminho do arquivo (PathProvider) da lógica de extração de dados (CodeFetcher).

---

Visão Geral da Arquitetura

O diagrama abaixo ilustra como os componentes se comunicam através de interfaces, mantendo o domínio protegido.

graph LR
    subgraph "External World"
        OS[Operating System]
        User[Terminal User]
    end

    subgraph "Infrastructure (Adapters)"
        CLI[CLIAdapter]
        FS[FileSystemExtractor]
        TI[TerminalInput]
        TO[TerminalOutput]
    end

    subgraph "Domain (Ports)"
        PP[PathProvider]
        CF[CodeFetcher]
        IP[InputProvider]
        OW[OutputWriter]
    end

    subgraph "Core (Application)"
        TM[TuringMachine]
    end

    OS --> CLI
    CLI --> PP
    FS -- uses --> PP
    FS --> CF
    CF --> TM
    User --> TI
    TI --> IP
    TO --> OW
    TM --> IP
    TM --> OW

Loading

---

Documentação de Decisões (ADRs)

Para entender os "porquês" por trás do código, consulte nossos registros de decisão de arquitetura:

1. ADR 0001: Escolha do Rust - Foco em segurança de memória e performance.
2. ADR 0002: Arquitetura Hexagonal - Desacoplamento via Traits.
3. ADR 0003: Dispatch Híbrido - Otimização de performance no "Hot Path".
4. ADR 0004: Composição de Adapters - SRP e modularidade.
5. ADR 0005: Modelo de Domínio - Lógica da Máquina de Turing.

---

Como Executar

Pré-requisitos (Windows)

Este projeto requer o linker do Visual Studio (link.exe).

1. Instale o Visual Studio Build Tools.
2. Selecione a carga de trabalho "Desenvolvimento para desktop com C++".

Instalação

git clone https://github.com/neoRandom/brainduck-rs.git
cd brainduck-rs
cargo build --release

Uso

# Executar um arquivo Brainfuck
cargo run -- caminho/do/script.bf

---

Troubleshooting (Resolução de Problemas)

Erro	Causa	Solução
link.exe not found	Toolchain MSVC ausente	Instale o C++ Build Tools no VS Installer
No file path	Argumento CLI faltando	Certifique-se de passar o caminho do arquivo após --
Unexpected Character	Script BF inválido	O interpretador ignora caracteres que não sejam ><+-.,[]

---

Testes

O design modular permite testar o Core sem interações reais de I/O:

cargo test

Os testes utilizam Mock Adapters para simular entradas de usuário e validar a fita de memória da máquina de forma determinística.

---

Licença

Distribuído sob a licença MIT. Veja LICENSE para mais detalhes.