Parsování a řetězení JSON s komentáři. Zachová komentáře i po uložení!

• Parsuje řetězce JSON s komentáři do objektů JavaScriptu a zachovává komentáře
  • podporuje komentáře všude, ano, VŠUDE v souboru JSON, případně 😆
  • opravuje známý problém s komentáři uvnitř polí.
• Stringuje objekty do řetězců JSON s komentáři, pokud existují

Použití comment-json je úplně stejné jako u vanilkového objektu JSON.

Obsah

• Proč a jak
• Použití a příklady
• Odkaz na API
  .
  • parse
  • stringify
  • assign
  • CommentArray
• Change Logs

Proč?

Existuje mnoho jiných knihoven, které umí pracovat s JSON s komentáři, například json5, nebo strip-json-comments, ale žádná z nich neumí stringifikovat parsovaný objekt a vrátit zpět řetězec JSON stejný jako původní obsah.

Představte si, že pokud je uživatelské nastavení uloženo v ${library}.json， a uživatel napsal mnoho komentářů pro zlepšení čitelnosti. Pokud knihovna library potřebuje uživatelské nastavení upravit, například změnit některé hodnoty vlastností a přidat nová pole, a pokud knihovna použije json5 k načtení nastavení, všechny komentáře po úpravě zmizí, což lidi přivede k šílenství.

Pokud tedy chcete analyzovat řetězec JSON s komentáři, upravit ho a pak ho uložit zpět, comment-json je vaše povinná volba!

Jak?

comment-jsonparsovat řetězce JSON s komentáři a ukládat tokeny komentářů do vlastností symbolů.

Pro pole JSON s komentáři comment-json rozšiřuje vanilkový objekt Array na CommentArray, jehož instance by mohly zpracovávat změny komentářů i po úpravě pole komentářů.

Instalovat

$ npm i comment-json

Pro vývojáře TypeScriptu by se dal použít @types/comment-json

Protože 2.4.1, comment-json obsahuje deklarace TypeScriptu, mohl bys @types/comment-json rovnou odstranit.

Použití

balíček.json:

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

Seřadit klíče

Jedná se o běžný případ použití, kdy je třeba seřadit klíče souboru JSON

Podrobnosti o assign naleznete zde.

parse()

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

• text string Řetězec, který se analyzuje jako JSON. Popis syntaxe JSON najdete v objektu JSON.
• reviver? Function() | null Výchozí hodnota je null. Chová se stejně jako druhý parametr JSON.parse. Je-li to funkce, předepisuje, jak se hodnota původně vzniklá parsováním před vrácením transformuje.
• remove_comments? boolean = false Je-li true, komentáře nebudou zachovány, což se často používá, když chceme získat čistý objekt.

Vrací object | string | number | boolean | null odpovídající zadanému textu JSON.

Pokud je content:

A hodnota parsed bude:

Existuje OSM druhů vlastností symbolů:

A hodnota každé vlastnosti symbolu je pole 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 do objektu bez komentářů

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

A výsledek bude:

{
 foo: 1,
 bar: 
}

Speciální případy

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

Pokud budeme pomocí remove_comments:false parsovat JSON primárního typu, pak návratová hodnota parse() bude typu objekt.

Hodnota parsed je ekvivalentní:

Což je podobné pro:

• Boolean typ
• String typ

Například

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

Co je ekvivalentní

Ale je tu jedna výjimka:

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

stringify()

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

Argumenty jsou stejné jako u vanilkového JSON.stringify.

Dělá to podobně jako vanilla, ale navíc si poradí s dalšími vlastnostmi a převede je na komentáře.

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

mezera

Pokud není mezera zadána nebo je mezera prázdný řetězec, výsledek stringify() nebude mít žádné komentáře.

Pro výše uvedený případ:

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

assign(target: objekt, source?: objekt, keys?: pole)

• target object cílový objekt
• source? object zdrojový objekt. Tento parametr je nepovinný, ale je hloupost tento argument nepředávat.
• keys? Array<string> Pokud není uveden, budou použity všechny vyjmenované vlastní vlastnosti source.

Tato metoda slouží ke kopírování vyjmenovaných vlastních vlastností a jim odpovídajících vlastností symbolu komentáře do cílového objektu.

Zvláštní případy o klíčích

Jestliže je však uveden argument keys a není prázdný, pak komentář before all, který nepatří k žádným vlastnostem, NEBUDE kopírován.

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

Zadání argumentu keys jako prázdného pole znamená, že se budou kopírovat pouze nevlastní symboly komentářů

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

Mezi nevlastní symboly patří např:

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

CommentArray

Pokročilá sekce

Všechna pole analyzovaného objektu jsou CommentArrays.

Konstruktor CommentArray by mohl být přístupný:

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

Pokud bychom modifikovali pole komentářů, mohly by být automaticky zpracovány jeho vlastnosti symbolů komentářů.

Aha! 😆

Ale pozor, pokud vlastnost pole komentářů přeřadíme normálním polem, všechny komentáře zmizí:

Naopak bychom měli:

Zvláštní případy o koncové čárce

Pokud máme řetězec JSON str

.