Formattatore YAML — commenti e ancore restano

Che cosa fa questo strumento

Reindenta. Non riscrive.

# Database di produzione — avvisare la reperibilità prima di toccare
db:
    host: db.example.com   # commutazione manuale
    port: 5432

Indentazione a due spazi, e tutto il resto esattamente come l’hai scritto: il commento sopra db, quello dopo host, lo stile di virgolette di ogni scalare.

La via ovvia perde i tuoi commenti

Il modo ovvio di scrivere un formattatore YAML è analizzare il file come valore e serializzare quel valore. È anche sbagliato, in due modi che non lasciano traccia.

Tutti i commenti spariscono. Un valore non ha commenti: vivono nel documento, non nei dati. Un file di configurazione che qualcuno ha documentato — perché quel timeout, chi chiamare, cosa si rompe se lo cambi — torna muto, e l’uscita è YAML valido, quindi nulla dice che cosa si è perso.

Le ancore vengono espanse. Questo:

base: &defaults
  restart: always
  logging: json
web:
  <<: *defaults
worker:
  <<: *defaults

diventa tre copie dello stesso blocco, più lungo dell’ingresso, con il legame tra loro svanito. Chi cambierà restart la prossima volta dovrà trovarle tutte e tre.

Questo formattatore conserva il documento e cambia solo la disposizione.

I valori ambigui restano intatti

country: NO resta country: NO.

Un lettore YAML 1.2 vede la stringa NO; uno YAML 1.1 — PyYAML — vede il booleano falso. Mettere le virgolette scioglierebbe la questione, e scioglierla spetta all’autore, non a un formattatore: un file scritto per PyYAML poteva benissimo intendere falso.

Gli strumenti di conversione le virgolette le mettono, e fanno bene: partono da un valore che sanno essere una stringa. Un formattatore parte da un file, e un file non lo dice.

Più documenti in un file

--- separa i documenti YAML, e un file può contenerne quanti vuole. Ognuno è formattato sul posto e i separatori restano. È la forma della maggior parte dei manifesti Kubernetes: un flusso, non un errore.

Le opzioni

Indentazione — due spazi di default, o quello che scegli.

Ordinare le chiavi — alfabeticamente, in modo ricorsivo, con ogni commento che segue la voce a cui era attaccato. Utile per confrontare due file divergenti; lascialo spento se l’ordine delle tue chiavi significa qualcosa, cosa che in un file di configurazione capita spesso.

Privato per progettazione

Tutto viene eseguito localmente nel browser con JavaScript. I tuoi dati non vengono mai caricati, quindi lo strumento è sicuro per contenuti sensibili e funziona anche offline.