{"id":22423349,"url":"https://github.com/prantlf/v-jany","last_synced_at":"2025-08-01T07:32:17.904Z","repository":{"id":172950602,"uuid":"650012721","full_name":"prantlf/v-jany","owner":"prantlf","description":"Build and access JSON/YAML data using a dynamic sumtype instead of static types.","archived":false,"fork":false,"pushed_at":"2024-11-16T02:59:14.000Z","size":50,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-16T03:26:43.109Z","etag":null,"topics":["any","json","vlang","vlang-package","yaml"],"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:30:26.000Z","updated_at":"2024-11-16T02:59:18.000Z","dependencies_parsed_at":"2024-01-01T23:53:08.335Z","dependency_job_id":"74edc17d-def9-4ec4-8547-92105d9923cc","html_url":"https://github.com/prantlf/v-jany","commit_stats":null,"previous_names":["prantlf/v-jsany"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fv-jany","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fv-jany/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fv-jany/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fv-jany/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prantlf","download_url":"https://codeload.github.com/prantlf/v-jany/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":["any","json","vlang","vlang-package","yaml"],"created_at":"2024-12-05T18:10:28.014Z","updated_at":"2025-08-01T07:32:17.885Z","avatar_url":"https://github.com/prantlf.png","language":"V","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Any Type for JSON and YAML\n\nBuild and access JSON/YAML data using a dynamic sumtype instead of static types.\n\n* Type `Any` accomodating all JSON types - `null`, `boolean`, `number`, `string`, `array` and `object`.\n* Strict extraction of values checking for the right return type.\n* Safe conversion of all numberic types (`u8`, `u16`, `u32`, `u64`, `i8`, `i16`, `int`, `i64` and `f32`) checking for arithmetic overflow.\n* Factory functions for creating JSON values.\n* Built-in formatting to `string` for easy logging.\n* Convenient traversing of nested values in arrays and objects.\n* Unmarshalling `Any` data to a static V type and marshalling a V value to `Any` data.\n\nUsed in [prantlf.json] and [prantlf.yaml] packages.\n\n**Attention**: If you dependened on the package `prantlf.jsany`, rename the dependency to `prantlf.jany`.\n\n## Synopsis\n\n```go\nimport prantlf.jany { Any, Null, any_int, marshal, MarshalOpts, unmarshal, UnmarshalOpts }\n\n// Create an Any\nany := any_int(42)  // factory function\nany := Any(f64(42)) // cast to sumtype\n\n// Checks for null\nif any is Null {}\nif any.is_null() {}\n\n// Get a value\nval := any.number()! // get a number (f64)\nval := any.int()!    // get an integer\n\n// Format a value to string\nstr := any.str()\n\n// Get a value on a path\nval := any.get('a.b[0]')!\n\n// Set a value on a path\nany.set('a.b[0]', any_int(42))!\n\n// Marshal a statically typed value to an Any\nstruct Config {\n\tanswer int\n}\nconfig := Config{ answer: 42 }\nany := marshal(config, MarshalOpts{})\n\n// Unmarshal an Any to a static type\nstruct Config {\n\tanswer int\n}\nany := Any({\n  'answer': Any(f64(42))\n})\nconfig := unmarshal[Config](any, UnmarshalOpts{})\n```\n\n## Installation\n\nYou can install this package either from [VPM] or from GitHub:\n\n```txt\nv install prantlf.jany\nv install --git https://github.com/prantlf/v-jany\n```\n\n## API\n\nThe type `Any` is a sumtype of the following built-in V types:\n\n```go\n// JSON types: null   boolean   number   string   array   object\npub type Any = Null | bool    | f64    | string | []Any | map[string]Any\n```\n\n### Null\n\nThe `null` is a special value in the `jany` namespace:\n\n```go\npub const null = Null{}\n```\n\n`Null` can be used to check the `null` value with the `is` operator. There's a convenience method `is_null()` too:\n\n```go\nif any is Null {}\nif any.is_null() {}\n```\n\n### Types\n\nBuilt-in V types are mapped to JSON types in the following way:\n\n| JSON type | V type           |\n|:----------|:-----------------|\n| `null`    | `Null`           |\n| `boolean` | `bool`           |\n| `number`  | `f64`            |\n| `string`  | `string`         |\n| `array`   | `[]Any`          |\n| `object`  | `map[string]Any` |\n\nThe native V type of an `Any` can be checked by the operator `is`:\n\n```go\nif any is string {}\n```\n\nThe name of the JSON type of an `Any` can be obtained as a string by the function `.typ()`:\n\n```go\ntyp := any.typ()\n```\n\n### Factories\n\nAn `Any` can be created by casting a native V value to the sumtype, or using a factory function exported from the `jany` namespace:\n\n| JSON type | V type           | Casting                   | Factory                   |\n|:----------|:-----------------|:--------------------------|:--------------------------|\n| `null`    | `Null`           | `Any(null)`               | `.any_null()`             |\n| `boolean` | `bool`           | `Any(true)`               | `.any_boolean(true)`      |\n| `number`  | `f64`            | `Any(f64(1))`             | `.any_number(1)`          |\n| `string`  | `string`         | `Any('a')`                | `.any_string('a')`        |\n| `array`   | `[]Any`          | `Any([Any(f64(1))])`      | `.any_array([1])`         |\n| `object`  | `map[string]Any` | `Any({'a': Any(f64(1))})` | `.any_object({ 'a': 1 })` |\n\n### Getters\n\nFor V types mapped from JSON types, there're getters. If the JSON value doesn't match the type of the getter, an error will be returned:\n\n| JSON type | V type           | Getter       |\n|:----------|:-----------------|:-------------|\n| `null`    | `Null`           | `.is_null()` |\n| `number`  | `f64`            | `.number()`  |\n| `boolean` | `bool`           | `.boolean()` |\n| `string`  | `string`         | `.string()`  |\n| `array`   | `[]Any`          | `.array()`  |\n| `object`  | `map[string]Any` | `.object()`  |\n\nExcept for the basic V types mapped from JSON types, there're additional getters for other numeric V types. If the JSON value doesn't match the type of the getter, or of the numeric type cannot accomodate the value and an arithmetic overflow would occur, an error will be returned:\n\n| JSON type | V type           | Getter       |\n|:----------|:-----------------|:-------------|\n| `number`  | `u8`             | `.u8()`      |\n| `number`  | `u16`            | `.u16()`     |\n| `number`  | `u32`            | `.u32()`     |\n| `number`  | `u64`            | `.u64()`     |\n| `number`  | `i8`             | `.i8()`      |\n| `number`  | `i16`            | `.i16()`     |\n| `number`  | `int`            | `.int()`     |\n| `number`  | `i64`            | `.i64()`     |\n| `number`  | `f32`            | `.f32()`     |\n\n### Formatting\n\nSerialisation of an `Any` to a string representation is expected from libraries providing the specific format, like JSON or YAML. The `Any` type provides only a simple serialisation to string for logging purposes - the getter `.str()`:\n\n```go\nstr := any.str()\n```\n\n### Traversing\n\nValues nested in arrays objects can be obtained by a convenience function using a string path - `.get(...)`. The syntax is the same as in the V langauge - arrays are accessed by `[usize]` and fields by `.`. Quotation marks (`\"` or `'`) can be used to specify field names with some of three special characters (`[`, `]` and `.`). If a value on any level of the the specifcfied path is missing, an error will be returned:\n\n```go\nval := any.get('a.b[0]')!\n```\n\nSimilarly to getting a nested value, a nested value can be set too. If the parent value on the path (the one but last value) is missing, an error will be returned. Arrays need to have the proper length before assigning values to them:\n\n```go\nany.set('a.b', Any([]Any{}))!\nany.set('a.b[0]', any_int(42))!\n```\n\nA new item can be added to an array too:\n\n```go\nany.add('a.b', any_int(42))!\n```\n\n### Marshalling\n\nExcept for using `Any` values directly, they can be converted to static V types and back again by functions exported from the `jany` namespace:\n\n### marshal[T](value T, opts \u0026MarshalOpts) !Any\n\nMarshals a value of `T` to `Any` 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\n```go\nstruct Config {\n\tanswer int\n}\n\nconfig := Config{ answer: 42 }\nany := marshal(config, MarshalOpts{})!\n```\n\n### unmarshal[T](any Any, 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| `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\nany := Any({\n  'answer': Any(f64(42))\n})\nconfig := unmarshal[Config](any, UnmarshalOpts{})!\n```\n\n### unmarshal_to[T](any Any, mut typ 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| `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\nany := Any({\n  'answer': Any(f64(42))\n})\nmut config := Config{}\nconfig := unmarshal_to(any, mut config, UnmarshalOpts{})!\n```\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.jany\n[prantlf.json]: https://github.com/prantlf/v-json\n[prantlf.yaml]: https://github.com/prantlf/v-yaml\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Fv-jany","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprantlf%2Fv-jany","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Fv-jany/lists"}