# zig-macaddress A small Zig library for parsing and formatting IEEE 802 MAC addresses. A `MacAddress` is a single `u48`, so it is cheap to copy, compare, sort, and store. Parsing accepts the common textual conventions; formatting can emit any of them in either case. Requires Zig 0.17.0 or later. For Zig 0.16, use the `zig-0.16` branch or the `v0.1.0` tag, which receive critical fixes only: ```console zig fetch --save git+https://git.jcollie.dev/jeff/zig-macaddress.git#v0.1.0 ``` The API documentation, generated from the doc comments in the source, is published at . ## Installation Fetch the package and save it to your `build.zig.zon`: ```console zig fetch --save git+https://git.jcollie.dev/jeff/zig-macaddress.git ``` Then wire the module into your build: ```zig const macaddress_dep = b.dependency("macaddress", .{ .target = target, .optimize = optimize, }); exe.root_module.addImport("macaddress", macaddress_dep.module("macaddress")); ``` ## Usage ```zig const std = @import("std"); const macaddress = @import("macaddress"); const MacAddress = macaddress.MacAddress; pub fn main() !void { const mac: MacAddress = try .parse("00:11:22:33:44:55"); // mac.data is a plain u48 std.debug.assert(mac.data == 0x001122334455); var buffer: [17]u8 = undefined; // Default formatting: upper case, colon separated. var w: std.Io.Writer = .fixed(&buffer); try w.print("{f}", .{mac}); std.debug.assert(std.mem.eql(u8, w.buffered(), "00:11:22:33:44:55")); // Or pick a style and case explicitly. var w2: std.Io.Writer = .fixed(&buffer); try mac.formatOptions(&w2, .{ .case = .lower, .style = .cisco }); std.debug.assert(std.mem.eql(u8, w2.buffered(), "0011.2233.4455")); } ``` ### Parsing `MacAddress.parse` (also re-exported as `macaddress.parse`) trims surrounding whitespace and then accepts exactly these layouts: | Input | Length | | ----------------- | ------ | | `001122334455` | 12 | | `0011.2233.4455` | 14 | | `00 11 22 33 44 55` | 17 | | `00:11:22:33:44:55` | 17 | | `00-11-22-33-44-55` | 17 | Hex digits may be upper or lower case, and the two cases may be mixed. Anything else — a wrong length, a stray character, a separator in the wrong place, or a separator that does not match the layout — returns `error.NotAMacAddress`. The separators in a 17-character address are checked individually, so mixed forms such as `00:11-22 33:44-55` are also accepted. ### Formatting `format` implements the standard `std.fmt` interface, so a `MacAddress` can be printed with `{f}`. It uses the defaults: upper case, colon separated. For anything else, call `formatOptions` with a `FormatOptions`: ```zig pub const FormatOptions = struct { case: Case = .upper, // .upper, .lower style: Style = .colons, }; ``` | `Style` | Output | | ---------------------------- | ------------------- | | `.compact` | `001122334455` | | `.cisco` | `0011.2233.4455` | | `.spaces` | `00 11 22 33 44 55` | | `.colons` | `00:11:22:33:44:55` | | `.hyphen`, `.dash`, `.minus` | `00-11-22-33-44-55` | `.hyphen`, `.dash`, and `.minus` are three names for the same output; pick whichever reads best where you use it. Every style produces at most 17 bytes, so a `[17]u8` is always a large enough buffer. ## Where this lives The canonical repository is on my Forgejo instance, mirrored to Codeberg and Tangled, and published on Radicle (see below): ```console git clone https://git.jcollie.dev/jeff/zig-macaddress.git git clone https://codeberg.org/jcollie/zig-macaddress.git ``` The Tangled mirror is at . ## Checking out the source with Radicle This repository is published on [Radicle](https://radicle.dev/), a peer-to-peer code forge built on git. Its Repository ID (RID) is: ``` rad:z3tH7LKeAUZWLmjbkkquzDxZ4Zjam ``` If you do not have Radicle yet, install it, create an identity, and start your node: ```console curl -sSf https://radicle.dev/install | sh rad auth rad node start ``` Then clone the repository: ```console rad clone rad:z3tH7LKeAUZWLmjbkkquzDxZ4Zjam ``` `rad clone` consults your node's routing table to find seeds that carry the repository, and drops the working copy into a `zig-macaddress` directory. Pass a target path as a second argument to put it somewhere else. If your node has not discovered a seed yet, name one directly with `--seed `. The result is an ordinary git working copy on the `main` branch, with a `rad` remote wired up, so everyday work is just git. To pull in changes published since your clone: ```console rad sync --fetch git pull rad main ``` ## Building and testing This package is a library only — it builds no executable, so `test` is the one interesting step: ```console zig build test ``` It has no dependencies of its own beyond the standard library. `zig build check` compiles everything without running it, which is how the documentation server is kept from quietly breaking — nothing else builds it. A Nix flake provides a development shell with the pinned Zig toolchain plus `reuse`, `pinact`, and `git-pages-cli`: ```console nix develop ``` ## Documentation Zig generates the API documentation from the doc comments, and this project keeps most of its explanation there, so it is worth reading rather than the source: ```console zig build docs # writes zig-out/docs zig build docs-serve # then open http://127.0.0.1:8000/ ``` It has to be served rather than opened as a file: the viewer fetches `sources.tar` and `main.wasm` at runtime, and a browser refuses both from a `file://` page. Pass `-Ddocs-port=N` to use a port other than 8000. Pushes to `main` publish the same bundle to . ## License MIT, except where noted otherwise. This repository follows the [REUSE](https://reuse.software/) specification: every file carries its own SPDX headers, and the full license texts live in `LICENSES/`.