Generatore di tabelle Markdown

Quattro formati in ingresso, uno in uscita

Una tabella Markdown è facile da scrivere e faticosa da mantenere. Basta aggiungere una parola in una cella perché tutte le barre verticali sotto vadano fuori squadra, e mettere insieme una tabella da dati che hai già — il risultato di una query, un export da un foglio di calcolo, la risposta di un’API — significa ribatterla a mano. Questo strumento prende i dati nella forma in cui li hai e restituisce una tabella pulita nel Markdown di GitHub.

Legge quattro formati, e ti dice per quale ha optato invece di deciderlo in silenzio:

• Una tabella Markdown, così una tabella che ha perso l’allineamento si incolla com’è e torna dritta.
• CSV, analizzato secondo la RFC 4180: un campo fra virgolette può contenere virgole, virgolette e persino a capo, e tutto sopravvive.
• TSV, che è ciò che si ottiene copiando un intervallo da un foglio di calcolo o da un client di database.
• Un array JSON, di oggetti (le chiavi diventano colonne) oppure di array (la prima riga diventa l’intestazione).

Il rilevamento cerca prima l’indizio più inequivocabile: una parentesi quadra iniziale può essere solo JSON, una riga di trattini può essere solo la riga separatrice di Markdown, una tabulazione nella prima riga può essere solo TSV. La separazione per virgole è ciò che resta, quindi viene annunciata come ripiego e non come scoperta: se lo strumento ha dovuto tirare a indovinare lo dice, e il selettore di formato ha la precedenza.

L’uscita è Markdown e solo Markdown. Riconvertire una tabella in CSV o JSON è un altro mestiere, e questo sito ha già strumenti che lo fanno; un secondo convertitore generico farebbe soltanto concorrenza a quelli e renderebbe questa pagina più difficile da spiegare.

Una cella si riempie per larghezza, non per lunghezza

Incolonnare le barre significa riempire ogni cella di una colonna fino alla stessa larghezza, e questo richiede di sapere quanto è larga una cella. La risposta ovvia — contare i caratteri — è sbagliata per la maggior parte dei sistemi di scrittura del mondo, ed è sbagliata in entrambe le direzioni.

Un font a spaziatura fissa non è un carattere, una colonna. Un ideogramma cinese o giapponese, un kana, una sillaba hangul, una lettera latina a larghezza piena e quasi ogni emoji sono disegnati esattamente il doppio più larghi di una lettera latina. Un segno combinante — un accento, un punto vocalico ebraico, un segno diacritico arabo — è disegnato sopra la lettera che lo precede e non occupa larghezza alcuna. Riempi contando i caratteri e una colonna di giapponese risulta corta mentre una di testo accentato risulta lunga.

'日本語'.length          // 3  UTF-16 code units
[...'日本語'].length     // 3  code points
displayWidth('日本語')   // 6  columns in the editor

Per questo il riempimento si misura in colonne di visualizzazione. Il testo viene prima diviso in gruppi grafemici — ciò che un lettore conta come un carattere, così che un’emoji costruita da più punti di codice resti una sola unità — e ogni gruppo viene confrontato con la proprietà East_Asian_Width del database dei caratteri Unicode. È l’unica cosa a cui un browser non sa rispondere da solo: JavaScript espone categoria, sistema di scrittura e maiuscole tramite le espressioni regolari, ma non questa, perciò con la pagina viaggia una piccola tabella degli intervalli larghi. Tutto il resto arriva dal motore.

Una categoria è trattata come stretta di proposito. Unicode segna un insieme di caratteri — grafica a riquadri, alcune lettere greche e cirilliche, vari segni di punteggiatura — come «ambigui»: larghi in un vecchio font dell’Asia orientale, stretti ovunque altrove. Un file Markdown si legge in un editor con un font latino predefinito, quindi contano come una colonna, che è quello che fanno i terminali e gli editor in cui aprirai il file.

Ciò che una tabella Markdown non può contenere

Il formato ha due limiti rigidi, e i dati veri li incontrano entrambi. Una cella non può contenere una barra verticale nuda, perché è ciò che separa le celle; va scritta protetta. E una riga di tabella è una riga sola, quindi una cella non può contenere un a capo per nulla — cosa che invece un campo CSV ha tutto il diritto di avere.

