Como Criar um Ficheiro INI: Regras de Sintaxe, Secções e Parsers

Um ficheiro INI é um ficheiro de configuração de texto simples que armazena definições como pares chave-valor, opcionalmente agrupados em secções nomeadas. O nome vem de «initialisation» (inicialização) — os ficheiros INI eram usados para inicializar aplicações Windows com as suas definições antes de existir o Registo do Windows. O formato nunca teve uma especificação formal, mas um padrão de facto surgiu do uso generalizado.

Onde os ficheiros INI são usados hoje

• Empacotamento Python — `setup.cfg`, `tox.ini`, `pytest.ini`, `mypy.ini`, `.flake8`
• Execução PHP — `php.ini` controla globalmente as definições do interpretador PHP
• MySQL / MariaDB — `my.ini` (Windows) e `my.cnf` (Unix) configuram o servidor de base de dados
• Git — `.gitconfig` e `.git/config` usam um formato tipo INI para definições de repositório e utilizador
• Wine — `wine.inf` configura a camada de compatibilidade do Windows em Linux e macOS
• Aplicações Windows — milhares de aplicações de ambiente de trabalho antigas e modernas guardam preferências em ficheiros `.ini` na pasta AppData

INI frente ao Registo do Windows

A Microsoft transferiu as definições das aplicações Windows para o Registo no início da década de 1990 por razões de desempenho e gestão centralizada. No entanto, muitos programadores continuam a preferir os ficheiros INI pela portabilidade — um ficheiro INI pode ser inspecionado e editado com qualquer editor de texto, submetido a controlo de versões e copiado entre máquinas sem qualquer ferramenta de exportação/importação. O Registo não pode.

Apesar da falta de uma especificação formal, a sintaxe INI segue convenções consistentes em praticamente todos os parsers. Estas são as regras em que pode confiar independentemente do que leia o seu ficheiro.

Um ficheiro INI é o formato de configuração mais simples possível: secções entre parênteses retos, pares chave-valor por baixo e ponto e vírgula para comentários. Todo o resto é específico do parser.

Regras universais

• Um par chave-valor por linha — `key = value` ou `key=value`; o espaço à volta de `=` é opcional mas o espaçamento consistente é legível
• Cabeçalhos de secção — `[NomeSecção]` na sua própria linha; sem conteúdo após o parêntese reto de fecho
• Linhas de comentário — começam com `;` para máxima compatibilidade; `#` é suportado por alguns parsers (`configparser` de Python, ferramentas Linux) mas não pelas APIs nativas do Windows
• Linhas em branco — ignoradas por todos os parsers; use-as livremente para separar grupos lógicos dentro de uma secção
• Sem aninhamento — o INI é plano: as secções contêm pares chave-valor, não outras secções
• Valores de cadeia — todos os valores são cadeias salvo se o parser os converter; `count = 5` é a cadeia "5" para a maioria dos parsers

O que o parser vê

O parser constrói um mapa de dois níveis: nome de secção → chave → valor. Se um ficheiro não tiver cabeçalhos de secção, os valores ficam numa secção implícita «predefinida» — o `configparser` de Python chama-lhe `DEFAULT`. Se o parser funde a secção predefinida com as secções nomeadas varia. As chaves e nomes de secção são tratados quase universalmente como insensíveis a maiúsculas por convenção, embora isto não seja garantido por todas as implementações.

Criar um ficheiro INI leva menos de cinco passos. A única ferramenta necessária é um editor de texto simples — qualquer editor que guarde como UTF-8 ou ASCII sem marca de ordem de bytes (BOM) funciona corretamente.

Os três elementos estruturais de um ficheiro INI — secções, chaves e valores — têm regras e casos extremos que vale a pena entender antes de escrever uma configuração que será lida pelo parser de outra pessoa.

Convenções de nomes de secção

Os nomes de secção vão entre parênteses retos e aparecem na sua própria linha. Podem conter letras, números, espaços e a maioria da pontuação — mas os espaços em nomes de secção são pouco suportados por alguns parsers e devem ser evitados. Use `[DatabaseConfig]` ou `[database_config]` em vez de `[database config]`. Nomes de secção duplicados são fundidos ou causam um erro dependendo do parser — trate-os como proibidos e valide com o Validador INI para detetar duplicados.

Regras de nomes de chaves

As chaves não devem conter o sinal `=` nem uma nova linha. Para além disso, as convenções variam, mas a prática mais segura é usar apenas letras minúsculas, dígitos e sublinhados — as mesmas regras dos nomes de variáveis Python. Evite hífenes nas chaves se planeia lê-las em Python com `configparser`, já que Python devolve as chaves como estão e chaves com hífen não podem ser acedidas como atributos.

Tipos de valor e valores multilinha

Todos os valores em ficheiros INI são cadeias salvo se o seu parser os converter explicitamente. `enabled = true` é a cadeia "true" — o seu código deve convertê-la num booleano. O `configparser` de Python fornece os métodos `getboolean()`, `getint()` e `getfloat()` para este propósito. Os valores multilinha são suportados por alguns parsers (o `configparser` de Python trata linhas com espaços iniciais como continuações do valor anterior) mas não todos — consulte a documentação do seu parser antes de confiar nisto.

A secção DEFAULT

