Parse et stringifie JSON avec des commentaires. Il conservera les commentaires même après avoir été sauvegardé!

• Parse les chaînes JSON avec des commentaires en objets JavaScript et MAINTIENT les commentaires
  • supports des commentaires partout, oui, PARTOUT dans un fichier JSON, éventuellement 😆
  • corrige le problème connu sur les commentaires à l’intérieur des tableaux.
• Transformer les objets en chaînes JSON avec des commentaires s’il y en a

L’utilisation de comment-json est exactement la même que celle de l’objet vanille JSON.

Table des matières

• Pourquoi et comment
• Utilisation et exemples
• Référence à l’API
  .
  • parse
  • stringify
  • assign
  • CommentArray
• Changement des journaux

Pourquoi ?

Il y a beaucoup d’autres bibliothèques qui peuvent traiter le JSON avec des commentaires, comme json5, ou strip-json-comments, mais aucune d’entre elles ne peut stringifier l’objet analysé et renvoyer une chaîne JSON identique au contenu original.

Imaginez que si les paramètres de l’utilisateur sont enregistrés dans ${library}.json， et que l’utilisateur a écrit beaucoup de commentaires pour améliorer la lisibilité. Si la bibliothèque library a besoin de modifier le paramètre de l’utilisateur, comme modifier certaines valeurs de propriété et ajouter de nouveaux champs, et si la bibliothèque utilise json5 pour lire les paramètres, tous les commentaires disparaîtront après avoir été modifiés, ce qui rendra les gens fous.

Donc, si vous voulez analyser une chaîne JSON avec des commentaires, la modifier, puis la sauvegarder à nouveau, comment-json est votre choix incontournable !

Comment ?

comment-jsonparse les chaînes JSON avec des commentaires et enregistre les tokens de commentaires dans les propriétés des symboles.

Pour le tableau JSON avec des commentaires, comment-json étend l’objet vanille Array en CommentArray dont les instances pourraient gérer les changements de commentaires même après qu’un tableau de commentaires soit modifié.

Install

$ npm i comment-json

Pour les développeurs TypeScript, @types/comment-json pourrait être utilisé

Depuis 2.4.1, comment-json contient des déclarations typescript, donc vous pourriez aussi bien supprimer @types/comment-json.

Usage

package.json:

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

Trier les clés

C’est un cas d’utilisation courant pour trier les clés d’un fichier JSON

Pour des détails sur assign, voir ici.

parse()

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

• texte string La chaîne de caractères à analyser en tant que JSON. Voir l’objet JSON pour une description de la syntaxe JSON.
• reviver ? Function() | null La valeur par défaut est null. Il agit de la même manière que le deuxième paramètre de JSON.parse. Si c’est une fonction, prescrit la façon dont la valeur produite à l’origine par l’analyse syntaxique est transformée, avant d’être retournée.
• remove_comments ? boolean = false Si vrai, les commentaires ne seront pas maintenus, ce qui est souvent utilisé quand on veut obtenir un objet propre.

Retourne object | string | number | boolean | null correspondant au texte JSON donné.

Si le content est :

Et la valeur de parsed sera :

Il y a HUIT types de propriétés de symboles :

Et la valeur de chaque propriété de symbole est un tableau de 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 en un objet sans commentaires

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

Et le résultat sera :

{
 foo: 1,
 bar: 
}

Cas particuliers

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

Si nous analysons un JSON de type primitif avec remove_comments:false, alors la valeur de retour de parse() sera de type objet.

La valeur de parsed est équivalente à:

Ce qui est similaire pour:

• Boolean type
• String type

Par exemple

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

Ce qui est équivalent à

Mais il y a une exception :

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

stringify()

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

Les arguments sont les mêmes que ceux de la vanille JSON.stringify.

Et elle fait la même chose que la vanille, mais traite aussi des propriétés supplémentaires et les convertit en commentaires.

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

espace

Si l’espace n’est pas spécifié, ou si l’espace est une chaîne vide, le résultat de stringify() n’aura pas de commentaires.

Pour le cas ci-dessus :

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

assign(cible : objet, source? : objet, clés? : tableau)

• cible object l’objet cible
• source ? object l’objet source. Ce paramètre est facultatif mais il est idiot de ne pas passer cet argument.
• clés ? Array<string> S’il n’est pas spécifié, toutes les propriétés propres énumérables de source seront utilisées.

Cette méthode est utilisée pour copier les propriétés propres énumérables et leurs propriétés de symbole de commentaire correspondantes vers l’objet cible.

Cas particuliers concernant les clés

Mais si l’argument keys est spécifié et n’est pas vide, alors le commentaire before all, qui n’appartient à aucune propriété, ne sera PAS copié.

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

Spécifier l’argument keys comme un tableau vide indique qu’il ne copiera que les symboles de commentaires n’appartenant à aucune propriété

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

Les symboles n’appartenant à aucune propriété comprennent :

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

Tableau de commentaires

Section avancée

Tous les tableaux de l’objet analysé sont CommentArrays.

On pourrait accéder au constructeur de CommentArray par :

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

Si on modifie un tableau de commentaires, ses propriétés de symboles de commentaires pourraient être traitées automatiquement.

Oh oui ! 😆

Mais attention, si vous réassignez la propriété d’un tableau de commentaires avec un tableau normal, tous les commentaires disparaîtront :

A la place, nous devrions :

Cas particuliers sur la virgule de fin

Si nous avons une chaîne JSON str

.