source: trip-planner-front/node_modules/json5/README.md@ 76712b2

Last change on this file since 76712b2 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 7.6 KB
Line 
1# JSON5 – JSON for Humans
2
3[![Build Status](https://travis-ci.com/json5/json5.svg)][Build Status]
4[![Coverage
5Status](https://coveralls.io/repos/github/json5/json5/badge.svg)][Coverage
6Status]
7
8The JSON5 Data Interchange Format (JSON5) is a superset of [JSON] that aims to
9alleviate some of the limitations of JSON by expanding its syntax to include
10some productions from [ECMAScript 5.1].
11
12This JavaScript library is the official reference implementation for JSON5
13parsing and serialization libraries.
14
15[Build Status]: https://travis-ci.com/json5/json5
16
17[Coverage Status]: https://coveralls.io/github/json5/json5
18
19[JSON]: https://tools.ietf.org/html/rfc7159
20
21[ECMAScript 5.1]: https://www.ecma-international.org/ecma-262/5.1/
22
23## Summary of Features
24The following ECMAScript 5.1 features, which are not supported in JSON, have
25been extended to JSON5.
26
27### Objects
28- Object keys may be an ECMAScript 5.1 _[IdentifierName]_.
29- Objects may have a single trailing comma.
30
31### Arrays
32- Arrays may have a single trailing comma.
33
34### Strings
35- Strings may be single quoted.
36- Strings may span multiple lines by escaping new line characters.
37- Strings may include character escapes.
38
39### Numbers
40- Numbers may be hexadecimal.
41- Numbers may have a leading or trailing decimal point.
42- Numbers may be [IEEE 754] positive infinity, negative infinity, and NaN.
43- Numbers may begin with an explicit plus sign.
44
45### Comments
46- Single and multi-line comments are allowed.
47
48### White Space
49- Additional white space characters are allowed.
50
51[IdentifierName]: https://www.ecma-international.org/ecma-262/5.1/#sec-7.6
52
53[IEEE 754]: http://ieeexplore.ieee.org/servlet/opac?punumber=4610933
54
55## Short Example
56```js
57{
58 // comments
59 unquoted: 'and you can quote me on that',
60 singleQuotes: 'I can use "double quotes" here',
61 lineBreaks: "Look, Mom! \
62No \\n's!",
63 hexadecimal: 0xdecaf,
64 leadingDecimalPoint: .8675309, andTrailing: 8675309.,
65 positiveSign: +1,
66 trailingComma: 'in objects', andIn: ['arrays',],
67 "backwardsCompatible": "with JSON",
68}
69```
70
71## Specification
72For a detailed explanation of the JSON5 format, please read the [official
73specification](https://json5.github.io/json5-spec/).
74
75## Installation
76### Node.js
77```sh
78npm install json5
79```
80
81```js
82const JSON5 = require('json5')
83```
84
85### Browsers
86```html
87<script src="https://unpkg.com/json5@^2.0.0/dist/index.min.js"></script>
88```
89
90This will create a global `JSON5` variable.
91
92## API
93The JSON5 API is compatible with the [JSON API].
94
95[JSON API]:
96https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON
97
98### JSON5.parse()
99Parses a JSON5 string, constructing the JavaScript value or object described by
100the string. An optional reviver function can be provided to perform a
101transformation on the resulting object before it is returned.
102
103#### Syntax
104 JSON5.parse(text[, reviver])
105
106#### Parameters
107- `text`: The string to parse as JSON5.
108- `reviver`: If a function, this prescribes how the value originally produced by
109 parsing is transformed, before being returned.
110
111#### Return value
112The object corresponding to the given JSON5 text.
113
114### JSON5.stringify()
115Converts a JavaScript value to a JSON5 string, optionally replacing values if a
116replacer function is specified, or optionally including only the specified
117properties if a replacer array is specified.
118
119#### Syntax
120 JSON5.stringify(value[, replacer[, space]])
121 JSON5.stringify(value[, options])
122
123#### Parameters
124- `value`: The value to convert to a JSON5 string.
125- `replacer`: A function that alters the behavior of the stringification
126 process, or an array of String and Number objects that serve as a whitelist
127 for selecting/filtering the properties of the value object to be included in
128 the JSON5 string. If this value is null or not provided, all properties of the
129 object are included in the resulting JSON5 string.
130- `space`: A String or Number object that's used to insert white space into the
131 output JSON5 string for readability purposes. If this is a Number, it
132 indicates the number of space characters to use as white space; this number is
133 capped at 10 (if it is greater, the value is just 10). Values less than 1
134 indicate that no space should be used. If this is a String, the string (or the
135 first 10 characters of the string, if it's longer than that) is used as white
136 space. If this parameter is not provided (or is null), no white space is used.
137 If white space is used, trailing commas will be used in objects and arrays.
138- `options`: An object with the following properties:
139 - `replacer`: Same as the `replacer` parameter.
140 - `space`: Same as the `space` parameter.
141 - `quote`: A String representing the quote character to use when serializing
142 strings.
143
144#### Return value
145A JSON5 string representing the value.
146
147### Node.js `require()` JSON5 files
148When using Node.js, you can `require()` JSON5 files by adding the following
149statement.
150
151```js
152require('json5/lib/register')
153```
154
155Then you can load a JSON5 file with a Node.js `require()` statement. For
156example:
157
158```js
159const config = require('./config.json5')
160```
161
162## CLI
163Since JSON is more widely used than JSON5, this package includes a CLI for
164converting JSON5 to JSON and for validating the syntax of JSON5 documents.
165
166### Installation
167```sh
168npm install --global json5
169```
170
171### Usage
172```sh
173json5 [options] <file>
174```
175
176If `<file>` is not provided, then STDIN is used.
177
178#### Options:
179- `-s`, `--space`: The number of spaces to indent or `t` for tabs
180- `-o`, `--out-file [file]`: Output to the specified file, otherwise STDOUT
181- `-v`, `--validate`: Validate JSON5 but do not output JSON
182- `-V`, `--version`: Output the version number
183- `-h`, `--help`: Output usage information
184
185## Contributing
186### Development
187```sh
188git clone https://github.com/json5/json5
189cd json5
190npm install
191```
192
193When contributing code, please write relevant tests and run `npm test` and `npm
194run lint` before submitting pull requests. Please use an editor that supports
195[EditorConfig](http://editorconfig.org/).
196
197### Issues
198To report bugs or request features regarding the JSON5 data format, please
199submit an issue to the [official specification
200repository](https://github.com/json5/json5-spec).
201
202To report bugs or request features regarding the JavaScript implementation of
203JSON5, please submit an issue to this repository.
204
205## License
206MIT. See [LICENSE.md](./LICENSE.md) for details.
207
208## Credits
209[Assem Kishore](https://github.com/aseemk) founded this project.
210
211[Michael Bolin](http://bolinfest.com/) independently arrived at and published
212some of these same ideas with awesome explanations and detail. Recommended
213reading: [Suggested Improvements to JSON](http://bolinfest.com/essays/json.html)
214
215[Douglas Crockford](http://www.crockford.com/) of course designed and built
216JSON, but his state machine diagrams on the [JSON website](http://json.org/), as
217cheesy as it may sound, gave us motivation and confidence that building a new
218parser to implement these ideas was within reach! The original
219implementation of JSON5 was also modeled directly off of Doug’s open-source
220[json_parse.js] parser. We’re grateful for that clean and well-documented
221code.
222
223[json_parse.js]:
224https://github.com/douglascrockford/JSON-js/blob/03157639c7a7cddd2e9f032537f346f1a87c0f6d/json_parse.js
225
226[Max Nanasy](https://github.com/MaxNanasy) has been an early and prolific
227supporter, contributing multiple patches and ideas.
228
229[Andrew Eisenberg](https://github.com/aeisenberg) contributed the original
230`stringify` method.
231
232[Jordan Tucker](https://github.com/jordanbtucker) has aligned JSON5 more closely
233with ES5, wrote the official JSON5 specification, completely rewrote the
234codebase from the ground up, and is actively maintaining this project.
Note: See TracBrowser for help on using the repository browser.