Parse och stringify JSON med kommentarer. Den behåller kommentarerna även efter att de har sparats!

• Parsar JSON-strängar med kommentarer till JavaScript-objekt och BEHÅLLER kommentarerna
  • har stöd för kommentarer överallt, ja, överallt i en JSON-fil, så småningom 😆
  • löser det kända problemet med kommentarer inuti matriser.
• Stringifiera objekten till JSON-strängar med kommentarer om det finns

Användningen av comment-json är exakt densamma som vaniljobjektet JSON.

Innehållsförteckning

• Varför och hur
• Användning och exempel
• API-referens
  • parse
  • stringify
  • assign
  • CommentArray
• Change Logs

Varför?

Det finns många andra bibliotek som kan hantera JSON med kommentarer, t.ex. json5 eller strip-json-comments, men inget av dem kan stringifiera det parsade objektet och returnera en JSON-sträng som är likadan som det ursprungliga innehållet.

Föreställ dig att användarinställningarna sparas i ${library}.json， och att användaren har skrivit många kommentarer för att förbättra läsbarheten. Om biblioteket library behöver ändra användarinställningen, t.ex. ändra vissa egenskapsvärden och lägga till nya fält, och om biblioteket använder json5 för att läsa inställningarna, kommer alla kommentarer att försvinna efter modifieringen, vilket kommer att driva folk till vansinne.

Så, om du vill analysera en JSON-sträng med kommentarer, ändra den, och sedan spara tillbaka den, är comment-json ditt måste val!

Hur?

comment-json analyserar JSON-strängar med kommentarer och sparar kommentartoken i symbolegenskaper.

För JSON-array med kommentarer utökar comment-json vaniljobjektet Array till CommentArray vars instanser kan hantera ändringar i kommentarerna även efter att en kommentarmatris har ändrats.

Installera

$ npm i comment-json

För TypeScript-utvecklare skulle @types/comment-json kunna användas

Sedan 2.4.1 innehåller comment-json typescriptdeklarationer, så det är lika bra att ta bort @types/comment-json.

Användning

paketet.json:

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

Sortera nycklar

Det är ett vanligt användningsfall att sortera nycklarna i en JSON-fil

För detaljer om assign, se här.

parse()

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

• text string Strängen som ska parsas som JSON. Se JSON-objektet för en beskrivning av JSON-syntaxen.
• reviver? Function() | null Standard är null. Den fungerar på samma sätt som den andra parametern i JSON.parse. Om det är en funktion, föreskrivs hur det värde som ursprungligen produceras av parsningen omvandlas innan det returneras.
• remove_comments? boolean = false Om sant kommer kommentarerna inte att behållas, vilket ofta används när vi vill få ett rent objekt.

Returnerar object | string | number | boolean | null som motsvarar den givna JSON-texten.

Om content är:

Och värdet av parsed blir:

Det finns ÅTTA typer av symbolegenskaper:

Och värdet av varje symbolegenskap är en array av 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
}

Parsera till ett objekt utan kommentarer

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

Och resultatet blir:

{
 foo: 1,
 bar: 
}

Specialfall

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

Om vi analyserar en JSON av primativ typ med remove_comments:false kommer returvärdet av parse() att vara av objekttyp.

Värdet av parsed är likvärdigt med:

Som är likvärdigt för:

• Boolean typ
• String typ

Till exempel

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

Som är likvärdigt för:

Men det finns ett undantag:

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

stringify()

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

Argumenten är desamma som i vanilj JSON.stringify.

Och den gör samma sak som vaniljen, men hanterar även extra egenskaper och omvandlar dem till kommentarer.

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

space

Om space inte specificeras, eller om space är en tom sträng, kommer resultatet av stringify() inte att ha några kommentarer.

För fallet ovan:

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 källobjektet. Denna parameter är valfri men det är dumt att inte lämna detta argument.
• keys? Array<string> Om det inte anges kommer alla uppräkningsbara egna egenskaper i source att användas.

Denna metod används för att kopiera de uppräkningsbara egna egenskaperna och deras motsvarande kommentarsymbolegenskaper till målobjektet.

Specialfall om nycklar

Men om argumentet keys anges och inte är tomt, kommer kommentarsymbolegenskaperna before all, som inte hör till några egenskaper, INTE att kopieras.

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

Om argumentet keys specificeras som en tom matris indikerar det att det endast kommer att kopiera symboler som inte är egenskapsymboler för kommentarer

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

Symboler som inte är egenskapsymboler inkluderar:

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

CommentArray

Avancerat avsnitt

Alla matriser i det analyserade objektet är CommentArrays.

Konstruktören för CommentArray kan nås genom:

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

Om vi ändrar en kommentarmatris kan dess egenskaper för kommentarsymboler hanteras automatiskt.

Oh yeah! 😆

Men var uppmärksam, om du omfördelar egenskapen för en kommentarmatris med en normal matris kommer alla kommentarer att försvinna:

Istället bör vi:

Specialfall om avslutande kommatecken

Om vi har en JSON-sträng str