hjson

What is hjson?

Hjson is a user interface for JSON. It allows you to write JSON in a more human-friendly format, making it easier to read and edit. Hjson supports comments, multi-line strings, and other features that make JSON more readable and maintainable.

What are hjson's main functionalities?

Parsing Hjson to JSON

This feature allows you to parse Hjson formatted strings into standard JSON objects. The code sample demonstrates how to convert a Hjson string with comments into a JSON object.

const Hjson = require('hjson');
const hjsonData = `{
  // This is a comment
  key: "value"
}`;
const jsonData = Hjson.parse(hjsonData);
console.log(jsonData);

Stringifying JSON to Hjson

This feature allows you to convert JSON objects into Hjson formatted strings. The code sample shows how to stringify a JSON object into a Hjson string with all keys quoted.

const Hjson = require('hjson');
const jsonData = { key: "value" };
const hjsonData = Hjson.stringify(jsonData, { quotes: 'all' });
console.log(hjsonData);

Reading Hjson from a file

This feature allows you to read Hjson data from a file and parse it into a JSON object. The code sample demonstrates reading a Hjson file and converting its content to a JSON object.

const Hjson = require('hjson');
const fs = require('fs');
const hjsonData = fs.readFileSync('data.hjson', 'utf8');
const jsonData = Hjson.parse(hjsonData);
console.log(jsonData);

Writing Hjson to a file

This feature allows you to write Hjson formatted strings to a file. The code sample shows how to convert a JSON object to a Hjson string and write it to a file.

const Hjson = require('hjson');
const fs = require('fs');
const jsonData = { key: "value" };
const hjsonData = Hjson.stringify(jsonData, { quotes: 'all' });
fs.writeFileSync('data.hjson', hjsonData);
console.log('Hjson data written to file');

Other packages similar to hjson

json5

JSON5 is an extension of JSON that aims to make JSON more human-friendly. It allows comments, trailing commas, and more. Compared to Hjson, JSON5 is closer to standard JSON but still offers some of the readability improvements.

yaml

YAML is a human-readable data serialization standard that can be used in conjunction with all programming languages. It is more flexible and readable than JSON but can be more complex. YAML supports comments, multi-line strings, and more, similar to Hjson.

toml

TOML is a data serialization language designed to be a minimal configuration file format that's easy to read due to its simplicity. It supports comments and is more readable than JSON, similar to Hjson.

README

hjson-js

Hjson JavaScript reference implementation.

Hjson is JSON - commas + comments for Humans.

It should be used for configuration files, for debug output or where it is likely that JSON data is read or will be edited by a human.

That means that you can write:

{
  # look, no quotes or commas!
  foo: Hello World!
  bar: Hello Hjson!

  # don't bother with escapes
  html: <div class="hello">world</div>

  # Hjson is a superset so the normal JSON syntax can be used
  "array": [ 1, "two" ]
}

instead of:

{
  "foo": "Hello World!",
  "bar": "Hello Hjson!",
  "html": "<div class=\"hello\">world</div>",
  "array": [ 1, "two" ]
}

For details see http://laktak.github.io/hjson.

Install from npm

npm install hjson

Usage

var Hjson = require('hjson');

var obj = Hjson.parse(hjsonText);
var text2 = Hjson.stringify(obj);

To keep comments intact see Editing.

From the Commandline

Install with npm install hjson -g.

usage: hjson [OPTIONS] [INPUT]

  hjson can be used to convert JSON from/to Hjson.

  hjson will read the given JSON/Hjson input file or read from stdin.
  - without options: will output as Hjson.
  - with -j or -json: will output as formatted JSON.
  - with -c or -json=compact: will output as JSON.

Sample:

• run hjson test.json > test.hjson to convert to Hjson
• run hjson -j test.hjson > test.json to convert to JSON

API

See hjson.js

Editing Hjson

You can modify a Hjson file and keep the whitespace & comments intact. This is useful if an app updates its config file.

// parse, keep whitespace and comments
// (they are stored in a non enumerable __WSC__ member)
var data = Hjson.parse(text, { keepWsc: true });

// modify like you normally would
data.foo = "text";

// you can also edit comments by accessing __WSC__
var wsc = data.__WSC__;
// __WSC__ for objects contains { c: {}, o: [] }
// - c with the actual comment and
// - o (array) with the order of the members
wsc.c.hugo = "just another test";
wsc.o.splice(2, 0, "hugo");
data.hugo = "value";

data.arrayWithComments = [ "a" ];
// __WSC__ for arrays is just an array with the
// comments ([0] for the space before the elements)
data.arrayWithComments.__WSC__ = [ "before a", "after a" ];

// convert back to Hjson
console.log(Hjson.stringify(data, { keepWsc: true }));

Changes

v1.0.0

• Switched to v1 for semver

• Adds editing support via the { keepWsc: true } option.

• Removes stringify(value, replacer, space) replacer support

  You can still use this syntax but replacer will no longer be called. This was removed in favor of editing support and because replacer provided an incomplete solution.