Parse and stringify JSON with comments. Mentés után is megtartja a megjegyzéseket!

• JSON karakterláncokat elemez megjegyzésekkel JavaScript objektumokká és Megtartja a megjegyzéseket
  • támogatja a megjegyzéseket mindenhol, igen, MINDENHOL egy JSON fájlban, végül 😆
  • javítja a tömbökön belüli megjegyzésekkel kapcsolatos ismert problémát.
• Az objektumokat JSON karakterláncokká fűzi fel kommentárokkal, ha vannak

A comment-json használata pontosan ugyanaz, mint a vanília JSON objektumé.

Tartalomjegyzék

• Miért és hogyan
• Használat és példák
• API hivatkozás
  .
  • parse
  • stringify
  • assign
  • CommentArray
• Change Logs

Miért?

Sok más könyvtár is tud JSON-t kezelni megjegyzésekkel, mint például a json5, vagy a strip-json-comments, de egyik sem képes a tagolt objektumot stringelni és az eredeti tartalommal megegyező JSON stringet visszaadni.

Elképzeljük, hogy ha a felhasználói beállítások ${library}.json，-ben vannak elmentve, és a felhasználó sok megjegyzést írt az olvashatóság javítása érdekében. Ha a könyvtárnak library módosítania kell a felhasználói beállításokat, például néhány tulajdonságértéket módosítani és új mezőket hozzáadni, és ha a könyvtár json5-t használ a beállítások olvasására, akkor a módosítás után az összes megjegyzés eltűnik, ami az őrületbe kergeti az embereket.

Szóval, ha egy JSON stringet szeretne elemezni megjegyzésekkel, módosítani, majd visszamenteni, akkor a comment-json a kötelező választás!

Hogyan?

comment-json elemzi a JSON stringeket megjegyzésekkel, és a megjegyzés tokeneket szimbólum tulajdonságokba menti.

A JSON tömb megjegyzésekkel, comment-json kiterjeszti a vanília Array objektumot CommentArray-ra, amelynek példányai képesek kezelni a megjegyzések módosítását még a megjegyzés tömb módosítása után is.

Install

$ npm i comment-json

A TypeScript fejlesztők számára a @types/comment-json használható

Mióta 2.4.1, a comment-json typescript deklarációkat tartalmaz, így akár a @types/comment-json is eltávolítható.

Usage

package.json:

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

Kulcsok rendezése

Egy JSON fájl kulcsainak rendezése gyakori felhasználási eset

A assign részleteit lásd itt.

parse()

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

• text string A JSON-ként elemzendő string. A JSON szintaxis leírását lásd a JSON objektumban.
• reviver? Function() | null Alapértelmezés szerint null. Ugyanúgy viselkedik, mint a JSON.parse második paramétere. Ha függvény, akkor azt írja elő, hogy az eredetileg elemzéssel előállított értéket hogyan alakítja át, mielőtt visszaadja.
• remove_comments? boolean = false Ha igaz, akkor a megjegyzések nem maradnak meg, amit gyakran használunk, amikor egy tiszta objektumot szeretnénk kapni.

A megadott JSON szövegnek megfelelő object | string | number | boolean | null visszaadja.

Ha a content:

És a parsed értéke lesz:

NYolcféle szimbólumtulajdonság van:

És az egyes szimbólumtulajdonságok értéke egy tömb: 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 an object without comments

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

Az eredmény pedig a következő lesz:

{
 foo: 1,
 bar: 
}

Speciális esetek

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

Ha egy primatív típusú JSON-t elemzünk remove_comments:false segítségével, akkor a parse() visszatérési értéke objektum típusú lesz.

A parsed értéke egyenértékű:

Mely hasonló a:

• Boolean type
• String type

Például

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

Mely egyenértékű

De van egy kivétel:

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

stringify()

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

Az argumentumok ugyanazok, mint a vanília JSON.stringify.

És hasonlót csinál, mint a vanília, de extra tulajdonságokkal is foglalkozik, és azokat kommentárrá alakítja.

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

space

Ha a space nincs megadva, vagy a space egy üres karakterlánc, akkor a stringify() eredménye nem tartalmaz kommentárt.

A fenti esetben:

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 a célobjektum
• source? object a forrás objektum. Ez a paraméter opcionális, de butaság ezt az argumentumot nem átadni.
• keys? Array<string> Ha nincs megadva, akkor a source összes felsorolható saját tulajdonsága felhasználásra kerül.

Ez a módszer a felsorolható saját tulajdonságok és a hozzájuk tartozó megjegyzésszimbólum tulajdonságok célobjektumba való másolására szolgál.

Különleges esetek a kulcsokról

De ha az keys argumentum meg van adva és nem üres, akkor a tulajdonságokhoz nem tartozó before all megjegyzés NEM lesz másolva.

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

A keys argumentum üres tömbként való megadása azt jelzi, hogy csak a megjegyzések nem tulajdonságokhoz tartozó szimbólumait fogja másolni

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

A nem tulajdonságokhoz tartozó szimbólumok közé tartoznak:

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

CommentArray

Előrészlet

Az elemzett objektum összes tömbje CommentArrays.

A CommentArray konstruktorát a következő módon érhetjük el:

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

Ha módosítunk egy Comment tömböt, akkor a Comment szimbólum tulajdonságait automatikusan kezelhetjük.

Oh yeah! 😆

De vigyázzunk, ha egy kommenttömb tulajdonságát egy normál tömbhöz rendeljük át, az összes komment eltűnik:

Ehelyett azt kell tennünk:

Speciális esetek az utolsó vesszőről

Ha van egy JSON stringünk str

.