HjsonSharp 1.0.0

HjsonSharp

A customisable streaming parser for HJSON, with support for JSON, JSONC and JSON5.

Features

• System.Text.Json integrated: Parse directly to System.Text.JsonElement.
• Token streaming: Parse one token at a time without loading the entire document into memory.
• Feature switches: Pick and choose your desired non-JSON features, with presets for HJSON, JSONC and JSON5.
• Unicode compatible: Compatible with UTF-8, UTF-16, UTF-32 and ASCII encodings.
• Incomplete inputs: Parse incomplete values, such as {"key": "val.
• Result pattern: Uses HjsonResult to avoid the overhead of exceptions.

Example

string Text = """
    {
        // use #, // or /**/ comments,
        // omit quotes for keys
        key: 1
        // omit quotes for strings
        contains: everything on this line
        // omit commas at the end of a line
        cool: {
          foo: 1
          bar: 2
        }
        // allow trailing commas
        list: [
          1,
          2,
        ]
        // and use multiline strings
        realist:
          '''
          My half empty glass,
          I will fill your empty half.
          Now you are half full.
          '''
    }
    """;

// Parse to JsonElement
JsonElement Element = HjsonReader.ParseElement(Text, HjsonReaderOptions.Hjson).Value;

// Serialize to JSON
string Json = JsonSerializer.Serialize(Element);

Specification Differences

Leading Whitespace In Triple Quoted Strings (HJSON)

Instead of counting leading whitespace preceding the opening quotes, HjsonSharp counts leading whitespace preceding the closing quotes.

See the open issue for more information.

For maximum portability, don't rely on significant leading whitespace in triple-quoted strings.

Carriage Returns (HJSON)

In the HJSON specification, carriage returns (\r) are ignored in favour of line feeds (\n). However, HjsonSharp allows \n, \r and \r\n.

This affects unquoted strings, which are terminated by a newline, and triple-quoted strings, which trim the first and last newlines.

For maximum portability, always use the line feed (\n) newline style in documents.

Escaped Newlines In Strings (HJSON)

The official HJSON specification does not include support for escaping newlines in strings like JSON5.

However, an open issue to add this was approved by a maintainer:

I no longer have any objections, implementing this for single or double quoted strings only should be fine. Not for multiline and not for quoteless strings. I would support PR:s for this, but we need PR:s for all major supported languages before changing the syntax documentation.

As such, HjsonSharp supports escaped newlines in single and double quoted strings by default.

For maximum portability, avoid escaping newlines in strings.

Benchmarks

For basic purposes, HjsonSharp has similar performance to hjson-cs: