0
# Hjson Java Library
1

2
Hjson (Human JSON) is a configuration file format for humans that extends standard JSON with human-friendly features including comments, unquoted strings, optional commas, and multi-line strings. This Java library provides comprehensive parsing and generation capabilities for both Hjson and standard JSON formats, built on a familiar JsonValue/JsonObject/JsonArray API.
3

4
## Package Information
5

6
- **Package Name**: org.hjson:hjson
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your `build.gradle` or `pom.xml`
10

11
### Gradle
12

13
```gradle
14
dependencies {
15
    implementation 'org.hjson:hjson:3.1.0'
16
}
17
```
18

19
### Maven
20

21
```xml
22
<dependency>
23
    <groupId>org.hjson</groupId>
24
    <artifactId>hjson</artifactId>
25
    <version>3.1.0</version>
26
</dependency>
27
```
28

29
## Core Imports
30

31
```java
32
import org.hjson.JsonValue;
33
import org.hjson.JsonObject;
34
import org.hjson.JsonArray;
35
import org.hjson.HjsonOptions;
36
import org.hjson.ParseException;
37
import org.hjson.Stringify;
38
```
39

40
## Basic Usage
41

42
```java
43
import org.hjson.JsonValue;
44
import org.hjson.JsonObject;
45
import org.hjson.JsonArray;
46

47
// Parse Hjson string (supports comments, unquoted strings, etc.)
48
JsonValue value = JsonValue.readHjson("""
49
    {
50
        name: John Doe  // Comment supported
51
        age: 30
52
        active: true
53
        hobbies: [
54
            reading
55
            "playing guitar"
56
        ]
57
    }
58
    """);
59

60
// Access values
61
JsonObject person = value.asObject();
62
String name = person.getString("name", "");
63
int age = person.getInt("age", 0);
64
boolean active = person.getBoolean("active", false);
65

66
// Create JSON programmatically
67
JsonObject newPerson = new JsonObject()
68
    .add("name", "Jane Smith")
69
    .add("age", 25)
70
    .add("active", true);
71

72
JsonArray hobbies = new JsonArray()
73
    .add("swimming")
74
    .add("hiking");
75
newPerson.add("hobbies", hobbies);
76

77
// Convert to different formats
78
String json = newPerson.toString(); // Compact JSON
79
String hjson = newPerson.toString(Stringify.HJSON); // Human-readable Hjson
80
String formatted = newPerson.toString(Stringify.FORMATTED); // Formatted JSON
81
```
82

83
## Architecture
84

85
The Hjson Java library is built around several key components:
86

87
- **JsonValue Hierarchy**: Abstract base class with concrete implementations for objects, arrays, strings, numbers, booleans, and null values
88
- **Type System**: Runtime type checking with `is*()` methods and safe type conversion with `as*()` methods
89
- **Parsing Engine**: Separate parsers for Hjson and JSON with comprehensive error reporting
90
- **Serialization System**: Multiple output formats (compact JSON, formatted JSON, Hjson) with configurable options
91
- **DSF Support**: Domain Specific Format providers for specialized value parsing (math constants, hex numbers)
92
- **Fluent Interface**: Method chaining support for JsonObject and JsonArray construction
93

94
## Capabilities
95

96
### Hjson and JSON Parsing
97

98
Parse both Hjson and standard JSON from strings or readers with comprehensive error handling and optional configuration.
99

100
```java { .api }
101
// Parse Hjson
102
static JsonValue readHjson(String text);
103
static JsonValue readHjson(Reader reader) throws IOException;
104
static JsonValue readHjson(String text, HjsonOptions options);
105
static JsonValue readHjson(Reader reader, HjsonOptions options) throws IOException;
106

107
// Parse JSON
108
static JsonValue readJSON(String text);
109
static JsonValue readJSON(Reader reader) throws IOException;
110

111
// Global EOL configuration
112
static String getEol();
113
static void setEol(String value);
114
```
115

116
[Hjson and JSON Parsing](./parsing.md)
117

118
### JSON Object Operations
119

120
Create, modify, and query JSON objects with type-safe accessors and fluent interface support.
121

122
```java { .api }
123
class JsonObject extends JsonValue implements Iterable<JsonObject.Member> {
124
    // Constructors
125
    JsonObject();
126
    JsonObject(JsonObject object);
127
    static JsonObject unmodifiableObject(JsonObject object);
128
    
129
    // Builder methods (fluent interface)
130
    JsonObject add(String name, JsonValue value);
131
    JsonObject add(String name, int value);
132
    JsonObject add(String name, long value);
133
    JsonObject add(String name, float value);
134
    JsonObject add(String name, double value);
135
    JsonObject add(String name, boolean value);
136
    JsonObject add(String name, String value);
137
    JsonObject set(String name, JsonValue value);
138
    JsonObject set(String name, int value);
139
    JsonObject set(String name, long value);
140
    JsonObject set(String name, float value);
141
    JsonObject set(String name, double value);
142
    JsonObject set(String name, boolean value);
143
    JsonObject set(String name, String value);
144
    JsonObject remove(String name);
145
    
146
    // Access methods with defaults
147
    JsonValue get(String name);
148
    String getString(String name, String defaultValue);
149
    int getInt(String name, int defaultValue);
150
    long getLong(String name, long defaultValue);
151
    float getFloat(String name, float defaultValue);
152
    double getDouble(String name, double defaultValue);
153
    boolean getBoolean(String name, boolean defaultValue);
154
    
155
    // Collection operations
156
    int size();
157
    boolean isEmpty();
158
    List<String> names();
159
}
160
```
161

