|
1 | | -# json5 |
2 | | -A JSON5 Library for Java |
| 1 | +# json5 [](https://javadoc.syntaxerror.at/json5/latest)  |
| 2 | + |
| 3 | +A JSON5 Library for Java (11+) |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The [JSON5 Standard](https://json5.org/) tries to make JSON more human-readable |
| 8 | + |
| 9 | +This is a reference implementation, capable of parsing JSON5 data according to the [specification](https://spec.json5.org/). |
| 10 | + |
| 11 | +## Getting started |
| 12 | + |
| 13 | +In order to use the code, you can either [download the jar](), or use the Maven dependency: |
| 14 | +```xml |
| 15 | +<!-- Repository --> |
| 16 | + |
| 17 | +<repository> |
| 18 | + <id>syntaxerror.at</id> |
| 19 | + <url>https://maven.syntaxerror.at</url> |
| 20 | +</repository> |
| 21 | + |
| 22 | +<!-- Dependency --> |
| 23 | + |
| 24 | +<dependency> |
| 25 | + <groupId>at.syntaxerror</groupId> |
| 26 | + <artifactId>json5</artifactId> |
| 27 | + <version>1.0.0</version> |
| 28 | +</dependency> |
| 29 | +``` |
| 30 | + |
| 31 | +The library itself is located in the module `json5`. |
| 32 | + |
| 33 | +## Usage |
| 34 | + |
| 35 | +### Deserializing (Parsing) |
| 36 | + |
| 37 | +To parse a JSON object (`{ ... }`), all you need to do is: |
| 38 | +```java |
| 39 | +import at.syntaxerror.json5.JSONObject; |
| 40 | + |
| 41 | +//... |
| 42 | + |
| 43 | +JSONObject jsonObject = new JSONObject("{ ... }"); |
| 44 | +``` |
| 45 | + |
| 46 | +Or if you want to read directly from a `Reader` or `InputStream`: |
| 47 | +```java |
| 48 | +import java.io.InputStream; |
| 49 | +import at.syntaxerror.json5.JSONObject; |
| 50 | + |
| 51 | +//... |
| 52 | + |
| 53 | +try(InputStream stream = ...) { |
| 54 | + JSONObject jsonObject = new JSONObject(new JSONParser(stream)); |
| 55 | + // ... |
| 56 | +} catch (Exception e) { |
| 57 | + //... |
| 58 | +} |
| 59 | +``` |
| 60 | + |
| 61 | +Just replace `JSONObject` with `JSONArray` to read list-like data (`[ ... ]`). |
| 62 | + |
| 63 | +### Serializing (Stringifying) |
| 64 | + |
| 65 | +Both the `JSONObject` and `JSONArray` class contain two methods for serialization: |
| 66 | +- `toString()` and |
| 67 | +- `toString(int indentFactor)` |
| 68 | + |
| 69 | +The normal `toString()` method will return the compact string representation, without any optional whitespaces. |
| 70 | +The `indentFactor` of the `toString(int indentFactor)` method will enable pretty-printing if `> 0`. |
| 71 | +Any value `< 1` will disable pretty-printing. The indent factor indicates the number of spaces before each key-value pair/ value: |
| 72 | + |
| 73 | +`indentFactor = 2` |
| 74 | +```json |
| 75 | +{ |
| 76 | + "key0": "value0", |
| 77 | + "key1": { |
| 78 | + "nested": 123 |
| 79 | + }, |
| 80 | + "key2": false |
| 81 | +} |
| 82 | + |
| 83 | +[ |
| 84 | + "value", |
| 85 | + { |
| 86 | + "nested": 123 |
| 87 | + }, |
| 88 | + false |
| 89 | +] |
| 90 | +``` |
| 91 | + |
| 92 | +`indentFactor = 0` |
| 93 | +```json |
| 94 | +{"key0":"value0","key1":{"nested":123},"key2":false} |
| 95 | + |
| 96 | +["value",{"nested":123},false] |
| 97 | +``` |
| 98 | + |
| 99 | +Calling `json.toString(indentFactor)` is the same as `JSONStringify.toString(json, indentFactor)`. |
| 100 | + |
| 101 | +### Working with JSONObjects and JSONArrays |
| 102 | + |
| 103 | +The `getXXX` methods are used to read values from the JSON object/ array. |
| 104 | +The `set` methods are used to override or set values in the JSON object/ array. |
| 105 | +The `add` methods are used to add values to a JSON array. |
| 106 | + |
| 107 | +Supported data types are: |
| 108 | +- `boolean` |
| 109 | +- `byte` |
| 110 | +- `short` |
| 111 | +- `int` |
| 112 | +- `float` |
| 113 | +- `double` |
| 114 | +- `String` |
| 115 | +- `JSONObject` |
| 116 | +- `JSONArray` |
| 117 | + |
| 118 | +The normal `getXXX(String key)` and `getXXX(int index)` methods will throw an exception if the specified key or index does not exist, but the |
| 119 | +`getXXX(String key, XXX defaults)` and `getXXX(int index, XXX defaults)` methods will return the default value (parameter `defaults`) instead. |
| 120 | + |
| 121 | +The `set(int index, XXX value)` method will also throw an exception if the index does not exist. You can use `add(XXX value)` instead to append a value to the list. |
| 122 | + |
| 123 | +The getter-methods for numbers always return a rounded or truncated result. |
| 124 | +If the actual number is too large to fit into the requested type, the upper bits are truncated (e.g. `int` to `byte` truncates the upper 24 bits). |
| 125 | +If the actual number is a decimal number (e.g. `123.456`), and the requested type is not (e.g. `long`), the decimal places are discarded. |
| 126 | +To check if a number can fit into a type, you can use the `getXXXExact` methods, which will throw an exception if the conversion is not possible without altering the result. |
| 127 | + |
| 128 | +Numbers are internally always stored as either a `java.math.BigInteger`, `java.math.BigDecimal`, or `double` (`double` is used for `Infinity` and `NaN` only). Therefore, any method |
| 129 | +returning raw `java.lang.Object`s will return numbers as one of those types. The same behaviour applies to the `getNumber` methods. |
| 130 | + |
| 131 | +## Documentation |
| 132 | + |
| 133 | +The JavaDoc for the latest version can be found [here](https://javadoc.syntaxerror.at/json5/latest). |
| 134 | + |
| 135 | +## Credits |
| 136 | + |
| 137 | +This project is partly based on stleary's [JSON-Java](https://github.com/stleary/JSON-java) library. |
| 138 | + |
| 139 | +## License |
| 140 | + |
| 141 | +This project is licensed under the [MIT License](https://github.com/Synt4xErr0r4/json5/blob/main/LICENSE) |
0 commit comments