Numerar as linhas de um texto para uma revisão a várias mãos

Porque é que um texto partilhado precisa de números

O código chega já com números. O editor mostra-os na margem esquerda, um diff imprime-os de ambos os lados da alteração e um comentário de revisão numa plataforma de alojamento agarra-se a um deles. A prosa não. Uma cláusula de contrato, um conjunto de legendas, uma exportação de memória de tradução, uma lista de nomes de produto à espera de ser verificada por dois colegas: nenhum destes textos tem uma forma estável de dizer «o quarto a contar de cima» que não seja contar.

É a contagem à mão que faz descarrilar a revisão. Duas pessoas contam a partir de sítios diferentes, uma inclui a linha em branco e a outra não, e uma hora depois há duas correções sobre a mesma cláusula e uma sobre uma cláusula que ninguém queria mexer. Pôr um número em cada linha antes de fazer circular o texto elimina toda essa família de mal-entendidos ao preço de uma colagem.

A palavra importante é «antes». Os números são um sistema de coordenadas, e um sistema de coordenadas só serve enquanto não se mexe. Se alguém renumerar um texto já anotado, cada comentário passa a ser um palpite. Numere uma vez, faça circular exatamente essa versão e recolha as correções contra ela.

O que a ferramenta produz de facto

Por omissão é um ponto e um espaço: «first line» passa a «1. first line». São oferecidos outros dez separadores: «1) », «1: », «1 - », «1 | », «[1] », «1] », «#1 », «1 → », um espaço simples e uma tabulação. Dois deles envolvem o número em vez de o seguir, e é por isso que «[1] » e «#1 » têm outro aspeto.

O alinhamento é calculado a partir do último número e aplicado com espaços normais, não com zeros. Um texto de 102 linhas volta com « 1. line1» em cima e « 102. line102» em baixo, com os algarismos alinhados à direita. A largura é decidida de uma vez, antes da primeira linha, por isso um texto de 99 linhas tem largura dois e um de 100 linhas tem largura três: mais um espaço em cada linha por causa de uma única linha acrescentada. Se estiver a comparar duas versões numeradas, é essa a razão de todas as linhas aparecerem como alteradas.

Vale a pena conhecer três comportamentos pequenos antes de colar algo longo. Uma quebra de linha final produz uma linha vazia numerada no fim, porque dividir «a\nb\n» pelas quebras dá três pedaços e o terceiro está vazio: a saída acaba em «3. ». Uma entrada vazia produz «1. » em vez de nada. E uma entrada com fins de linha do Windows volta com fins de linha Unix: a divisão aceita um retorno de carro antes do avanço de linha, mas a junção só repõe o avanço de linha.

Começar em 1, e só em 1 — ou num número negativo

A caixa «Começar em» existe porque um excerto numerado costuma vir de algum lado: a página quatro de uma transcrição não devia recomeçar em 1. Ponha-a a 500 e a saída dá 500, 501, 502, com largura de três. Até aí funciona como anunciado.

O zero é a exceção, e não é uma falha que se contorne escrevendo-o de outra maneira. O valor é lido como Number(start) || 1. O zero é um dos valores falsy do JavaScript, logo a expressão cai em 1: escrever 0 e não escrever nada dão o mesmo resultado. Quem quisesse uma numeração ao estilo dos arrays, com a primeira linha como linha 0, não a terá aqui. Uma caixa vazia comporta-se do mesmo modo, e um valor que não é um número também: «abc» dá 1.

Os arranques negativos, curiosamente, funcionam, porque −3 é truthy. Três linhas a começar em −3 voltam como «-3. », «-2. », «-1. »: não serve para nada em concreto, mas mostra que a salvaguarda é sobre a falsiness e não sobre o sinal. Os valores fracionários são arredondados para menos infinito: 2,7 passa a 2 e −2,7 passa a −3.

O regresso, que não é simétrico

O remove-line-numbers não tem qualquer opção. Aplica um único padrão a cada linha: espaços ou tabulações iniciais, depois o número e a sua marca — algarismos seguidos de uma tabulação, ou algarismos entre parênteses retos ou precedidos de um cardinal, ou algarismos seguidos de um ponto, de um parêntesis de fecho, de dois pontos, de um parêntesis reto de fecho ou de uma seta — e a seguir um só espaço, ou o fim da linha. Tudo o que corresponde é apagado, uma vez por linha. Dois pormenores dessa frase fazem todo o trabalho: a marca tem de ser seguida de um espaço, e o espaço consumido é exatamente um.