Entrambi vengono riscritti, e ogni riscrittura è segnalata con il numero di celle interessate e la posizione della prima. Il punto è proprio questo: uno strumento che trasforma in silenzio il tuo indirizzo su due righe in una sola ha danneggiato i tuoi dati senza dirtelo. Un a capo diventa per impostazione predefinita un tag di interruzione, che è ciò che GitHub, GitLab e la maggior parte dei renderer mostrano come nuova riga dentro la cella; se il tuo rimuove l’HTML, passa allo spazio.

Una riga più lunga dell’intestazione è il terzo caso. Il Markdown di GitHub scarta semplicemente le celle in più, e questo perde dati in silenzio. Qui invece la tabella viene allargata, con celle di intestazione vuote, e la discrepanza viene segnalata: un’intestazione dall’aria strana che puoi sistemare è meglio di una colonna di cui non verrai mai a sapere. Una riga più corta dell’intestazione viene riempita con celle vuote e segnalata allo stesso modo.

Le barre rovesciate sono trattate con un po’ più di attenzione di quanto facciano quasi tutti gli strumenti. Una barra rovesciata viene raddoppiata solo dove potrebbe inghiottire la barra verticale che la segue: davanti a una barra nel testo, oppure proprio in fondo a una cella, dove arriva il separatore. In ogni altro punto resta com’è, così un percorso Windows dentro una cella rimane leggibile invece di diventare una fila di barre doppie.

L’allineamento vive nella riga separatrice

La riga di trattini sotto l’intestazione fa due lavori. È ciò che rende il blocco una tabella, e i suoi due punti fissano l’allineamento di ogni colonna: due punti a sinistra allinea a sinistra, a destra allinea a destra, su entrambi i lati centra. Senza due punti il renderer usa il proprio valore predefinito, che è la sinistra in ogni implementazione, ma non è la stessa cosa di chiedere la sinistra.

Qui ogni colonna ha il proprio comando, perché è così che l’allineamento viene davvero usato: il testo a sinistra, i numeri a destra, una colonna di stato centrata. E quando incolli una tabella che ha già un allineamento, questo viene letto dalla riga separatrice e mostrato in quei comandi, così riformattare una tabella esistente non butta mai via in silenzio il lavoro che qualcuno ci ha messo.

Anche il riempimento segue l’allineamento. Una colonna allineata a destra viene riempita a sinistra, così il sorgente si presenta come si presenterà la tabella renderizzata. Markdown ignora del tutto quegli spazi, ed è esattamente per questo che si possono spendere gratis per rendere leggibile il sorgente.

Riempita o compatta, e perché il testo da destra a sinistra è diverso

Il riempimento vale la pena in un documento che una persona modifica e costa qualcosa in un repository. Ogni cella che cresce fa riempire di nuovo tutta la sua colonna, così una modifica di una parola compare nel diff come una modifica a ogni riga della tabella. La forma compatta scrive la tabella lecita più stretta — niente riempimento, tre trattini per colonna — e tiene il diff limitato alle righe che sono davvero cambiate. Le due si renderizzano identiche. Le barre a inizio e fine riga sono facoltative nel Markdown di GitHub ma obbligatorie in alcuni renderer più vecchi, quindi sono un interruttore e non una decisione.

Il riempimento non può funzionare affatto in una tabella con ebraico o arabo, e lo strumento lo dice invece di fingere. Gli spazi sono contati correttamente, ma un editor dispone una riga mista secondo l’algoritmo bidirezionale: il tratto da destra a sinistra viene riordinato, e le barre che lo circondano si spostano con lui. I caratteri sono al posto giusto e le barre continuano a non sembrare incolonnate, perché in una riga così posizione visiva e posizione logica non sono la stessa cosa. Non c’è rimedio, quindi quando c’è testo da destra a sinistra in una cella lo strumento lo segnala e suggerisce la forma compatta, dove non c’è allineamento da cui restare delusi.

Per lo stesso motivo l’uscita Markdown di questa pagina è sempre mostrata da sinistra a destra, anche quando leggi il sito in ebraico o in arabo. È codice sorgente, e il codice sorgente ha una direzione tutta sua.

Dove gira

Tutto avviene nel tuo browser. La tabella viene analizzata, misurata e ricostruita sulla tua macchina, e nulla di ciò che incolli viene caricato, conservato o registrato — cosa che conta, perché le tabelle che serve riformattare sono di solito risultati di query ed export più che dati pubblici.