Códigos de escape ANSI: o que cada um faz e qual padrão o define

O que são os códigos de escape ANSI

Uma sequência de escape é um trecho de caracteres comuns que o terminal lê como instrução em vez de imprimir. Quase todas as que aparecem começam pelo caractere de escape seguido de um colchete de abertura, depois alguns números e por fim uma letra que diz o que aqueles números significavam. Quando essa letra final é m, a sequência é SGR — Select Graphic Rendition — e os números são os códigos de cor e atributo que todo mundo chama de códigos de cor ANSI.

O mecanismo é simples e com estado: um código liga alguma coisa, e ela fica ligada até outro desligar. É por isso que esquecer o reset no fim de uma string colorida deixa o resto do prompt na cor errada, e por isso os códigos quase sempre são escritos aos pares.

O que não é simples é de onde eles vêm. Tudo que se publica sobre isso apresenta uma tabela única e achatada, e são três padrões vestindo uma sintaxe só. As cores e atributos comuns são do ECMA-48. As cores brilhantes são uma extensão do aixterm da IBM. Os códigos de 256 cores e de cor verdadeira vêm do ISO 8613-6, e a referência do xterm os descreve como marcados na quinta edição do ECMA-48 como reservados para padronização futura — ou seja, os dois códigos a que mais se recorre estão, no padrão que todo mundo cita para eles, reservados e não definidos.

Como usar

1. Cole saída de terminal ou escolha um exemplo. Os exemplos cobrem um log de build, a mesma cor escrita do jeito padrão, brilhantes contra comuns, uma sequência totalmente portátil e outra com duas coisas erradas.
2. Leia a prévia e a tabela de códigos. A prévia mostra o que um terminal desenharia. Abaixo, cada código SGR encontrado aparece com o padrão que o define e o que significa, e as notas explicam o que vale saber sobre o que você colou.
3. Monte uma e compare as grafias. Ative negrito, itálico e sublinhado, escolha uma cor, e a mesma instrução aparece duas vezes: uma com dois-pontos e outra com ponto e vírgula. Significam a mesma coisa e não são intercambiáveis.

O separador que ninguém escreve do jeito padrão

Os códigos de cor estendida levam subparâmetros: 38 diz que vem uma cor de frente, depois 5 e um índice da paleta de 256, ou 2 e três valores de canal para cor verdadeira. A referência do xterm escreve esses subparâmetros separados por dois-pontos e afirma sem rodeios que aceita tanto os dois-pontos, que chama de padrão, quanto o ponto e vírgula, que chama de legado. Todo tutorial, toda biblioteca e toda ferramenta emitem a forma com ponto e vírgula.

Não é questão de gosto, e o custo recai sobre a que você escolher. Lendo o código dos dois renderizadores JavaScript mais usados para isso, ambos separam parâmetros apenas por ponto e vírgula — um faz um split direto, o outro apara os pontos e vírgulas finais e separa igual — e nenhum contém dois-pontos em lugar nenhum do tratamento de parâmetros. Então a grafia que a referência chama de padrão é exatamente a que essas bibliotecas descartam em silêncio: a cor some e o texto sai sem estilo, sem erro algum em canto nenhum.

Há uma segunda vítima na mesma linha. A forma com dois-pontos da cor verdadeira carrega um identificador de espaço de cor antes do valor de vermelho, normalmente escrito vazio, de modo que a grafia completa tem uma lacuna que parece erro de digitação. A forma com ponto e vírgula não tem espaço nenhum para esse campo, e é por isso que quase ninguém sabe que ele existe.

O resumo honesto é que não existe grafia que seja ao mesmo tempo padrão e amplamente suportada, e por isso esta página diz qual troca a sua sequência está fazendo em vez de dizer que uma das duas é a certa. Se você escreve para um terminal, a forma com ponto e vírgula é a que os terminais esperam. Se escreve para uma especificação, a forma com dois-pontos é a que ela diz.

O que esta página não consegue dizer

As primeiras dezesseis cores não são fixadas por nada. Os códigos de 30 a 37 nomeiam uma cor, não um valor — como o vermelho realmente aparece é o que o tema do terminal de quem lê definir, e a mesma saída é uma imagem diferente em duas janelas lado a lado. A prévia aqui usa um conjunto comum para haver algo a ver, e isso é uma demonstração, não uma resposta. Do índice 16 para cima muda: o cubo de 216 cores e a rampa de 24 cinzas são definidos por aritmética, então esses são exatos.

A frase sobre reservados para padronização futura é a caracterização que o xterm faz do ECMA-48, não uma citação dele. O ECMA-48 é publicado como um PDF que resistiu à extração de texto todas as vezes que foi tentada aqui, então, em vez de parafrasear um documento que não pôde ser lido, a atribuição fica onde pode ser conferida: com a referência que faz a afirmação.

Só o SGR é interpretado. Uma sequência que move o cursor, limpa a tela ou define o título da janela é reconhecida, relatada e deixada em paz, porque renderizá-la significaria simular um terminal inteiro em vez de explicar um código de cor. Sequências que não começam com o par escape e colchete — os antigos controles de um caractere só e os comandos ao sistema operacional que definem título — ficam fora do que isto lê.

Por fim, isto descreve o que os códigos significam, não o que o seu terminal faz com eles. Piscar é ignorado quase em todo lugar. O fraco é ignorado por alguns e desenhado como uma cor mais apagada por outros. O sublinhado duplo é irregular. Um terminal pode não fazer absolutamente nada com um código que não implementa, e a maioria faz exatamente isso, caladamente.

Por que é grátis?

Analisar sequências de escape é manipulação de strings, e roda no seu navegador. Não há servidor no caminho, então não há o que cobrar nem conta a criar.

Nada é enviado, o que aqui importa mais que o normal: saída de terminal colada costuma trazer caminhos, nomes de máquina e um token ou outro. Recarregue a página e ela terá esquecido tudo.