🗮️ Gleam BR: XML SAX Parser

*Um parser SAX (Simple API for XML) de altíssima performance e baixo consumo de memória, construído em Gleam.*

Este pacote atua como um wrapper Type-Safe sobre o xmerl_sax_parser nativo da Máquina Virtual Erlang (BEAM), permitindo o processamento de grandes arquivos XML sem sobrecarregar a memória.

🎯 Por que o gbr_xml existe?

O processamento de arquivos XML gigantescos (como diagramas BPMN do Camunda ou feeds de dados corporativos) pode ser um pesadelo de performance se tentarmos carregar todo o documento na memória (DOM). Além disso, a biblioteca nativa xmerl do Erlang utiliza átomos e estruturas complexas que podem causar erros difíceis de depurar em Gleam.

O gbr_xml resolve esse problema ao: - Utilizar a arquitetura *SAX (Simple API for XML), que lê o arquivo como um fluxo contínuo de eventos. - Fornecer uma ponte FFI segura que converte os tipos dinâmicos do Erlang em *Custom Types elegantes do Gleam**. - Garantir que o Garbage Collector não seja sobrecarregado, mantendo a pegada de memória constante independente do tamanho do XML.

📦 Instalação

Adicione o gbr_xml ao seu projeto Gleam:

gleam add gbr_xml

🛠️ Como Utilizar

O gbr_xml utiliza uma abordagem funcional de fold/reduce. Você fornece um estado inicial e uma função de callback que reage aos eventos do parser.

import gbr_xml.{Attribute, Characters, EndElement, StartElement}
import gleam/io
import gleam/string

pub fn main() {
  let xml = "<hello id=\"1\">world</hello>"

  // Callback que processa os eventos do XML
  let callback = fn(event, acc: List(String)) {
    case event {
      StartElement(name, attributes) -> {
        // Acessa atributos de forma tipada
        [name, ..acc]
      }
      Characters(text) -> [text, ..acc]
      EndElement(name) -> ["end_" <> name, ..acc]
      _ -> acc
    }
  }

  // Executa o parse com estado inicial (lista vazia)
  let assert Ok(result) = gbr_xml.parse_string(xml, [], callback)

  io.println(string.inspect(result))
  // -> ["end_hello", "world", "hello"]
}

🚦 Quando usar (e quando não usar)

✅ Use o gbr_xml quando: - Você precisa processar *arquivos XML muito grandes* (BPMN, XML de notas fiscais, dumps de banco de dados). - O baixo consumo de memória e a performance de fluxo são prioridades. - Você quer uma API Gleam limpa e tipada para interagir com o parser nativo do Erlang.

❌ Não use o gbr_xml se: - Você está compilando para o target javascript (esta biblioteca depende do xmerl da BEAM). - Você precisa de uma árvore DOM completa para navegar livremente pelo documento (ex: XPath aleatório). Para arquivos pequenos, considere converter os eventos SAX em um tipo de dado personalizado. - O XML possui namespaces extremamente complexos que exigem validação de esquema (XSD) em tempo real.

🤝 Contribuindo

Seja bem-vindo(a) à comunidade! O ecossistema gleam-br é construído com carinho para todos. Consulte nosso Guia de Contribuição antes de abrir uma Pull Request.

Desenvolvido com ❤️ para a comunidade Gleam. 🚀