Parse and stringify JSON with comments. Zachowa komentarze nawet po zapisaniu!

• Parsuje ciągi JSON z komentarzami do obiektów JavaScript i MAINTAIN comments
  • obsługuje komentarze wszędzie, tak, WSZĘDZIE w pliku JSON, w końcu 😆
  • poprawia znany problem z komentarzami wewnątrz tablic.
• Stringify obiekty do ciągów JSON z komentarzami jeśli są

Użycie comment-json jest dokładnie takie samo jak waniliowego obiektu JSON.

Spis treści

• Dlaczego i jak
• Użycie i przykłady
• Odniesienie do API
  .
  • parse
  • stringify
  • assign
  • CommentArray
• Change Logs

Dlaczego?

Istnieje wiele innych bibliotek, które radzą sobie z JSON z komentarzami, takich jak json5 lub strip-json-comments, ale żadna z nich nie jest w stanie sparsyfikować sparsowanego obiektu i zwrócić ciąg JSON taki sam jak oryginalna zawartość.

Wyobraź sobie, że jeśli ustawienia użytkownika są zapisane w ${library}.json， a użytkownik napisał wiele komentarzy, aby poprawić czytelność. Jeśli biblioteka library musi zmodyfikować ustawienia użytkownika, takie jak modyfikowanie niektórych wartości właściwości i dodawanie nowych pól, a jeśli biblioteka używa json5 do odczytu ustawień, wszystkie komentarze znikną po zmodyfikowaniu, co doprowadzi ludzi do szaleństwa.

Więc, jeśli chcesz parsować ciąg JSON z komentarzami, zmodyfikować go, a następnie zapisać go z powrotem, comment-json jest twoim obowiązkowym wyborem!

Jak?

comment-json parsuje łańcuchy JSON z komentarzami i zapisuje tokeny komentarzy we właściwościach symbolu.

Dla tablicy JSON z komentarzami, comment-json rozszerza waniliowy Array obiekt do CommentArray, którego instancje mogą obsługiwać zmiany komentarzy nawet po zmodyfikowaniu tablicy komentarzy.

Install

$ npm i comment-json

Dla programistów TypeScript, @types/comment-json mógłby być użyty

Od 2.4.1, comment-json zawiera deklaracje typescript, więc równie dobrze można usunąć @types/comment-json.

Usage

package.json:

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

Sortuj klucze

Powszechnym przypadkiem użycia jest sortowanie kluczy pliku JSON

Szczegóły na temat assign, zobacz tutaj.

parse()

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

• tekst string Łańcuch do parsowania jako JSON. Zobacz obiekt JSON, aby uzyskać opis składni JSON.
• reviver? Function() | null Domyślnie null. Działa tak samo jak drugi parametr JSON.parse. Jeśli jest funkcją, nakazuje, jak wartość pierwotnie wytworzona przez parsowanie jest przekształcana, zanim zostanie zwrócona.
• remove_comments? boolean = false Jeśli true, komentarze nie zostaną zachowane, co jest często używane, gdy chcemy uzyskać czysty obiekt.

Zwraca object | string | number | boolean | null odpowiadający podanemu tekstowi JSON.

Jeśli content jest:

A wartość parsed będzie:

Istnieje SIEDEM rodzajów właściwości symbolu:

A wartością każdej właściwości symbolu jest tablica 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
}

Parsuj do obiektu bez komentarzy

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

A wynikiem będzie:

{
 foo: 1,
 bar: 
}

Przypadki szczególne

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

Jeśli parsujemy JSON typu prymitywnego za pomocą remove_comments:false, to wartość zwracana parse() będzie typu obiektowego.

Wartość parsed jest równoważna:

Co jest podobne dla:

• Boolean typ
• String typ

Na przykład

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

Co jest równoważne

Jest jednak jeden wyjątek:

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

stringify()

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

Argumenty są takie same jak w waniliowym JSON.stringify.

I robi podobną rzecz jak waniliowy, ale również zajmuje się dodatkowymi właściwościami i konwertuje je na komentarze.

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

spacja

Jeśli spacja nie jest określona, lub spacja jest pustym łańcuchem, wynik stringify() nie będzie miał komentarzy.

Dla powyższego przypadku:

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 obiekt docelowy
• source? object obiekt źródłowy. Ten parametr jest opcjonalny, ale głupio jest nie przekazać tego argumentu.
• klucze? Array<string> Jeśli nie zostanie określony, zostaną użyte wszystkie enumerowalne właściwości własne source.

Ta metoda jest używana do kopiowania enumerowalnych właściwości własnych i odpowiadających im właściwości symboli komentarzy do obiektu docelowego.

Specjalne przypadki dotyczące kluczy

Ale jeśli argument keys jest określony i nie jest pusty, to komentarz before all, który nie należy do żadnych właściwości, NIE zostanie skopiowany.

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

Określenie argumentu keys jako pustej tablicy wskazuje, że skopiowane zostaną tylko symbole komentarzy niebędące właściwościami

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

Symbole niebędące właściwościami obejmują:

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

CommentArray

Sekcja zaawansowana

Wszystkie tablice parsowanego obiektu są CommentArrays.

Do konstruktora CommentArraymożna uzyskać dostęp przez:

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

Jeśli zmodyfikujemy tablicę komentarzy, jej właściwości symbolu komentarza będą obsługiwane automatycznie.

Oh yeah! 😆

Ale uwaga, jeśli ponownie przypiszemy właściwość tablicy komentarzy do zwykłej tablicy, wszystkie komentarze znikną:

W zamian powinniśmy:

Specjalne przypadki dotyczące przecinka w nawiasie

Jeśli mamy ciąg JSON str

.