Parse e stringa JSON con commenti. Manterrà i commenti anche dopo il salvataggio!

• Parse le stringhe JSON con commenti in oggetti JavaScript e MANTIENE i commenti
  • supporta i commenti ovunque, sì, OVUNQUE in un file JSON, infine 😆
  • corregge il noto problema dei commenti all’interno degli array.
• Stringi gli oggetti in stringhe JSON con commenti se ci sono

L’uso di comment-json è esattamente lo stesso dell’oggetto vanilla JSON.

Indice

• Perché e come
• Uso ed esempi
• Riferimento API
  • parse
  • stringify
  • assign
  • CommentArray
• Change Logs

Perché?

Ci sono molte altre librerie che possono trattare JSON con commenti, come json5, o strip-json-comments, ma nessuna di loro può stringere l’oggetto analizzato e restituire una stringa JSON uguale al contenuto originale.

Immaginate che se le impostazioni dell’utente sono salvate in ${library}.json， e l’utente ha scritto molti commenti per migliorare la leggibilità. Se la libreria library ha bisogno di modificare le impostazioni dell’utente, come la modifica di alcuni valori di proprietà e l’aggiunta di nuovi campi, e se la libreria utilizza json5 per leggere le impostazioni, tutti i commenti scompariranno dopo la modifica che farà impazzire le persone.

Quindi, se si desidera analizzare una stringa JSON con commenti, modificarla, quindi salvarla nuovamente, comment-json è la scelta obbligata!

Come?

comment-json analizza le stringhe JSON con commenti e salva i token dei commenti nelle proprietà dei simboli.

Per gli array JSON con commenti, comment-json estende l’oggetto vanilla Array in CommentArray le cui istanze possono gestire i cambiamenti dei commenti anche dopo che un array di commenti è stato modificato.

Installa

$ npm i comment-json

Per gli sviluppatori TypeScript, @types/comment-json potrebbe essere usato

Da 2.4.1, comment-json contiene dichiarazioni typescript, quindi potresti anche rimuovere @types/comment-json.

Uso

pacchetto.json:

{
 // package name
 "name": "comment-json"
}

Ordina chiavi

È un caso d’uso comune per ordinare le chiavi di un file JSON

Per dettagli su assign, vedi qui.

parse()

parse(text, reviver? = null, remove_comments? = false)
 : object | string | number | boolean | null

• testo string La stringa da analizzare come JSON. Vedere l’oggetto JSON per una descrizione della sintassi JSON.
• reviver? Function() | null Predefinito a null. Si comporta come il secondo parametro di JSON.parse. Se è una funzione, prescrive come viene trasformato il valore originariamente prodotto dall’analisi, prima di essere restituito.
• remove_comments? boolean = false Se vero, i commenti non saranno mantenuti, il che è spesso usato quando vogliamo ottenere un oggetto pulito.

Ritorna object | string | number | boolean | null corrispondente al testo JSON dato.

Se il content è:

E il valore di parsed sarà:

Ci sono OTTO tipi di proprietà di simboli:

E il valore di ogni proprietà del simbolo è un array di CommentToken

interface CommentToken {
 type: 'BlockComment' | 'LineComment'
 // The content of the comment, including whitespaces and line breaks
 value: string
 // If the start location is the same line as the previous token,
 // then `inline` is `true`
 inline: boolean
 
 // But pay attention that,
 // locations will NOT be maintained when stringified
 loc: CommentLocation
}
 
interface CommentLocation {
 // The start location begins at the `//` or `/*` symbol
 start: Location
 // The end location of multi-line comment ends at the `*/` symbol
 end: Location
}
 
interface Location {
 line: number
 column: number
}

Parse in un oggetto senza commenti

console.log(parse(content, null, true))

E il risultato sarà:

{
 foo: 1,
 bar: 
}

Casi speciali

const parsed = parse(`
// comment
1
`)
 
console.log(parsed === 1)
// false

Se analizziamo un JSON di tipo primitivo con remove_comments:false, allora il valore di ritorno di parse() sarà di tipo oggetto.

Il valore di parsed è equivalente a:

Che è simile per:

• Boolean tipo
• String tipo

Per esempio

const parsed = parse(`
"foo" /* comment */
`)

Che è equivalente a

Ma c’è una eccezione:

const parsed = parse(`
// comment
null
`)
 
console.log(parsed === null) // true

stringify()

stringify(object: any, replacer?, space?): string

Gli argomenti sono gli stessi della vaniglia JSON.stringify.

E fa la stessa cosa di quello vanilla, ma tratta anche le proprietà extra e le converte in commenti.

console.log(stringify(parsed, null, 2))
// Exactly the same as `content`

spazio

Se lo spazio non è specificato, o lo spazio è una stringa vuota, il risultato di stringify() non avrà commenti.

Per il caso precedente:

console.log(stringify(result)) // {"a":1}
console.log(stringify(result, null, 2)) // is the same as `code`

assign(target: oggetto, source?: oggetto, keys?: Array)

• target object l’oggetto target
• source? object l’oggetto sorgente. Questo parametro è opzionale, ma è sciocco non passare questo argomento.
• chiavi? Array<string> Se non specificato, saranno usate tutte le proprietà proprie enumerabili di source.

Questo metodo è usato per copiare le proprietà proprie enumerabili e le loro corrispondenti proprietà dei simboli di commento nell’oggetto di destinazione.

Casi speciali sulle chiavi

Ma se l’argomento keys è specificato e non è vuoto, allora il commento before all, che non appartiene a nessuna proprietà, NON sarà copiato.

const obj = assign({
 bar: 'baz'
}, parsed, )
 
stringify(obj, null, 2)
// {
// "bar": "baz",
// // This is a comment
// "foo": "bar"
// }

Specificare l’argomento keys come un array vuoto indica che copierà solo i simboli non di proprietà dei commenti

const obj = assign({
 bar: 'baz'
}, parsed, )
 
stringify(obj, null, 2)
// // before all
// {
// "bar": "baz",
// }

I simboli non di proprietà includono:

Symbol.for('before-all')
Symbol.for('before')
Symbol.for('after-all')

CommentArray

Sezione avanzata

Tutti gli array dell’oggetto analizzato sono CommentArrays.

Il costruttore di CommentArray potrebbe essere raggiunto da:

const {CommentArray} = require('comment-json')

Se modifichiamo un array di commenti, le sue proprietà dei simboli di commento potrebbero essere gestite automaticamente.

Oh sì! 😆

Ma fate attenzione, se riassegnate la proprietà di un array di commenti con un array normale, tutti i commenti spariranno:

Invece, dovremmo:

Casi speciali sulla virgola finale

Se abbiamo una stringa JSON str