https://github.com/r4gus/zon-rb
Zig Object Notation for Ruby
https://github.com/r4gus/zon-rb
gem ruby ruby-gem ruby-gems zig zig-object-notation ziglang zon
Last synced: 3 months ago
JSON representation
Zig Object Notation for Ruby
- Host: GitHub
- URL: https://github.com/r4gus/zon-rb
- Owner: r4gus
- License: mit
- Created: 2025-09-26T07:23:34.000Z (7 months ago)
- Default Branch: master
- Last Pushed: 2025-09-27T17:12:05.000Z (7 months ago)
- Last Synced: 2025-09-27T18:20:18.343Z (7 months ago)
- Topics: gem, ruby, ruby-gem, ruby-gems, zig, zig-object-notation, ziglang, zon
- Language: Ruby
- Homepage: https://rubygems.org/gems/zon-rb
- Size: 35.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Zig Object Notation (ZON) for Ruby
[](https://badge.fury.io/rb/zon-rb)
The [Zig](https://ziglang.org/) Object Notation (ZON) is a file format primarily used within the Zig ecosystem. For example, ZON is used for the Zig package [manifest](https://github.com/ziglang/zig/blob/b7ab62540963d80f68d0e9ee7ce18520fb173487/doc/build.zig.zon.md).
## Installation
Install the gem and add to the application's Gemfile by executing:
```bash
bundle add zon-rb
```
If bundler is not being used to manage dependencies, install the gem by executing:
```bash
gem install zon-rb
```
## Usage
To use this Gem you have to require it:
```ruby
require "zon"
```
To parse ZON data into a Ruby object, one can use the `Zon::parse` method. The method expects either a `String` or `IO` (`File`) object as its argument.
```irb
irb(main):001> Zon::parse(".{ \"foo\", \"bar\"}")
=> ["foo", "bar"]
irb(main):002> Zon.parse(File.open("../PassKeeZ/build.zig.zon"))
=>
{name: :passkeez,
version: "0.5.3",
minimum_zig_version: "0.15.1",
fingerprint: 15931082159778014966,
dependencies:
{keylib:
{url: "https://github.com/Zig-Sec/keylib/archive/refs/tags/0.7.0.tar.gz",
hash: "keylib-0.7.0-mbYjk6qaCQACutrMpyhgstSmYxSKmcuRmLI-CJSumBeA"},
uuid:
{url: "https://github.com/r4gus/uuid-zig/archive/refs/tags/0.4.0.tar.gz",
hash: "uuid-0.4.0-oOieIR2AAAChAUVBY4ABjYI1XN0EbVALmiN0JIlggC3i"},
kdbx: {path: "../kdbx"}},
paths: ["build.zig", "build.zig.zon", "linux", "README.md", "script", "src", "static"]}
```
To serialize a Ruby object into ZON, use the `Zon::serialize` method.
```irb
irb(main):002> o
=>
{name: :passkeez,
version: "0.5.3",
minimum_zig_version: "0.15.1",
fingerprint: 15931082159778014966,
dependencies:
{keylib: {url: "https://github.com/Zig-Sec/keylib/archive/refs/tags/0.7.0.tar.gz", hash: "keylib-0.7.0-mbYjk6qaCQACutrMpyhgstSmYxSKmcuRmLI-CJSumBeA"},
uuid: {url: "https://github.com/r4gus/uuid-zig/archive/refs/tags/0.4.0.tar.gz", hash: "uuid-0.4.0-oOieIR2AAAChAUVBY4ABjYI1XN0EbVALmiN0JIlggC3i"},
kdbx: {path: "../kdbx"}},
paths: ["build.zig", "build.zig.zon", "linux", "README.md", "script", "src", "static"]}
irb(main):013> puts(Zon::serialize(o, {:indent_level => 4}))
.{
.name = .passkeez,
.version = "0.5.3",
.minimum_zig_version = "0.15.1",
.fingerprint = 0xdd1692d15d21a6f6,
.dependencies = .{
.keylib = .{
.url = "https://github.com/Zig-Sec/keylib/archive/refs/tags/0.7.0.tar.gz",
.hash = "keylib-0.7.0-mbYjk6qaCQACutrMpyhgstSmYxSKmcuRmLI-CJSumBeA",
},
.uuid = .{
.url = "https://github.com/r4gus/uuid-zig/archive/refs/tags/0.4.0.tar.gz",
.hash = "uuid-0.4.0-oOieIR2AAAChAUVBY4ABjYI1XN0EbVALmiN0JIlggC3i",
},
.kdbx = .{
.path = "../kdbx",
},
},
.paths = .{
"build.zig",
"build.zig.zon",
"linux",
"README.md",
"script",
"src",
"static",
},
}
```
To customize the generated ZON data one can use the `:indent_level` and `:ibase` options. The `:indent_level` specifies how much each block is indented. The `:ibase` option can be used to define in which format (hex: 16, octal: 8, binary: 2, decimal: 10) an `Integer` should be serialized. The default for `:ibase` is `16` (hexadecimal).
```irb
irb(main):010> Zon::serialize(255, {:ibase => 2})
=> "0b11111111"
```
### Zig Manifest
`Zon::Zig::Manifest` provides you with an abstraction for your `build.zig.zon`. It will also validate your Zig package [manifest](https://github.com/ziglang/zig/blob/b7ab62540963d80f68d0e9ee7ce18520fb173487/doc/build.zig.zon.md) and raise an exception if one of the required fields is missing.
```ruby
o = Zon::parse(File.open("../PassKeeZ/build.zig.zon"))
manifest = Zon::Zig::Manifest.new o
# Use:
# manifest.name
# manifest.version
# ...
```
### Zig Package Hash
Given a path `pdir` that points to the root of a Zig package, one can calculate the packages hash using the `Zon::Hasher`:
```ruby
hasher = Zon::Zig::Hasher.new pdir
hasher.hash
# Hash with the format nnnn-vvvv-XXXX..XXXX
# e.g.: uuid-0.4.0-oOieIR2AAAChAUVBY4ABjYI1XN0EbVALmiN0JIlggC3i
result = hasher.result
```
## Development
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/r4gus/zon-rb.
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).