JSON Parser and Formatter

Strictly parse and format JSON / JSONC / JSON5 data.

Uses a fast recursive descent parser written in V.
Shows detailed error messages with location context.
Optionally supports JSONC - ignores single-line and multi-line JavaScript-style comments treating them as whitespace and also trailing commas in arrays ans objects.
Partially supports JSON5 - allows single-quoted strings. (JSON5 is work in progress.)
Offers both condensed and prettified JSON output.
Works with the Any type suitable for safe handling of JSON / YAML data.
Supports statically typed data as well.

Uses prantlf.jany . See also the prantlf.yaml package and jsonlint and yaml2json tools.

Synopsis

import prantlf.json { parse, ParseOpts }

// Prepare a JSON string
json := '{
  "answer": 42
}'

// Parse a data from the JSON string
any := parse(json, ParseOpts{})

import prantlf.jany { Any, any_int }
import prantlf.json { stringify, StringifyOpts }

// Create a JSON data
any := Any({
  'answer': any_int(42)
})

// Format the data to a JSON string
str := stringify(any, StringifyOpts{})

import prantlf.json { unmarshal, UnmarshalOpts }

// Prepare a JSON string
json := '{
  "answer": 42
}'

// Declare a target object
struct Config {
  answer int
}

// Parse an object from the JSON string
config := unmarshal[Config](json, UnmarshalOpts{})

import prantlf.json { stringify, MarshalOpts }

// Declare a source object
struct Config {
  answer int
}

// Assign a source object
config := Config{
  answer: 42
}

// Format the object to a JSON string
str := marshal(config, MarshalOpts{})

Installation

You can install this package either from VPM or from GitHub:

v install prantlf.json
v install --git https://github.com/prantlf/v-json

The package with the type Any will be installed automatically. You can install it explicitly from VPM or from GitHub too:

v install prantlf.jany
v install --git https://github.com/prantlf/v-jany

API

The following functions are exported:

parse(input string, opts &ParseOpts) !Any

Parses an Any value from a string in the JSON format. See [jany] for more information about the Any type. Fields available in ParseOpts :

Name	Type	Default	Description
`ignore_comments`	`bool`	`false`	ignores single-line and multi-line JavaScript-style comments treating them as whitespace
`ignore_trailing_commas`	`bool`	`false`	ignores commas behind the last item in an array or in an object
`allow_single_quotes`	`bool`	`false`	allows single-quoted strings

any := parse(input, ParseOpts{})!

stringify(any Any, opts &StringifyOpts) !string

Formats an Any value to a string according to the JSON specification. See [jany] for more information about the Any type. Fields available in StringifyOpts :

Name	Type	Default	Description
`pretty`	`bool`	`false`	enables readable formatting using line breaks, spaces and indentation
`trailing_commas`	`bool`	`false`	inserts commas behind the last item in an array or in an object
`single_quotes`	`bool`	`false`	format single-quoted instead of double-quoted strings
`escape_slashes`	`bool`	`false`	escape slashes by prefixing them with a backslash (reverse solidus)
`escape_unicode`	`bool`	`false`	escape multibyte Unicode characters with `\u` literals

str := stringify(any, StringifyOpts{ pretty: true })!

marshal[T](value T, opts &MarshalOpts) !string

Marshals a value of T to a string value. Fields available in MarshalOpts :

Name	Type	Default	Description
`enums_as_names`	`bool`	`false`	stores `string` names of enum values instead of their `int` values
`pretty`	`bool`	`false`	enables readable formatting using line breaks, spaces and indentation
`trailing_commas`	`bool`	`false`	inserts commas behind the last item in an array or in an object
`single_quotes`	`bool`	`false`	format single-quoted instead of double-quoted strings
`escape_slashes`	`bool`	`false`	escape slashes by prefixing them with a backslash (reverse solidus)
`escape_unicode`	`bool`	`false`	escape multibyte Unicode characters with `\u` literals

struct Config {
    answer int
}

config := Config{ answer: 42 }
str := marshal(config, MarshalOpts{})!

unmarshal[T](input string, opts &UnmarshalOpts) !T

Unmarshals an Any value to a new instance of T . Fields available in UnmarshalOpts :

Name	Type	Default	Description
`ignore_comments`	`bool`	`false`	ignores single-line and multi-line JavaScript-style comments treating them as whitespace
`ignore_trailing_commas`	`bool`	`false`	ignores commas behind the last item in an array or in an object
`allow_single_quotes`	`bool`	`false`	allows single-quoted strings
`require_all_fields`	`bool`	`false`	requires a key in the source object for each field in the target struct
`forbid_extra_keys`	`bool`	`false`	forbids keys in the source object not mapping to a field in the target struct
`cast_null_to_default`	`bool`	`false`	allows `null` s in the source data to be translated to default values of V types; `null` s can be unmarshaled only to Option types by default
`ignore_number_overflow`	`bool`	`false`	allows losing precision when unmarshaling numbers to smaller numeric types

struct Config {
    answer int
}

json := '{
  "answer": 42
}'

config := unmarshal[Config](json, UnmarshalOpts{})!

unmarshal_to[T](input string, mut obj T, opts &UnmarshalOpts) !

Unmarshals an Any value to an existing instance of T . Fields available in UnmarshalOpts :

Name	Type	Default	Description
`ignore_comments`	`bool`	`false`	ignores single-line and multi-line JavaScript-style comments treating them as whitespace
`ignore_trailing_commas`	`bool`	`false`	ignores commas behind the last item in an array or in an object
`allow_single_quotes`	`bool`	`false`	allows single-quoted strings
`require_all_fields`	`bool`	`false`	requires a key in the source object for each field in the target struct
`forbid_extra_keys`	`bool`	`false`	forbids keys in the source object not mapping to a field in the target struct
`cast_null_to_default`	`bool`	`false`	allows `null` s in the source data to be translated to default values of V types; `null` s can be unmarshaled only to Option types by default
`ignore_number_overflow`	`bool`	`false`	allows losing precision when unmarshaling numbers to smaller numeric types

struct Config {
    answer int
}

json := '{
  "answer": 42
}'

mut config := Config{}
config := unmarshal_to(json, mut config, UnmarshalOpts{})!

Errors

For example, the following code:

parse('42 // ultimate answer', ParseOpts{})

will fail with the following message:

Unexpected "/" at the end of the parsed content on line 1, column 4:
1 | 42 // ultimate answer
  |    ^

The message is formatted using the error fields, for example:

JsonError {
  reason  string = 'Unexpected "/" at the end of the parsed content'
  offset  int    = 3
  line    int    = 1
  column  int    = 3
}

Performance

This module is almost 3.8x faster than x.json2 when parsing:

❯ ./parse_bench.vsh

SPENT  1082.011 ms in parsing condensed with x.json2
SPENT   283.197 ms in parsing condensed with prantlf.json
SPENT  1047.946 ms in parsing pretty with x.json2
SPENT   284.696 ms in parsing pretty with prantlf.json

and almost 3.5x faster when stringifying:

❯ ./stringify_bench.vsh

SPENT  1271.921 ms in stringifying condensed with x.json2
SPENT   380.261 ms in stringifying condensed with prantlf.json
SPENT  1386.552 ms in stringifying pretty with x.json2
SPENT   398.728 ms in stringifying pretty with prantlf.json

TODO

This is a work in progress.

Support replacer for stringify and marshal and reviver for parse and unmarshal .
Finish the JSON5 support.
Help fixing a bug in V - generics doesn't support nested structs.