CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-hjson--hjson

Hjson (Human JSON) configuration file format library for Java providing parsing and generation capabilities with human-friendly features.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

Hjson Java Library

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.

Package Information

  • Package Name: org.hjson:hjson
  • Package Type: maven
  • Language: Java
  • Installation: Add to your build.gradle or pom.xml

Gradle

dependencies {
    implementation 'org.hjson:hjson:3.1.0'
}

Maven

<dependency>
    <groupId>org.hjson</groupId>
    <artifactId>hjson</artifactId>
    <version>3.1.0</version>
</dependency>

Core Imports

import org.hjson.JsonValue;
import org.hjson.JsonObject;
import org.hjson.JsonArray;
import org.hjson.HjsonOptions;
import org.hjson.ParseException;
import org.hjson.Stringify;

Basic Usage

import org.hjson.JsonValue;
import org.hjson.JsonObject;
import org.hjson.JsonArray;

// Parse Hjson string (supports comments, unquoted strings, etc.)
JsonValue value = JsonValue.readHjson("""
    {
        name: John Doe  // Comment supported
        age: 30
        active: true
        hobbies: [
            reading
            "playing guitar"
        ]
    }
    """);

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

// Create JSON programmatically
JsonObject newPerson = new JsonObject()
    .add("name", "Jane Smith")
    .add("age", 25)
    .add("active", true);

JsonArray hobbies = new JsonArray()
    .add("swimming")
    .add("hiking");
newPerson.add("hobbies", hobbies);

// Convert to different formats
String json = newPerson.toString(); // Compact JSON
String hjson = newPerson.toString(Stringify.HJSON); // Human-readable Hjson
String formatted = newPerson.toString(Stringify.FORMATTED); // Formatted JSON

Architecture

The Hjson Java library is built around several key components:

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

Capabilities

Hjson and JSON Parsing

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

// Parse Hjson
static JsonValue readHjson(String text);
static JsonValue readHjson(Reader reader) throws IOException;
static JsonValue readHjson(String text, HjsonOptions options);
static JsonValue readHjson(Reader reader, HjsonOptions options) throws IOException;

// Parse JSON
static JsonValue readJSON(String text);
static JsonValue readJSON(Reader reader) throws IOException;

// Global EOL configuration
static String getEol();
static void setEol(String value);

Hjson and JSON Parsing

JSON Object Operations

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

class JsonObject extends JsonValue implements Iterable<JsonObject.Member> {
    // Constructors
    JsonObject();
    JsonObject(JsonObject object);
    static JsonObject unmodifiableObject(JsonObject object);
    
    // Builder methods (fluent interface)
    JsonObject add(String name, JsonValue value);
    JsonObject add(String name, int value);
    JsonObject add(String name, long value);
    JsonObject add(String name, float value);
    JsonObject add(String name, double value);
    JsonObject add(String name, boolean value);
    JsonObject add(String name, String value);
    JsonObject set(String name, JsonValue value);
    JsonObject set(String name, int value);
    JsonObject set(String name, long value);
    JsonObject set(String name, float value);
    JsonObject set(String name, double value);
    JsonObject set(String name, boolean value);
    JsonObject set(String name, String value);
    JsonObject remove(String name);
    
    // Access methods with defaults
    JsonValue get(String name);
    String getString(String name, String defaultValue);
    int getInt(String name, int defaultValue);
    long getLong(String name, long defaultValue);
    float getFloat(String name, float defaultValue);
    double getDouble(String name, double defaultValue);
    boolean getBoolean(String name, boolean defaultValue);
    
    // Collection operations
    int size();
    boolean isEmpty();
    List<String> names();
}

JSON Object Operations

JSON Array Operations

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

class JsonArray extends JsonValue implements Iterable<JsonValue> {
    // Constructors
    JsonArray();
    JsonArray(JsonArray array);
    static JsonArray unmodifiableArray(JsonArray array);
    
    // Builder methods (fluent interface)  
    JsonArray add(JsonValue value);
    JsonArray add(int value);
    JsonArray add(long value);
    JsonArray add(float value);
    JsonArray add(double value);
    JsonArray add(boolean value);
    JsonArray add(String value);
    JsonArray set(int index, JsonValue value);
    JsonArray set(int index, int value);
    JsonArray set(int index, long value);
    JsonArray set(int index, float value);
    JsonArray set(int index, double value);
    JsonArray set(int index, boolean value);
    JsonArray set(int index, String value);
    JsonArray remove(int index);
    
    // Access methods
    JsonValue get(int index);
    int size();
    boolean isEmpty();
    List<JsonValue> values();
}

JSON Array Operations

Serialization and Output

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

// String output
String toString();
String toString(Stringify format);
String toString(HjsonOptions options);

// Stream output
void writeTo(Writer writer) throws IOException;
void writeTo(Writer writer, Stringify format) throws IOException;
void writeTo(Writer writer, HjsonOptions options) throws IOException;

// Format options
enum Stringify {
    PLAIN,      // Compact JSON
    FORMATTED,  // Pretty-printed JSON
    HJSON       // Human JSON format
}

Serialization and Output

Configuration and Options

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

class HjsonOptions {
    HjsonOptions();
    IHjsonDsfProvider[] getDsfProviders();
    void setDsfProviders(IHjsonDsfProvider[] providers);
    boolean getParseLegacyRoot();
    void setParseLegacyRoot(boolean value);
}

interface IHjsonDsfProvider {
    String getName();
    String getDescription();
    JsonValue parse(String text);
    String stringify(JsonValue value);
}

Configuration and Options

Type System and Error Handling

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

// Type checking
boolean isObject();
boolean isArray();
boolean isString();
boolean isNumber();
boolean isBoolean();
boolean isTrue();
boolean isFalse();
boolean isNull();
JsonType getType();

// Type conversion
JsonObject asObject();
JsonArray asArray();
String asString();
int asInt();
long asLong();
float asFloat();
double asDouble();
boolean asBoolean();
Object asDsf();

// Exception handling
class ParseException extends RuntimeException {
    int getOffset();
    int getLine(); 
    int getColumn();
}

Type System and Error Handling

Types

Core Value Types

abstract class JsonValue implements Serializable {
    // Constants
    static final JsonValue TRUE;
    static final JsonValue FALSE;
    static final JsonValue NULL;
    
    // Factory methods
    static JsonValue valueOf(String value);
    static JsonValue valueOf(int value);
    static JsonValue valueOf(long value);
    static JsonValue valueOf(float value);
    static JsonValue valueOf(double value);
    static JsonValue valueOf(boolean value);
    static JsonValue valueOfDsf(Object value);
}

enum JsonType {
    STRING, NUMBER, OBJECT, ARRAY, BOOLEAN, NULL, DSF
}

Member Type

static class JsonObject.Member {
    String getName();
    JsonValue getValue();
}

docs

configuration.md

index.md

json-arrays.md

json-objects.md

parsing.md

serialization.md

types-exceptions.md

tile.json