Parse e stringify JSON com comentários. Ele irá reter comentários mesmo depois de salvo!

• Pare as strings do JSON com comentários em objetos JavaScript e MANTENHA os comentários
  • suporta comentários em todo lugar, sim, TUDO em um arquivo JSON, eventualmente 😆
  • corrige o problema conhecido sobre comentários dentro de arrays.
• Stringify the objects into JSON strings with comments if there are

The usage of comment-json is exactly the same as the vanilla JSON object.

Índice

• Porque e Como
• Utilização e exemplos
• ReferênciaAPI
  • parse
  • stringify
  • assignar
  • ComentarArray
• Alterar Registos

Porquê?

Há muitas outras bibliotecas que podem lidar com o JSON com comentários, tais como json5, ou strip-json-comments, mas nenhuma delas pode codificar o objeto analisado e devolver uma string JSON igual ao conteúdo original.

Imagine que se as configurações do usuário forem salvas em ${library}.json， e o usuário tiver escrito muitos comentários para melhorar a legibilidade. Se a biblioteca library precisar modificar a configuração do usuário, como modificar alguns valores de propriedade e adicionar novos campos, e se a biblioteca usar json5 para ler as configurações, todos os comentários desaparecerão depois de modificados, o que deixará as pessoas loucas.

Então, se você quiser analisar uma string JSON com comentários, modifique-a, depois salve-a de volta, comment-json é sua escolha obrigatória!

Como?

comment-json analisar as strings JSON com comentários e salvar as fichas de comentários em propriedades de símbolos.

Para o array JSON com comentários, comment-json estende o objeto vanilla Array para CommentArray cujas instâncias poderiam lidar com as alterações dos comentários mesmo depois que um array de comentários é modificado.

Instale

$ npm i comment-json

Para desenvolvedores de TypeScript, @types/comment-json poderia ser usado

Desde 2.4.1, comment-json contém declarações de digitação, então você também poderia remover @types/comment-json.

Uso

package.json:

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

Classificar chaves

É um caso de uso comum para classificar as chaves de um arquivo JSON

Para detalhes sobre assign, veja aqui.

parse()

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

• texto string A cadeia a ser analisada como JSON. Veja o objeto JSON para uma descrição da sintaxe JSON.
• reviver? Function() | null Predefinição para null. Ele age da mesma forma que o segundo parâmetro de JSON.parse. Se uma função, prescreve como o valor originalmente produzido pelo parsing é transformado, antes de ser retornado.
• remove_comments? boolean = false Se for verdade, os comentários não serão mantidos, o que é frequentemente usado quando queremos obter um objecto limpo.

Retornos object | string | number | boolean | null correspondente ao texto JSON dado.

Se o content for:

E o valor de parsed será:

Existem OITO tipos de propriedades de símbolos:

E o valor de cada propriedade de símbolo é um array 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 em um objeto sem comentários

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

E o resultado será:

{
 foo: 1,
 bar: 
}

Casos especiais

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

Se analisarmos um JSON do tipo primativo com remove_comments:false, então o valor de retorno de parse() será do tipo objeto.

O valor de parsed é equivalente a:

O que é semelhante para:

• Boolean tipo
• String tipo

Por exemplo

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

O que é equivalente a

Mas há uma excepção:

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

stringify()

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

Os argumentos são os mesmos que a baunilha JSON.stringify.

E faz o mesmo que a baunilha, mas também lida com propriedades extras e as converte em comentários.

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

espaço

Se o espaço não for especificado, ou se o espaço for uma string vazia, o resultado de stringify() não terá comentários.

Para o caso acima:

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 o objeto fonte. Este parâmetro é opcional mas é tolice não passar este argumento.
• chaves? Array<string> Se não especificado, todas as propriedades próprias enumeradas de source serão usadas.

Este método é usado para copiar as propriedades próprias enumeradas e suas propriedades de símbolo de comentário correspondentes para o objeto de destino.

Casos especiais sobre chaves

Mas se o argumento keys for especificado e não estiver vazio, então o comentário before all, que não pertence a nenhuma propriedade, NÃO será copiado.

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

Especificando o argumento keys como um array vazio indica que apenas copiará símbolos sem propriedades de comentários

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

Siglas sem propriedades incluem:

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

ComentárioArray

Secção Avançada

Todos os conjuntos do objeto analisado são CommentArrays.

O construtor de CommentArray poderia ser acessado por:

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

Se modificarmos um array de comentários, suas propriedades de símbolos de comentários poderiam ser tratadas automaticamente.

Oh yeah! 😆

Mas preste atenção, se você reatribuir a propriedade de um array de comentários com um array normal, todos os comentários desaparecerão:

Em vez disso, devemos:

Casos Especiais sobre Trailing Comma

Se tivermos uma string JSON str