{"id":16765311,"url":"https://github.com/lewisgaul/zig-nestedtext","last_synced_at":"2025-04-10T18:44:06.050Z","repository":{"id":44913920,"uuid":"342881934","full_name":"LewisGaul/zig-nestedtext","owner":"LewisGaul","description":"Zig NestedText parser library - a simple human readable data format based on YAML","archived":false,"fork":false,"pushed_at":"2024-09-29T21:24:18.000Z","size":140,"stargazers_count":13,"open_issues_count":8,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-05T11:46:03.402Z","etag":null,"topics":["nestedtext","parser","zig"],"latest_commit_sha":null,"homepage":"https://www.lewisgaul.co.uk/blog/coding/2021/04/18/zig-nestedtext/","language":"Zig","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/LewisGaul.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}},"created_at":"2021-02-27T14:56:00.000Z","updated_at":"2024-09-29T21:22:25.000Z","dependencies_parsed_at":"2023-01-20T02:00:23.870Z","dependency_job_id":null,"html_url":"https://github.com/LewisGaul/zig-nestedtext","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LewisGaul%2Fzig-nestedtext","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LewisGaul%2Fzig-nestedtext/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LewisGaul%2Fzig-nestedtext/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LewisGaul%2Fzig-nestedtext/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LewisGaul","download_url":"https://codeload.github.com/LewisGaul/zig-nestedtext/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248271921,"owners_count":21075800,"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":["nestedtext","parser","zig"],"created_at":"2024-10-13T05:42:21.553Z","updated_at":"2025-04-10T18:44:06.027Z","avatar_url":"https://github.com/LewisGaul.png","language":"Zig","readme":"# zig-nestedtext\n\n[![Build badge](https://img.shields.io/github/actions/workflow/status/LewisGaul/zig-nestedtext/tests.yml?branch=main)](https://github.com/LewisGaul/zig-nestedtext/actions/workflows/tests.yml?query=branch%3Amain)\n[![Release badge](https://img.shields.io/github/v/release/LewisGaul/zig-nestedtext?include_prereleases\u0026sort=semver)](https://github.com/LewisGaul/zig-nestedtext/releases/)\n\n\nA NestedText parser written in Zig 0.13 targeting [NestedText v2.0](https://nestedtext.org/en/v2.0/) (note [Deviations From Specification](#deviations-from-specification) below).\n\nSee my [Zig NestedText Library blog post](https://www.lewisgaul.co.uk/blog/coding/2021/04/18/zig-nestedtext/).\n\n\n## Usage\n\nThere are a few options for making use of this project:\n - Download from the [releases page](https://github.com/LewisGaul/zig-nestedtext/releases/)\n - Include as a dependency via git submodules\n - Clone and build manually, using a static copy of the built artefacts\n - Use the gyro package manager (untested)\n - Use the zigmod package manager (untested)\n\nThe Zig library has no external dependencies.\n\nThe CLI tool depends only on `Clap` for command line arg parsing (included as a git submodule under `deps/`).\n\nRun `zig build` to build the static library `libnestedtext.a` under `zig-out/lib/`, which can then be linked with your program.\n\n\n### CLI Tool\n\nAn executable CLI program `nt-cli` is included for exposing the core functionality of the project. When building with `zig build` this can be found under `zig-out/bin/`.\n\nThis tool can be used to convert between NestedText and JSON, for example:  \n```\n$./zig-out/bin/nt-cli -f samples/employees.nt\ndebug(cli):     +0 Starting up\ndebug(cli):     +0 Parsed args\ndebug(cli):     +1 Finished reading input\ndebug(cli):     +1 Parsed NestedText\ndebug(cli):     +1 Converted to JSON\ndebug(cli):     +1 Stringified JSON\n{\"president\":{\"name\":\"Katheryn McDaniel\",\"address\":\"138 Almond Street\\nTopeka, Kansas 20697\",\"phone\":{\"cell\":\"1-210-555-5297\",\"home\":\"1-210-555-8470\"},\"email\":\"KateMcD@aol.com\",\"additional-roles\":[\"board member\"]},\"vice-president\":{\"name\":\"Margaret Hodge\",\"address\":\"2586 Marigold Lane\\nTopeka, Kansas 20682\",\"phone\":\"1-470-555-0398\",\"email\":\"margaret.hodge@ku.edu\",\"additional-roles\":[\"new membership task force\",\"accounting task force\"]},\"treasurer\":[{\"name\":\"Fumiko Purvis\",\"address\":\"3636 Buffalo Ave\\nTopeka, Kansas 20692\",\"phone\":\"1-268-555-0280\",\"email\":\"fumiko.purvis@hotmail.com\",\"additional-roles\":[\"accounting task force\"]},{\"name\":\"Merrill Eldridge\",\"phone\":\"1-268-555-3602\",\"email\":\"merrill.eldridge@yahoo.com\"}]}\ndebug(cli):     +1 Exiting with: 0\n```\n\nYes, that took around 1 millisecond ;)\n\nAnd back to NestedText:\n```\n$./zig-out/bin/nt-cli -f samples/employees.nt | ./zig-out/bin/nt-cli -F json -O nt\npresident:\n  name: Katheryn McDaniel\n  address:\n    \u003e 138 Almond Street\n    \u003e Topeka, Kansas 20697\n  phone:\n    cell: 1-210-555-5297\n    home: 1-210-555-8470\n  email: KateMcD@aol.com\n  additional-roles:\n    - board member\nvice-president:\n  name: Margaret Hodge\n  address:\n    \u003e 2586 Marigold Lane\n    \u003e Topeka, Kansas 20682\n  phone: 1-470-555-0398\n  email: margaret.hodge@ku.edu\n  additional-roles:\n    - new membership task force\n    - accounting task force\ntreasurer:\n  -\n    name: Fumiko Purvis\n    address:\n      \u003e 3636 Buffalo Ave\n      \u003e Topeka, Kansas 20692\n    phone: 1-268-555-0280\n    email: fumiko.purvis@hotmail.com\n    additional-roles:\n      - accounting task force\n  -\n    name: Merrill Eldridge\n    phone: 1-268-555-3602\n    email: merrill.eldridge@yahoo.com\n```\n\n\n## Deviations From Specification\n\nThe amount of deviation from the official NestedText spec is kept to a minimum, however there is one minor case to be aware of (as reflected in the [fork of the official testsuite](https://github.com/KenKundert/nestedtext_tests/compare/master...LewisGaul:dev) being used to test this project). Where possible these issues are resolved upstream.\n\nNote that this project implements a *strict subset* of the official spec, to avoid compatibility issues.\n\n\n### Empty Values in Flow-style\n\nEmpty values are officially allowed in flow-style NestedText, e.g. `{:}` -\u003e `{\"\":\"\"}`, however this is *disallowed* by this project.\n\nThe design choices behind handling for empty values in flow-style are explained in detail at \u003chttps://zigforum.org/t/zig-nestedtext-release-0-1-0/383/5\u003e.\n\nThis has been discussed with the NestedText creators in GitHub issues ([here](https://github.com/KenKundert/nestedtext/issues/23#issuecomment-831195971) and [here](https://github.com/KenKundert/nestedtext/issues/25#issuecomment-860185422)) and over email, and discussions are ongoing.\n\nTo summarise the rationale behind this deviation:\n - Flow-style is only provided as a shorthand (and a way to represent empty lists/objects), so can be as strict as desired without preventing representation of arbitrary data.\n - The spec says that `[,]` -\u003e `[\"\"]`, `[,,]` -\u003e `[\"\", \"\"]` etc., where the trailing comma is required to indicate an empty value at the end of the list.\n - There is no other use for trailing commas in NestedText since flow-style cannot span multiple lines.\n - At first glance, `[,]` looks more like a list of *two* empty values than one.\n - The language states one of its primary goals as being \"*easily understood and used by both programmers and non-programmers*\".\n - On balance, the author of this project has decided that the potential confusion from the use of trailing commas to indicate empty values is not worth the convenience it brings to more experienced users.\n\nIf you have any thoughts about this either way, please consider posting a comment to \u003chttps://github.com/LewisGaul/zig-nestedtext/issues/17\u003e.\n\n### Line Endings Preserved\n\nWhen a string contains newlines, those newlines are preserved from the NestedText content itself.\nWithout this, it is impossible to represent carriage return and newline characters in a platform-independent, implementation-independent way.\n\nThis has been discussed at \u003chttps://github.com/KenKundert/nestedtext_tests/issues/5\u003e.\n\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md).\n\n\n## Development\n\nBuild with `zig build` - the library will be under `zig-out/lib/` and the CLI tool will be under `zig-out/bin/`.\n\nRun the tests with `zig build test`.\n\nPlease feel free to propose changes via a PR, but please make sure all tests are passing, and also make sure to run `zig fmt .` (there are GitHub actions checks for both of these).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flewisgaul%2Fzig-nestedtext","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flewisgaul%2Fzig-nestedtext","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flewisgaul%2Fzig-nestedtext/lists"}