Passe os onze separadores pela ferramenta e oito sobrevivem à viagem: ponto, parêntesis, dois pontos, tabulação, «[1] », «1] », «#1 » e «1 → » voltam exatamente ao texto original. Três não, e a omissão é deliberada. «1 - alpha», «1 | alpha» e «1 alpha» voltam inalterados, com os números ainda presos, porque «5 - 3 = 2», «10 - 20 people», «1 | Alice | 30» e «007 James» têm exatamente a mesma forma e são conteúdo muito mais vezes do que numeração. Uma ferramenta de remoção que desfizesse esses três comeria uma linha de folha de cálculo sempre que alguém colasse uma.

O padrão acabava com uma sequência gananciosa de espaços, que levava a indentação do próprio texto; agora toma exatamente um. Numere cinco linhas de JavaScript com uma função, um if e um return, retire-lhes os números, e o ficheiro volta byte a byte, com as indentações. O YAML e o Python comportam-se do mesmo modo, e é aí que isso mais conta: nessas duas linguagens um resultado achatado não é apenas feio, já não quer dizer o mesmo.

Uma ferramenta de remoção não sabe de quem é o número

Este é o limite honesto de toda a ideia, e a regra do espaço estreita-o sem o eliminar. «1. Lavar o arroz» é uma linha numerada se foi a ferramenta a pôr o 1, e é conteúdo se foi o cozinheiro. Nada na cadeia distingue as duas coisas, e nenhum padrão o pode fazer: essas duas linhas são os mesmos bytes. Exigir um espaço depois do separador afasta os acidentes — «3.14 is pi» e «1.2.3 version» voltam agora intactos, porque um ponto decimal nunca é seguido de um espaço — mas não afasta as coincidências. «12: 30 departure» continua a voltar como «30 departure». «2026. A year.» continua a voltar como «A year.» Ambas são, carácter a carácter, o que o add-line-numbers escreve; numa linha que ninguém numerou, isso continua a ser perda de dados.

Duas coisas mantêm o caso corrente a salvo. A remoção acontece uma vez por linha e para no primeiro separador: uma lista de preços escrita à inglesa, numerada, dá «1. 12.50 Coffee», e retirar-lhe o número reconhece «1. » e para, devolvendo «12.50 Coffee» intacto; uma lista que já tinha os seus números, «1. 1. alpha», perde exatamente um nível. E essa linha de preço sobrevive agora mesmo sem a numeração, porque o ponto de «12.50» não é seguido de um espaço. A ida e volta é, portanto, segura em qualquer texto, indentado ou plano, com qualquer um dos oito separadores. O que ainda morde é a ferramenta de remoção sozinha, aplicada a um texto que ninguém numerou, no estreito conjunto de linhas que se parecem com a sua própria saída.

Perceber porque é que algo é seguro é mais útil do que a lista. Um CSV de identificadores sobrevive — «1024, Dupont, 42» volta intacto — porque o carácter a seguir aos algarismos é uma vírgula, e a vírgula não aparece em nenhuma das formas de marca. «100 units of flour» e «007 James» sobrevivem porque um espaço simples também não é uma. As decimais e as versões semânticas são seguras também, mas pela outra razão: «3.14» e «1.2.3» levam mesmo um ponto, e o que as salva é não lhe seguir nenhum espaço. O que corre risco é o estreito conjunto em que um número, uma marca reconhecida e um espaço chegam por essa ordem: os anos usados como títulos, «12: 30» escrito com espaço depois dos dois pontos, e — novidade desde que o conjunto de marcas se alargou — as chamadas de nota do tipo «[1] » e as linhas que abrem com «#1 ».

Conduzir a revisão sem perder nada

Guarde o original sem numeração num sítio onde não o vá sobrescrever e trate a versão numerada como uma impressão: algo para ler, citar e anotar, não para editar e devolver. Cada correção recolhida como «linha 47, substituir X por Y» aplica-se limpamente ao original, e os números nunca precisam de ser retirados.

Se tenciona mesmo retirar os números mais tarde, evite exatamente três separadores: o travessão, a barra vertical e o espaço simples. Todo o resto do menu — ponto, parêntesis, dois pontos, tabulação, «[1] », «1] », «#1 », «1 → » — sai sem dificuldade. Prefira a tabulação se o texto passar perto de uma folha de cálculo: põe os números na sua própria coluna.

