Conversor de CSV para JSON

O que esta ferramenta faz

O CSV é o que as folhas de cálculo, as exportações de bases de dados e os painéis de análise lhe entregam; o JSON é o que as APIs e o código querem. Esta ferramenta converte entre ambos nos dois sentidos, no seu navegador. Cole CSV e obtém um array JSON — objetos com as chaves da linha de cabeçalho, ou arrays simples quando os dados não a têm. Troque o sentido e um array JSON volta a ser CSV, com cada valor entre aspas exatamente na medida necessária.

O trabalho acontece no seu dispositivo, e aqui isso importa: o CSV é o formato para onde se exportam listas de clientes, faturas e extratos analíticos. Nada disso é enviado para lado nenhum.

Porque dividir por vírgulas não chega

A forma óbvia de ler CSV — dividir cada linha por vírgulas — falha com ficheiros reais, porque o formato tem um mecanismo de escape. Um campo entre aspas duplas pode conter o delimitador, uma aspa literal escrita como duas aspas seguidas e até quebras de linha, caso em que um registo se estende por várias linhas do ficheiro. Esta ferramenta aplica as regras verdadeiras (RFC 4180) com um analisador caractere a caractere, por isso os três casos chegam intactos.

name,note
Grace,"rear admiral, USN"
Ada,"she said ""hello"""
Alan,"two
lines"

Estes quatro registos têm dois campos cada um, apesar das vírgulas, aspas e da quebra de linha a mais. Se as aspas estiverem malformadas — um campo abre uma aspa e nunca a fecha — recebe a linha e a coluna onde a aspa descontrolada começou, em vez de uma tabela silenciosamente deformada.

O delimitador muitas vezes não é uma vírgula

Apesar do nome, os valores separados por vírgulas muitas vezes não o são. Nas configurações regionais em que a vírgula é o separador decimal — quase toda a Europa continental — o Excel exporta com ponto e vírgula, porque aí 1,50 é um número. As ferramentas de bases de dados e de linha de comandos produzem frequentemente dados separados por tabulações, e os pipelines de registos preferem barras verticais. Colar um desses numa ferramenta que só entende vírgulas produz uma única coluna larguíssima: a frustração mais comum com CSV.

Por isso o delimitador é detetado em vez de assumido. Cada candidato é experimentado e vence o que dá o mesmo número de colunas em todas as linhas — consistência, não a contagem mais alta, porque de outro modo um ficheiro cheio de vírgulas decimais pareceria separado por vírgulas. O delimitador detetado é sempre mostrado e pode alterá-lo se o palpite estiver errado.

Cabeçalhos e a forma da saída

Com «a primeira linha é um cabeçalho» ativo, essa linha fornece os nomes das chaves e a saída é um array de objetos — a forma que quase todas as APIs esperam. Desativado, cada linha passa a ser um array de valores, que é o que se quer para um ficheiro que começa logo com dados.

• Uma linha com menos campos do que o cabeçalho recebe strings vazias nas colunas em falta, em vez de chaves com valor undefined.
• Nomes de cabeçalho duplicados tornam-se únicos (id, id_2, id_3) em vez de se sobreporem uns aos outros, o que faria desaparecer colunas em silêncio.
• Uma célula de cabeçalho vazia passa a column_2, column_3 e por aí fora, para que nenhuma chave seja a string vazia.
• As linhas em branco são ignoradas, como fazem os importadores de folhas de cálculo: um ficheiro colado termina muitas vezes com uma quebra de linha solta, e uma linha de valores vazios aí parece um erro.

Conversão de tipos que não pode perder dados

Todo o campo CSV é texto. Converter texto que parece numérico em números JSON costuma ser o que se quer — mas é também a forma como os dados são destruídos em silêncio. Um código postal 01234 passa a 1234. Um número de encomenda de 20 dígitos passa a um decimal arredondado. Um preço escrito 1.50 perde o zero final.

A regra usada aqui evita tudo isso sem uma lista de casos especiais: um valor só se torna número se ao voltar a texto reproduzir exatamente o original. 42 consegue, por isso é convertido. 01234 não, por isso permanece string. Nem 1.50, +5, 1e5, nem qualquer inteiro para lá do ponto em que os decimais perdem precisão. As strings true e false tornam-se booleanos; um campo vazio permanece string vazia em vez de se tornar null, porque o CSV não consegue exprimir a diferença entre «sem valor» e «valor vazio», e inventar uma seria inventar informação.

De volta ao CSV

No sentido inverso, um array de objetos torna-se uma tabela cujas colunas são a união de todas as chaves, pela ordem em que aparecem pela primeira vez — assim linhas com chaves diferentes continuam alinhadas, e uma chave em falta produz uma célula vazia. Um array de arrays é escrito linha a linha. As aspas são aplicadas apenas onde o formato exige: um valor que contenha o delimitador, uma aspa ou uma quebra de linha é envolvido, com as aspas interiores duplicadas.

Os valores que o CSV não consegue representar — um objeto ou array aninhado — são escritos como JSON dentro da sua célula, em vez de achatados ou descartados, para que nada desapareça numa conversão. Null torna-se uma célula vazia.