Parse und stringify JSON mit Kommentaren. Es behält die Kommentare auch nach dem Speichern bei!

• Parse JSON-Strings mit Kommentaren in JavaScript-Objekte und behalte Kommentare bei
  • unterstützt Kommentare überall, ja, ÜBERALL in einer JSON-Datei, behebt schließlich 😆
  • das bekannte Problem mit Kommentaren in Arrays.
• Stringify the objects into JSON strings with comments if there are

Die Verwendung von comment-json ist genau die gleiche wie beim Vanilla JSON Objekt.

Inhaltsverzeichnis

• Warum und wie
• Verwendung und Beispiele
• API Referenz
  • parse
  • stringify
  • assign
  • CommentArray
• Change Logs

Warum?

Es gibt viele andere Bibliotheken, die JSON mit Kommentaren verarbeiten können, wie z.B. json5 oder strip-json-comments, aber keine von ihnen kann das geparste Objekt stringifizieren und einen JSON-String zurückgeben, der mit dem ursprünglichen Inhalt identisch ist.

Stellen Sie sich vor, dass die Benutzereinstellungen in ${library}.json， gespeichert werden und der Benutzer eine Menge Kommentare geschrieben hat, um die Lesbarkeit zu verbessern. Wenn die Bibliothek library die Benutzereinstellungen ändern muss, wie z.B. das Ändern einiger Eigenschaftswerte und das Hinzufügen neuer Felder, und wenn die Bibliothek json5 verwendet, um die Einstellungen zu lesen, werden alle Kommentare nach der Änderung verschwinden, was die Leute in den Wahnsinn treibt.

Wenn Sie also eine JSON-Zeichenkette mit Kommentaren parsen, sie ändern und dann wieder speichern wollen, ist comment-json Ihre erste Wahl!

Wie?

comment-jsonparst JSON-Strings mit Kommentaren und speichert Kommentar-Token in Symboleigenschaften.

Für JSON-Arrays mit Kommentaren erweitert comment-json das Vanilla Array-Objekt zu CommentArray, dessen Instanzen Änderungen an Kommentaren auch dann verarbeiten können, wenn ein Kommentar-Array geändert wird.

Install

$ npm i comment-json

Für TypeScript-Entwickler könnte @types/comment-json verwendet werden

Seit 2.4.1 enthält comment-json Typescript-Deklarationen, daher kann man @types/comment-json auch entfernen.

Verwendung

Paket.json:

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

Schlüssel sortieren

Es ist ein häufiger Anwendungsfall, die Schlüssel einer JSON-Datei zu sortieren

Für Details über assign, siehe hier.

parse()

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

• text string Der String, der als JSON geparst werden soll. Siehe das JSON-Objekt für eine Beschreibung der JSON-Syntax.
• reviver? Function() | null Standardwert ist null. Er verhält sich wie der zweite Parameter von JSON.parse. Wenn es sich um eine Funktion handelt, legt sie fest, wie der ursprünglich beim Parsen erzeugte Wert umgewandelt wird, bevor er zurückgegeben wird.
• remove_comments? boolean = false Wenn true, werden die Kommentare nicht beibehalten, was oft verwendet wird, wenn wir ein sauberes Objekt erhalten wollen.

Returnt object | string | number | boolean | null entsprechend dem angegebenen JSON-Text.

Wenn der content ist:

Und der Wert von parsed wird sein:

Es gibt ACHT Arten von Symboleigenschaften:

Und der Wert jeder Symboleigenschaft ist ein Array von 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
}

Parsen in ein Objekt ohne Kommentare

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

Und das Ergebnis wird sein:

{
 foo: 1,
 bar: 
}

Sonderfälle

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

Wenn wir ein JSON vom primären Typ mit remove_comments:false parsen, dann wird der Rückgabewert von parse() vom Objekttyp sein.

Der Wert von parsed ist äquivalent zu:

Was ähnlich ist für:

• Boolean Typ
• String Typ

Zum Beispiel

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

Was äquivalent ist zu

Aber es gibt eine Ausnahme:

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

stringify()

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

Die Argumente sind die gleichen wie bei der Vanille JSON.stringify.

Und es macht das Gleiche wie das Vanilla, aber es behandelt auch zusätzliche Eigenschaften und wandelt sie in Kommentare um.

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

Leerzeichen

Wenn Leerzeichen nicht angegeben wird, oder das Leerzeichen ein leerer String ist, wird das Ergebnis von stringify() keine Kommentare haben.

Für den obigen Fall:

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

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

• target object das Zielobjekt
• source? object das Quellobjekt. Dieser Parameter ist optional, aber es ist dumm, dieses Argument nicht zu übergeben.
• keys? Array<string> Wenn nicht angegeben, werden alle aufzählbaren eigenen Eigenschaften von source verwendet.

Diese Methode wird verwendet, um die aufzählbaren eigenen Eigenschaften und ihre entsprechenden Kommentar-Symboleigenschaften in das Zielobjekt zu kopieren.

Sonderfälle über Schlüssel

Wenn aber das Argument keys angegeben wird und nicht leer ist, dann wird der Kommentar before all, der zu keinen Eigenschaften gehört, NICHT kopiert.

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

Die Angabe des Arguments keys als leeres Array bedeutet, dass nur Nicht-Eigenschaftssymbole von Kommentaren kopiert werden

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

Nicht-Eigenschaftssymbole sind:

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

CommentArray

Erweiterter Abschnitt

Alle Arrays des geparsten Objekts sind CommentArrays.

Auf den Konstruktor von CommentArrays könnte man zugreifen:

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

Wenn wir ein Kommentar-Array modifizieren, könnten seine Kommentar-Symbol-Eigenschaften automatisch behandelt werden.

Oh ja! 😆

Aber Achtung, wenn Sie die Eigenschaft eines Kommentar-Arrays mit einem normalen Array neu zuweisen, werden alle Kommentare verschwinden:

Stattdessen sollten wir:

Spezialfälle über Trailing Comma

Wenn wir einen JSON-String haben str