Numerar código que tencione voltar a colar é agora viável, o que antes não era: com um ponto, um parêntesis, dois pontos ou uma tabulação, o ficheiro volta byte a byte, com a indentação. Continua a ser raramente o gesto certo — uma revisão de código tem melhores instrumentos: um diff, um pull request, ou simplesmente os números de linha que o editor já vos mostra aos dois — mas, se o fizer, escolha um desses quatro e faça primeiro a ida e volta numa cópia.

Perguntas frequentes

Posso fazer a numeração começar em 0?

Não, e não há truque que o contorne. A ferramenta lê a caixa como Number(start) || 1. O zero é falsy em JavaScript, portanto a expressão deita-o fora e devolve 1: escrever 0, deixar a caixa vazia ou escrever uma palavra produzem todos uma lista que começa em 1. Verificado com 0, «0», «» e «abc»: os quatro deram a mesma saída. Se precisa de numeração a partir de zero, numere a partir de 1 e subtraia um de cabeça, ou numere a partir de −1 se o desvio importar mais do que o sinal: os arranques negativos funcionam, porque um número negativo é truthy.

Os números continuam alinhados quando o texto passar das 100 linhas?

Sim. A largura é calculada a partir do último número antes de se escrever seja o que for, e cada número é preenchido à esquerda com espaços até essa largura. Um texto de 102 linhas começa com dois espaços antes da linha 1 e nenhum antes da 102: os pontos formam uma coluna direita. Não há zeros à esquerda — obtém « 7. », nunca «007. ». Uma consequência apanha muita gente: um texto de 99 linhas usa largura dois e o mesmo texto com mais uma linha usa largura três, portanto cada linha muda um espaço. Se comparar duas versões numeradas com um diff, é por isso que o ficheiro inteiro parece alterado. Compare antes os originais.

O remove-line-numbers desfaz sempre o add-line-numbers?

Não, mas as razões mudaram. Reconhece oito dos onze separadores — ponto, parêntesis de fecho, dois pontos, tabulação, «[1] », «1] », «#1 » e «1 → » — e deixa de propósito o travessão, a barra vertical e o espaço simples, porque «10 - 20 people», «1 | Alice | 30» e «007 James» têm a mesma forma e são quase sempre conteúdo. Com um separador reconhecido, a ida e volta é agora byte a byte, com a indentação incluída: cinco linhas de JavaScript com um corpo de função indentado a quatro e a oito espaços entraram e voltaram idênticas, e o mesmo com YAML, Python e uma lista de preços plana.

Passei a ferramenta de remoção por uma lista de preços e comeu parte deles. O que aconteceu?

Já não o pode fazer. A ferramenta apagava antes os algarismos iniciais seguidos de um ponto, de um parêntesis de fecho, de dois pontos ou de uma tabulação, sem exigir nada a seguir — daí «3.14 is pi» passar a «14 is pi» e «12.50 Coffee» a «50 Coffee». O padrão exige agora um espaço, ou o fim da linha, depois do separador, e um ponto decimal nunca é seguido de um espaço: «3.14 is pi», «1.2.3 version» e «12.50 Coffee» voltam todos intactos. O que ainda pode levar é uma linha com a forma exata da sua própria saída — «2026. A year.» dá «A year.», «12: 30 departure» dá «30 departure» — e, desde que o conjunto de marcas se alargou, as chamadas de nota: «[1] See note» dá «See note». Uma lista separada por vírgulas é segura em qualquer caso, porque a vírgula não aparece em nenhuma forma de marca.

Devo numerar código-fonte para uma revisão de código?

Em geral não, embora já não seja arriscado. O código já traz números de linha onde quer que seja lido — na margem do editor, num diff, na interface de revisão de qualquer plataforma — por isso numerá-lo acrescenta sobretudo ruído. Sobrevive agora à ida e volta: com um ponto, um parêntesis, dois pontos ou uma tabulação, numerar um ficheiro indentado e retirar-lhe os números devolve-o byte a byte, com a indentação, o que antes não acontecia. Três separadores continuam a nunca ser removidos — o travessão, a barra vertical e o espaço simples — evite-os, portanto, se os números tiverem de sair. A numeração ganha o seu lugar em textos sem números próprios, lidos fora de uma ferramenta que os forneça: um contrato distribuído como documento, um ficheiro de legendas discutido num fio de conversa, uma lista de cadeias enviada a um tradutor. Se está a rever código e a plataforma está fora de alcance, citá-lo num bloco e referir-se a ele pelo nome da função continua a ser a via mais calma.