{"id":22423360,"url":"https://github.com/prantlf/v-json","last_synced_at":"2025-08-01T07:32:19.964Z","repository":{"id":172952421,"uuid":"650018135","full_name":"prantlf/v-json","owner":"prantlf","description":"Strictly parse and format JSON/JSONC/JSON5 data.","archived":false,"fork":false,"pushed_at":"2024-11-16T02:56:18.000Z","size":2892,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-16T03:26:22.304Z","etag":null,"topics":["json","json5","jsonc","parse","stringify","vlang","vlang-package"],"latest_commit_sha":null,"homepage":"","language":"V","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prantlf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-06T06:48:06.000Z","updated_at":"2024-11-16T02:56:22.000Z","dependencies_parsed_at":"2023-11-14T20:27:27.479Z","dependency_job_id":"af90a4ad-8e41-483a-afef-c16ad9cf98b8","html_url":"https://github.com/prantlf/v-json","commit_stats":null,"previous_names":["prantlf/v-json"],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fv-json","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fv-json/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fv-json/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fv-json/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prantlf","download_url":"https://codeload.github.com/prantlf/v-json/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228348371,"owners_count":17905899,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json","json5","jsonc","parse","stringify","vlang","vlang-package"],"created_at":"2024-12-05T18:10:36.296Z","updated_at":"2025-08-01T07:32:19.947Z","avatar_url":"https://github.com/prantlf.png","language":"V","readme":"# JSON Parser and Formatter\n\nStrictly parse and format [JSON]/[JSONC]/[JSON5] data.\n\n* Uses a [fast](#performance) recursive descent parser written in V.\n* Shows detailed [error messages](#errors) with location context.\n* Optionally supports [JSONC] - ignores single-line and multi-line JavaScript-style comments treating them as whitespace and also trailing commas in arrays ans objects.\n* Partially supports [JSON5] - allows single-quoted strings. (JSON5 is work in progress.)\n* Offers both condensed and prettified [JSON] output.\n* Works with the `Any` type suitable for safe handling of [JSON]/[YAML] data.\n* Supports statically typed data as well.\n\nUses [prantlf.jany]. See also the [prantlf.yaml] package and [jsonlint] and [yaml2json] tools.\n\n## Synopsis\n\n```go\nimport prantlf.json { parse, ParseOpts }\n\n// Prepare a JSON string\njson := '{\n  \"answer\": 42\n}'\n\n// Parse a data from the JSON string\nany := parse(json, ParseOpts{})\n```\n\n```go\nimport prantlf.jany { Any, any_int }\nimport prantlf.json { stringify, StringifyOpts }\n\n// Create a JSON data\nany := Any({\n  'answer': any_int(42)\n})\n\n// Format the data to a JSON string\nstr := stringify(any, StringifyOpts{})\n```\n\n```go\nimport prantlf.json { unmarshal, UnmarshalOpts }\n\n// Prepare a JSON string\njson := '{\n  \"answer\": 42\n}'\n\n// Declare a target object\nstruct Config {\n  answer int\n}\n\n// Parse an object from the JSON string\nconfig := unmarshal[Config](json, UnmarshalOpts{})\n```\n\n```go\nimport prantlf.json { stringify, MarshalOpts }\n\n// Declare a source object\nstruct Config {\n  answer int\n}\n\n// Assign a source object\nconfig := Config{\n  answer: 42\n}\n\n// Format the object to a JSON string\nstr := marshal(config, MarshalOpts{})\n```\n\n## Installation\n\nYou can install this package either from [VPM] or from GitHub:\n\n```txt\nv install prantlf.json\nv install --git https://github.com/prantlf/v-json\n```\n\nThe package with the type `Any` will be installed automatically. You can install it explicitly from [VPM] or from GitHub too:\n\n```txt\nv install prantlf.jany\nv install --git https://github.com/prantlf/v-jany\n```\n\n## API\n\nThe following functions are exported:\n\n### parse(input string, opts \u0026ParseOpts) !Any\n\nParses an `Any` value from a string in the JSON format. See [jany] for more information about the `Any` type. Fields available in `ParseOpts`:\n\n| Name                     | Type   | Default | Description |\n|:-------------------------|:-------|:--------|:------------|\n| `ignore_comments`        | `bool` | `false` | ignores single-line and multi-line JavaScript-style comments treating them as whitespace |\n| `ignore_trailing_commas` | `bool` | `false` | ignores commas behind the last item in an array or in an object             |\n| `allow_single_quotes`    | `bool` | `false` | allows single-quoted strings |\n\n```go\nany := parse(input, ParseOpts{})!\n```\n\n### stringify(any Any, opts \u0026StringifyOpts) string\n\nFormats an `Any` value to a string according to the JSON specification. See [jany] for more information about the `Any` type. Fields available in `StringifyOpts`:\n\n| Name              | Type   | Default | Description                                                           |\n|:------------------|:-------|:--------|:----------------------------------------------------------------------|\n| `pretty`          | `bool` | `false` | enables readable formatting using line breaks, spaces and indentation |\n| `trailing_commas` | `bool` | `false` | inserts commas behind the last item in an array or in an object       |\n| `single_quotes`   | `bool` | `false` | format single-quoted instead of double-quoted strings                 |\n| `escape_slashes`  | `bool` | `false` | escape slashes by prefixing them with a backslash (reverse solidus)   |\n| `escape_unicode`  | `bool` | `false` | escape multibyte Unicode characters with `\\u` literals                |\n\n```go\nstr := stringify(any, StringifyOpts{ pretty: true })\n```\n\n### marshal[T](value T, opts \u0026MarshalOpts) !string\n\nMarshals a value of `T` to a `string` value. Fields available in `MarshalOpts`:\n\n| Name              | Type   | Default | Description                                                           |\n|:------------------|:-------|:--------|:----------------------------------------------------------------------|\n| `enums_as_names`  | `bool` | `false` | stores `string` names of enum values instead of their `int` values    |\n| `pretty`          | `bool` | `false` | enables readable formatting using line breaks, spaces and indentation |\n| `trailing_commas` | `bool` | `false` | inserts commas behind the last item in an array or in an object       |\n| `single_quotes`   | `bool` | `false` | format single-quoted instead of double-quoted strings                 |\n| `escape_slashes`  | `bool` | `false` | escape slashes by prefixing them with a backslash (reverse solidus)   |\n| `escape_unicode`  | `bool` | `false` | escape multibyte Unicode characters with `\\u` literals                |\n\n```go\nstruct Config {\n\tanswer int\n}\n\nconfig := Config{ answer: 42 }\nstr := marshal(config, MarshalOpts{})!\n```\n\n### unmarshal[T](input string, opts \u0026UnmarshalOpts) !T\n\nUnmarshals an `Any` value to a new instance of `T`. Fields available in `UnmarshalOpts`:\n\n| Name                     | Type   | Default | Description                                                                              |\n|:-------------------------|:-------|:--------|:-----------------------------------------------------------------------------------------|\n| `ignore_comments`        | `bool` | `false` | ignores single-line and multi-line JavaScript-style comments treating them as whitespace |\n| `ignore_trailing_commas` | `bool` | `false` | ignores commas behind the last item in an array or in an object                          |\n| `allow_single_quotes`    | `bool` | `false` | allows single-quoted strings                                                             |\n| `require_all_fields`     | `bool` | `false` | requires a key in the source object for each field in the target struct                  |\n| `forbid_extra_keys`      | `bool` | `false` | forbids keys in the source object not mapping to a field in the target struct            |\n| `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 |\n| `ignore_number_overflow` | `bool` | `false` | allows losing precision when unmarshaling numbers to smaller numeric types               |\n\n```go\nstruct Config {\n\tanswer int\n}\n\njson := '{\n  \"answer\": 42\n}'\n\nconfig := unmarshal[Config](json, UnmarshalOpts{})!\n```\n\n### unmarshal_to[T](input string, mut obj T, opts \u0026UnmarshalOpts) !\n\nUnmarshals an `Any` value to an existing instance of `T`. Fields available in `UnmarshalOpts`:\n\n| Name                     | Type   | Default | Description                                                             |\n|:-------------------------|:-------|:--------|:------------------------------------------------------------------------|\n| `ignore_comments`        | `bool` | `false` | ignores single-line and multi-line JavaScript-style comments treating them as whitespace |\n| `ignore_trailing_commas` | `bool` | `false` | ignores commas behind the last item in an array or in an object             |\n| `allow_single_quotes`    | `bool` | `false` | allows single-quoted strings |\n| `require_all_fields`     | `bool` | `false` | requires a key in the source object for each field in the target struct |\n| `forbid_extra_keys`      | `bool` | `false` | forbids keys in the source object not mapping to a field in the target struct |\n| `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 |\n| `ignore_number_overflow` | `bool` | `false` | allows losing precision when unmarshaling numbers to smaller numeric types |\n\n```go\nstruct Config {\n\tanswer int\n}\n\njson := '{\n  \"answer\": 42\n}'\n\nmut config := Config{}\nconfig := unmarshal_to(json, mut config, UnmarshalOpts{})!\n```\n\n### escape(s string) string\n\nFormats a `string` value for being used in JSON strings by escaping sensitive characters by backslashes according to the JSON specification.\n\n```go\nstr := escape('...')!\n```\n\n### escape_opt(s string, opts \u0026EscapeOpts) string\n\nFormats a `string` value for being used in JSON strings by escaping sensitive characters by backslashes with options to customise the operation beyond the JSON specification. Fields available in `EscapeOpts`:\n\n| Name              | Type   | Default | Description                                                           |\n|:------------------|:-------|:--------|:----------------------------------------------------------------------|\n| `single_quotes`   | `bool` | `false` | escape single quotes, keep double quotes unescaped                    |\n| `escape_slashes`  | `bool` | `false` | escape slashes by prefixing them with a backslash (reverse solidus)   |\n| `escape_unicode`  | `bool` | `false` | escape multibyte Unicode characters with `\\u` literals                |\n\nBy default, double quotes are considered delimiters, which need escaping. This can be changed by setting `single_quotes` to `true`.\n\n```go\nstr := escape_opt('...', EscapeOpts{ escape_unicode: true })!\n```\n\n## Errors\n\nFor example, the following code:\n\n```go\nparse('42 // ultimate answer', ParseOpts{})\n```\n\nwill fail with the following message:\n\n    Unexpected \"/\" at the end of the parsed content on line 1, column 4:\n    1 | 42 // ultimate answer\n      |    ^\n\nThe message is formatted using the error fields, for example:\n\n    JsonError {\n      reason  string = 'Unexpected \"/\" at the end of the parsed content'\n      offset  int    = 3\n      line    int    = 1\n      column  int    = 3\n    }\n\n## Performance\n\nThis module is around 4x faster than `x.json2` when parsing:\n\n    ❯ ./parse_bench.vsh\n\n    SPENT  1130.785 ms in parsing condensed with x.json2\n    SPENT   282.204 ms in parsing condensed with prantlf.json\n    SPENT  1071.293 ms in parsing pretty with x.json2\n    SPENT   271.030 ms in parsing pretty with prantlf.json\n\nand almost 3x faster when stringifying:\n\n    ❯ ./stringify_bench.vsh\n\n    SPENT  1201.283 ms in stringifying condensed with x.json2\n    SPENT   439.548 ms in stringifying condensed with prantlf.json\n    SPENT  1307.802 ms in stringifying pretty with x.json2\n    SPENT   445.283 ms in stringifying pretty with prantlf.json\n\nand almost 4x faster when unmarshalling:\n\n    ❯ ./unmarshal_bench.vsh\n\n    SPENT   155.405 ms in unmarshalling condensed with json\n    SPENT  1184.805 ms in unmarshalling condensed with x.json2\n    SPENT   330.345 ms in unmarshalling condensed with prantlf.json\n    SPENT   153.020 ms in unmarshalling pretty with json\n    SPENT  1172.505 ms in unmarshalling pretty with x.json2\n    SPENT   304.557 ms in unmarshalling pretty with prantlf.json\n\nand more than 46x and in the pretty mode more than 68x faster when marshalling:\n\n    ❯ ./marshal_bench.vsh\n\n    SPENT    96.876 ms in marshalling condensed with json\n    SPENT   516.113 ms in marshalling condensed with x.json2\n    SPENT    11.678 ms in marshalling condensed with prantlf.json\n    SPENT    87.807 ms in marshalling pretty with json\n    SPENT  1027.831 ms in marshalling pretty with x.json2\n    SPENT    15.724 ms in marshalling pretty with prantlf.json\n\n## Contributing\n\nIn lieu of a formal styleguide, take care to maintain the existing coding style. Lint and test your code.\n\n## License\n\nCopyright (c) 2023-2025 Ferdinand Prantl\n\nLicensed under the MIT license.\n\n[VPM]: https://vpm.vlang.io/packages/prantlf.json\n[prantlf.jany]: https://github.com/prantlf/v-jany\n[prantlf.yaml]: https://github.com/prantlf/v-yaml\n[jsonlint]: https://github.com/prantlf/v-jsonlint\n[yaml2json]: https://github.com/prantlf/v-yaml2json\n[JSON]: https://www.json.org/\n[JSONC]: https://changelog.com/news/jsonc-is-a-superset-of-json-which-supports-comments-6LwR\n[JSON5]: https://spec.json5.org/\n[YAML]: https://yaml.org/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Fv-json","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprantlf%2Fv-json","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Fv-json/lists"}