Parse og stringify JSON med kommentarer. Den bevarer kommentarer, selv efter at de er gemt!

• Parse JSON-strenge med kommentarer til JavaScript-objekter og BEHOLD kommentarer
  • understøtter kommentarer overalt, ja, ALLE steder i en JSON-fil, til sidst 😆
  • løser det kendte problem med kommentarer inde i arrays.
• Stringificerer objekterne til JSON-strenge med kommentarer, hvis der er

Brugen af comment-json er nøjagtig den samme som vanilla JSON-objektet.

Indholdsfortegnelse

• Hvorfor og hvordan
• Anvendelse og eksempler
• API-reference
  • parse
  • stringify
  • assign
  • CommentArray
• Change Logs

Hvorfor?

Der findes mange andre biblioteker, der kan håndtere JSON med kommentarer, f.eks. json5 eller strip-json-comments, men ingen af dem kan stringificere det analyserede objekt og returnere en JSON-streng, der er den samme som det oprindelige indhold.

Forestil dig, at hvis brugerindstillingerne gemmes i ${library}.json，, og brugeren har skrevet en masse kommentarer for at forbedre læsbarheden. Hvis biblioteket library skal ændre brugerindstillingerne, f.eks. ændre nogle egenskabsværdier og tilføje nye felter, og hvis biblioteket bruger json5 til at læse indstillingerne, vil alle kommentarer forsvinde efter ændring, hvilket vil drive folk til vanvid.

Så, hvis du vil analysere en JSON-streng med kommentarer, ændre den og derefter gemme den tilbage, er comment-json dit must-valg!

Hvordan?

comment-json analyserer JSON-strenge med kommentarer og gemmer kommentartegn i symbolegenskaber.

For JSON-array med kommentarer udvider comment-json vanilla Array-objektet til CommentArray, hvis instanser kan håndtere kommentarændringer, selv efter at et kommentararray er ændret.

Installér

$ npm i comment-json

For TypeScript-udviklere kunne @types/comment-json bruges

Siden 2.4.1 indeholder comment-json typescript-deklarationer, så man kan lige så godt fjerne @types/comment-json.

Anvendelse

pakke.json:

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

Sortere nøgler

Det er et almindeligt anvendelsestilfælde at sortere nøglerne i en JSON-fil

For detaljer om assign, se her.

parse()

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

• tekst string Den streng, der skal parses som JSON. Se JSON-objektet for en beskrivelse af JSON-syntaksen.
• reviver? Function() | null Standardindstillingen er null. Den fungerer på samme måde som den anden parameter i JSON.parse. Hvis det er en funktion, foreskriver den, hvordan den værdi, der oprindeligt blev produceret ved parsing, transformeres, før den returneres.
• remove_comments? boolean = false Hvis sand, vil kommentarerne ikke blive opretholdt, hvilket ofte bruges, når vi ønsker at få et rent objekt.

Returnerer object | string | number | boolean | null, der svarer til den givne JSON-tekst.

Hvis content er:

Og værdien af parsed vil være:

Der er Otte typer af symbolegenskaber:

Og værdien af hver symbolegenskab er et array af 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 til et objekt uden kommentarer

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

Og resultatet vil være:

{
 foo: 1,
 bar: 
}

Særlige tilfælde

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

Hvis vi analyserer en JSON af primativ type med remove_comments:false, så vil returværdien af parse() være af objekttype.

Værdien af parsed svarer til:

Hvilket svarer til:

• Boolean type
• String type

For eksempel

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

Hvilket svarer til

Men der er en undtagelse:

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

stringify()

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

Argumenterne er de samme som i vanilla JSON.stringify.

Og den gør det samme som vanillaen, men håndterer også ekstra egenskaber og konverterer dem til kommentarer.

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

space

Hvis space ikke er angivet, eller hvis space er en tom streng, vil resultatet af stringify() ikke have nogen kommentarer.

For ovenstående tilfælde:

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 the target object
• source? object kildeobjektet. Denne parameter er valgfri, men det er dumt ikke at aflevere dette argument.
• keys? Array<string> Hvis den ikke er angivet, anvendes alle enumerable egne egenskaber i source.

Denne metode bruges til at kopiere de enumerable egne egenskaber og deres tilsvarende egenskaber for kommentar-symboler til målobjektet.

Særlige tilfælde om nøgler

Men hvis argument keys er angivet og ikke er tomt, vil kommentar before all, som ikke hører til nogen egenskaber, IKKE blive kopieret.

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

Specificering af argumentet keys som et tomt array indikerer, at det kun vil kopiere ikke-egenskabs-symboler for kommentarer

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

Nej egenskabssymboler omfatter:

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

CommentArray

Vejere afsnit

Alle arrays i det parsede objekt er CommentArrays.

Konstruktøren af CommentArray kunne tilgås ved:

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

Hvis vi ændrer et comment array, kunne dets egenskaber for kommentar-symboler håndteres automatisk.

Oh yeah! 😆

Men vær opmærksom på, at hvis du omfordeler egenskaben for et kommentararray med et normalt array, vil alle kommentarer være væk:

I stedet bør vi:

Særlige tilfælde om afsluttende komma

Hvis vi har en JSON-streng str