O `configparser` de Python trata uma secção chamada `[DEFAULT]` (insensível a maiúsculas) como uma secção especial de recurso. Qualquer chave definida em `[DEFAULT]` está disponível em todas as outras secções como recurso — se uma secção não define uma chave, o valor de `[DEFAULT]` é devolvido. Este é um comportamento específico de Python não encontrado na maioria dos outros parsers. Se escreve ficheiros INI especificamente para Python, `[DEFAULT]` é uma forma útil de definir valores partilhados sem repeti-los em cada secção.

Os comentários e a codificação de caracteres são os dois aspetos dos ficheiros INI com maior probabilidade de causar problemas silenciosos quando os ficheiros são partilhados entre ferramentas, sistemas operativos ou linguagens diferentes.

Caracteres de comentário: ; vs #

O ponto e vírgula (`;`) é o carácter de comentário universalmente suportado — funciona no `configparser` de Python, nas APIs nativas do Windows, no `parse_ini_file()` do PHP, no MySQL e em praticamente qualquer outro parser INI. O cardinal (`#`) é suportado pelo `configparser` de Python e pela maioria dos parsers baseados em Linux, mas não pelo `GetPrivateProfileString()` do Windows. Se o seu ficheiro INI só será lido por Python, qualquer carácter é seguro. Para ficheiros multiplataforma, use exclusivamente `;`.

Codificação de caracteres: UTF-8 vs Windows-1252

Guarde os ficheiros INI como UTF-8 sem BOM para ferramentas modernas. O BOM (marca de ordem de bytes, o carácter invisível `\uFEFF` no início de alguns ficheiros UTF-8 guardados por ferramentas do Windows) causa problemas com parsers que o tratam como parte do primeiro nome de chave. O `configparser` de Python lida com UTF-8 nativamente desde o Python 3. Se escreve um ficheiro INI para uma aplicação Windows antiga que espera codificação Windows-1252, alinhe com o que a aplicação espera — misturar codificações é uma fonte comum de corrupção de caracteres nos valores.

Fins de linha

Os ficheiros INI funcionam tanto com fins de linha do Windows (CRLF, `\r\n`) como do Unix (LF, `\n`). Use a convenção de fins de linha da sua plataforma destino. Se edita um ficheiro INI no Windows para implementação em Linux, configure o seu editor de texto para guardar com fins de linha LF para evitar que o carácter de retorno de carro apareça nos valores em parsers Linux. O Formatador INI normaliza fins de linha e espaçamento numa única passagem.

A maioria das linguagens fornece um parser integrado ou de biblioteca padrão para ficheiros INI. Aqui estão as abordagens padrão para os ambientes mais comuns.

Python: configparser

O módulo `configparser` de Python é a forma padrão de ler ficheiros INI em Python. Importe-o, crie uma instância `ConfigParser()`, chame `.read()` com o seu nome de ficheiro e aceda aos valores com `config["NomeSecção"]["chave"]` ou `config.get("NomeSecção", "chave")`. O método `.get()` aceita um argumento `fallback` que devolve um valor predefinido quando a chave falta — útil para valores de configuração opcionais. Use `getboolean()`, `getint()` e `getfloat()` para valores tipados em vez de converter cadeias manualmente.

PHP: parse_ini_file()

O PHP fornece `parse_ini_file($filename, $process_sections)` como função integrada. Com `$process_sections = true`, a função devolve um array associativo aninhado organizado por nome de secção. Com `false`, devolve um array plano com todas as chaves fundidas. O parser do PHP é rigoroso quanto a certos caracteres especiais em valores sem aspas — valores contendo =, chavetas de abertura/fecho, |, &, ~, !, [, ] precisam de estar entre aspas no ficheiro INI para serem parseados corretamente.

Node.js e outros ambientes

O Node.js não tem um parser INI integrado, mas o pacote npm `ini` (licença MIT) fornece uma interface padrão `parse()` e `stringify()`. Para Java, a biblioteca `org.ini4j` é a escolha padrão. Para Go, o pacote `gopkg.in/ini.v1` é a opção mais usada. Em cada caso, a biblioteca lida com a mesma estrutura de dois níveis secção/chave — as formas da API variam mas o formato subjacente é idêntico.

O INI nem sempre é o formato de configuração certo. Entender onde se encaixa — e onde TOML ou YAML é uma melhor escolha — ajuda-o a tomar a decisão certa para novos projetos.

Quando usar INI

O INI é a escolha certa quando a sua configuração tem dois níveis de profundidade (secções e pares chave-valor planos), quando o parser destino já espera formato INI (PHP, ecossistema Python, MySQL, Git) e quando quer o formato mais simples possível que qualquer programador possa ler sem conhecimento prévio. Não é apropriado para configurações que precisem de arrays, objetos aninhados ou dados tipados.

Quando usar TOML ou YAML em vez disso

Escolha TOML quando a sua configuração precisar de valores tipados, arrays ou tabelas em linha e quiser uma especificação rigorosa com parsing previsível. O TOML é o formato de `pyproject.toml`, `Cargo.toml` e dos ficheiros de configuração do Hugo. Escolha YAML quando precisar de estruturas profundamente aninhadas ou trabalhar num ecossistema onde o YAML já é padrão — Kubernetes, GitHub Actions, Docker Compose e Ansible são ambientes YAML-first.