Son CV dans un terminal web en Javascript! https://terminal-cv.gregandev.fr
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

140 lines
5.2 KiB

# json-source-map
Parse/stringify JSON and provide source-map for JSON-pointers to all nodes.
NEW: supports BigInt, Maps, Sets and Typed arrays.
[![Build Status](https://travis-ci.org/epoberezkin/json-source-map.svg?branch=master)](https://travis-ci.org/epoberezkin/json-source-map)
[![npm version](https://badge.fury.io/js/json-source-map.svg)](https://www.npmjs.com/package/json-source-map)
[![Coverage Status](https://coveralls.io/repos/github/epoberezkin/json-source-map/badge.svg?branch=master)](https://coveralls.io/github/epoberezkin/json-source-map?branch=master)
## Install
```bash
npm install json-source-map
```
## Possible use cases
#### Source maps
When a domain-specific language that compiles to JavaScript uses JSON as a format, this module can be used as a replacement for standard JSON to simplify generation of source maps.
#### Editing forms/JSON
When a form also allows to edit JSON representation of data on the same screen, this module can be used to sinchronise navigation in JSON and in the form.
## Usage
#### Stringify
```javascript
var jsonMap = require('json-source-map');
var result = jsonMap.stringify({ foo: 'bar' }, null, 2);
console.log('json:');
console.log(result.json);
console.log('\npointers:');
console.log(result.pointers);
```
output:
```text
json:
{
"foo": "bar"
}
pointers:
{ '':
{ value: { line: 0, column: 0, pos: 0 },
valueEnd: { line: 2, column: 1, pos: 18 } },
'/foo':
{ key: { line: 1, column: 2, pos: 4 },
keyEnd: { line: 1, column: 7, pos: 9 },
value: { line: 1, column: 9, pos: 11 },
valueEnd: { line: 1, column: 14, pos: 16 } } }
```
#### Parse
```javascript
var result = jsonMap.parse('{ "foo": "bar" }');
console.log('data:')
console.log(result.data);
console.log('\npointers:');
console.log(result.pointers);
```
output:
```text
data:
{ foo: 'bar' }
pointers:
{ '':
{ value: { line: 0, column: 0, pos: 0 },
valueEnd: { line: 0, column: 16, pos: 16 } },
'/foo':
{ key: { line: 0, column: 2, pos: 2 },
keyEnd: { line: 0, column: 7, pos: 7 },
value: { line: 0, column: 9, pos: 9 },
valueEnd: { line: 0, column: 14, pos: 14 } } }
```
## API
#### .parse(String json, Any _, Object options) -> Object;
Parses JSON string. Returns object with properties:
- _data_: parsed data.
- _pointers_: an object where each key is a JSON pointer ([RFC 6901](https://tools.ietf.org/html/rfc6901)), each corresponding value is a mapping object.
Mapping object has properties:
- _key_: location object (see below) of the beginning of the key in JSON string. This property is only present if parent data is an object (rather than array).
- _keyEnd_: location of the end of the key in JSON string. This property is only present if parent data is an object.
- _value_: location of the beginning of the value in JSON string.
- _valueEnd_: location of the end of the value in JSON string.
Location object has properties (zero-based numbers):
- _line_: line number in JSON file.
- _column_: column number in JSON string (from the beginning of line).
- _pos_: character position in JSON file (from the beginning of JSON string).
Options:
- _bigint_: parse large integers as [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt).
Whitespace:
- the only character that increases line number in mappings is line feed ('\n'), so if your JSON string has '\r\n' sequence, it will still be counted as one line,
- both '\r' and '\n' are counted as a character when determining `pos` (it is possible to slice sections of JSON string using `pos` property), but `column` counter is reset when `r` or `n` is encountered,
- tabs ('\t') are counted as four spaces when determining `column` but as a single character for `pos`.
Comparison with the standard `JSON.parse`:
- when it is not possible to parse JSON, a SyntaxError exception with exactly the same message is thrown,
- `reviver` parameter of [JSON.parse](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#Using_the_reviver_parameter) is not supported, but its position is reserved.
- supports parsing large integers as [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) (with the option `bigint: true`).
#### .stringify(Any data, Any _, String|Number|Object space) -> Object;
Stringifies JavaScript data. Returns object with properties:
- _json_: JSON string - stringified data.
- _pointers_: an object where each key is a JSON-pointer, each corresponding value is a mapping object (same format as in parse method).
Comparison with the standard `JSON.stringify`:
- `replacer` parameter of [JSON.stringify](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_replacer_parameter) is not supported, but its position is reserved.
- `space` parameter is supported, but if it is a string, it may only contain characters space, tab ('\t'), caret return ('\r') and line feed ('\n') - using any other caracter throws an exception. If this parameter is an object, it is options.
Options:
- _space_: same as `space` parameter.
- _es6_: stringify ES6 Maps, Sets and Typed arrays (as JSON arrays).
## License
[MIT](https://github.com/epoberezkin/json-source-map/blob/master/LICENSE)