Hjson

Warnings

• gotcha Quoteless strings in Hjson automatically end at the newline. Preceding and trailing whitespace is ignored, and escapes are not supported. Additionally, a quoteless string cannot start with a comment sequence (`#`, `//`, `/*`), as these characters would become part of the string or be misinterpreted.
  Fix: For explicit string content, especially with whitespace, comments, or escapes, always use single or double quotes. Place comments on separate lines before or after the string value.
• gotcha Hjson's relaxed syntax can introduce ambiguity, particularly with quoteless strings that resemble booleans or numbers. For example, `true` is parsed as a boolean, but `True` (with a capital 'T') is parsed as a string, because it's not a recognized boolean literal in Hjson.
  Fix: Be mindful of Hjson's type inference rules. If strict type control is necessary, explicitly quote string values that could be misinterpreted as other data types.
• gotcha When parsing Hjson, if the root object's opening brace `{` is on the same line as its first key-value pair without a preceding newline, the Python parser might error or misinterpret the structure. While not explicitly in official docs as a bug, it's a reported parsing quirk.
  Fix: Ensure opening and closing braces for the root object are on separate lines from their content for robust parsing. Example: `{ \n key: value \n }` instead of `{ key: value }`.
• deprecated For `hjson.dumps()`, the `indent` parameter in versions prior to 2.1.0 accepted an integer, which was then converted to a string of spaces. While still supported for backwards compatibility, it is now recommended to pass a string (e.g., `' '`) for indentation.
  Fix: Use a string value for the `indent` parameter, e.g., `indent=' '` for two spaces, or `indent='\t'` for tabs.
• gotcha Hjson allows omitting curly braces `{}` for the root object, similar to YAML, making configuration files simpler. However, this feature might not be universally supported by all third-party Hjson implementations.
  Fix: For maximum portability and compatibility across different Hjson parsers and tools, it is recommended to explicitly include the root braces in your Hjson files.
• gotcha The `hjson.dumpsJSON()` function, which converts Python objects to strict JSON, is noted in the documentation to be 'probably not as performant as the `simplejson` version'. If performance is critical for JSON output, consider using `json.dumps` from the standard `json` module or `simplejson.dumps` directly.
  Fix: For optimal performance when serializing to strict JSON, especially large data structures, consider using the `json` module from Python's standard library or `simplejson` directly instead of `hjson.dumpsJSON()`.

Install

• pip install hjson Install with pip

Imports

• hjson

  import hjson

• loads

  hjson.loads(hjson_string)

  Used for parsing Hjson strings into Python objects.
• dumps

  hjson.dumps(python_object)

  Used for converting Python objects into Hjson formatted strings.
• dumpsJSON

  hjson.dumpsJSON(python_object)

  Used for converting Python objects into strict JSON formatted strings (potentially less performant than `simplejson`'s equivalent).

Quickstart

Demonstrates how to parse Hjson strings into Python objects using `hjson.loads()` and how to serialize Python objects into Hjson or strict JSON strings using `hjson.dumps()` and `hjson.dumpsJSON()` respectively.

import hjson
import collections

# Decoding Hjson
hjson_text = '''
{
  foo: a # This is a comment
  bar: 1
  # Multiline string example
  description: '''
    This is a
    multiline string.
  '''
}
'''

# Parse Hjson string
data = hjson.loads(hjson_text)
print(f"Decoded Hjson: {data}")
assert data == collections.OrderedDict([
    ('foo', 'a'),
    ('bar', 1),
    ('description', 'This is a\nmultiline string.\n')
])

# Encoding Python object hierarchies to Hjson
python_obj = {'foo': 'text', 'bar': [1, 2], 'nested': {'key': 'value'}}
hjson_output = hjson.dumps(python_obj, indent=2)
print(f"\nEncoded Hjson:\n{hjson_output}")

# Encoding to strict JSON (note: may be less performant than simplejson)
json_output = hjson.dumpsJSON(python_obj, indent=2)
print(f"\nEncoded JSON:\n{json_output}")