162
[JSON Object Operations](./json-objects.md)
163

164
### JSON Array Operations
165

166
Create, modify, and iterate over JSON arrays with type-safe element access and fluent construction.
167

168
```java { .api }
169
class JsonArray extends JsonValue implements Iterable<JsonValue> {
170
    // Constructors
171
    JsonArray();
172
    JsonArray(JsonArray array);
173
    static JsonArray unmodifiableArray(JsonArray array);
174
    
175
    // Builder methods (fluent interface)  
176
    JsonArray add(JsonValue value);
177
    JsonArray add(int value);
178
    JsonArray add(long value);
179
    JsonArray add(float value);
180
    JsonArray add(double value);
181
    JsonArray add(boolean value);
182
    JsonArray add(String value);
183
    JsonArray set(int index, JsonValue value);
184
    JsonArray set(int index, int value);
185
    JsonArray set(int index, long value);
186
    JsonArray set(int index, float value);
187
    JsonArray set(int index, double value);
188
    JsonArray set(int index, boolean value);
189
    JsonArray set(int index, String value);
190
    JsonArray remove(int index);
191
    
192
    // Access methods
193
    JsonValue get(int index);
194
    int size();
195
    boolean isEmpty();
196
    List<JsonValue> values();
197
}
198
```
199

200
[JSON Array Operations](./json-arrays.md)
201

202
### Serialization and Output
203

204
Convert JSON values to various string formats and write to streams with configurable formatting options.
205

206
```java { .api }
207
// String output
208
String toString();
209
String toString(Stringify format);
210
String toString(HjsonOptions options);
211

212
// Stream output
213
void writeTo(Writer writer) throws IOException;
214
void writeTo(Writer writer, Stringify format) throws IOException;
215
void writeTo(Writer writer, HjsonOptions options) throws IOException;
216

217
// Format options
218
enum Stringify {
219
    PLAIN,      // Compact JSON
220
    FORMATTED,  // Pretty-printed JSON
221
    HJSON       // Human JSON format
222
}
223
```
224

225
[Serialization and Output](./serialization.md)
226

227
### Configuration and Options
228

229
Configure parsing behavior and output formatting with HjsonOptions and Domain Specific Format providers.
230

231
```java { .api }
232
class HjsonOptions {
233
    HjsonOptions();
234
    IHjsonDsfProvider[] getDsfProviders();
235
    void setDsfProviders(IHjsonDsfProvider[] providers);
236
    boolean getParseLegacyRoot();
237
    void setParseLegacyRoot(boolean value);
238
}
239

240
interface IHjsonDsfProvider {
241
    String getName();
242
    String getDescription();
243
    JsonValue parse(String text);
244
    String stringify(JsonValue value);
245
}
246
```
247

248
[Configuration and Options](./configuration.md)
249

250
### Type System and Error Handling
251

252
Runtime type checking, safe type conversion, and comprehensive error reporting for invalid input.
253

254
```java { .api }
255
// Type checking
256
boolean isObject();
257
boolean isArray();
258
boolean isString();
259
boolean isNumber();
260
boolean isBoolean();
261
boolean isTrue();
262
boolean isFalse();
263
boolean isNull();
264
JsonType getType();
265

266
// Type conversion
267
JsonObject asObject();
268
JsonArray asArray();
269
String asString();
270
int asInt();
271
long asLong();
272
float asFloat();
273
double asDouble();
274
boolean asBoolean();
275
Object asDsf();
276

277
// Exception handling
278
class ParseException extends RuntimeException {
279
    int getOffset();
280
    int getLine(); 
281
    int getColumn();
282
}
283
```
284

285
[Type System and Error Handling](./types-exceptions.md)
286

287
## Types
288

289
### Core Value Types
290

291
```java { .api }
292
abstract class JsonValue implements Serializable {
293
    // Constants
294
    static final JsonValue TRUE;
295
    static final JsonValue FALSE;
296
    static final JsonValue NULL;
297
    
298
    // Factory methods
299
    static JsonValue valueOf(String value);
300
    static JsonValue valueOf(int value);
301
    static JsonValue valueOf(long value);
302
    static JsonValue valueOf(float value);
303
    static JsonValue valueOf(double value);
304
    static JsonValue valueOf(boolean value);
305
    static JsonValue valueOfDsf(Object value);
306
}
307

308
enum JsonType {
309
    STRING, NUMBER, OBJECT, ARRAY, BOOLEAN, NULL, DSF
310
}
311
```
312

313
### Member Type
314

315
```java { .api }
316
static class JsonObject.Member {
317
    String getName();
318
    JsonValue getValue();
319
}
320
```