// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! The parts of zig-uri that need Unicode character data: IDNA (UTS #46), //! Normalization Form C, and converting a `uri.Uri` between its URI and IRI //! forms. //! //! This is a module of its own, `uri_unicode`, beside the `uri` module rather //! than inside it, so that the URI parser itself depends on nothing but z46. //! This one imports `uri` and uucode, which generates its tables at build //! time. See the README for how to ask for it from a `build.zig`. //! //! ```zig //! const uri = @import("uri"); //! const uri_unicode = @import("uri_unicode"); //! //! const u = try uri.Uri.parse(alloc, "https://Bücher.example/"); //! defer u.deinit(); //! //! const ascii = try uri_unicode.toUri(alloc, u); //! defer ascii.deinit(); //! // ascii.host.?.hostname is "xn--bcher-kva.example" //! //! const name = try uri_unicode.idna.toAscii(alloc, "münchen.de", .{}); //! defer alloc.free(name); //! // name is "xn--mnchen-3ya.de" //! ``` //! //! Punycode needs no tables and so lives in `uri` as `uri.punycode`; so does //! the IRI text form, `.form = .iri` in the options `Uri.toText` takes, which //! only decides what to leave unescaped. What needs this module is turning an //! `xn--` host into Unicode and back. const std = @import("std"); const uri = @import("uri"); /// IDNA per UTS #46. pub const idna = @import("idna.zig"); /// Unicode Normalization Form C. pub const normalization = @import("normalization.zig"); const Allocator = std.mem.Allocator; const Uri = uri.Uri; /// What `toUri` and `toIri` can fail with: IDNA's errors, which include /// running out of memory. pub const Error = idna.Error; /// Convert to URI form: the host is IDNA-encoded to its ASCII `xn--` form, so /// that writing the result with the default `TextOptions` produces pure ASCII. /// /// Only the host changes. Everything else is stored decoded and is escaped on /// output, so `Uri.toText` already emits a conforming URI. An address literal /// is already ASCII and is copied unchanged. The result is owned by the /// caller. pub fn toUri(alloc: Allocator, u: Uri) Error!Uri { return convertHost(alloc, u, .to_ascii); } /// Convert to IRI form: an `xn--` host is decoded back to Unicode for display. /// Pair it with `.form = .iri` in `TextOptions` to keep the rest of the /// reference unescaped too. The result is owned by the caller. pub fn toIri(alloc: Allocator, u: Uri) Error!Uri { return convertHost(alloc, u, .to_unicode); } const HostConversion = enum { to_ascii, to_unicode }; fn convertHost(alloc: Allocator, u: Uri, dir: HostConversion) Error!Uri { // Only a registered name is convertible; address literals are already // ASCII and have no Unicode form. const name = switch (u.host orelse return u.clone(alloc)) { .hostname => |h| h, else => return u.clone(alloc), }; if (name.len == 0) return u.clone(alloc); const converted = switch (dir) { .to_ascii => try idna.toAscii(alloc, name, .{}), .to_unicode => try idna.toUnicode(alloc, name, .{}), }; defer alloc.free(converted); return u.replace(alloc, .{ .host = uri.Host{ .hostname = converted } }); } test { std.testing.refAllDecls(@This()); inline for (.{ idna, normalization }) |m| std.testing.refAllDecls(m); _ = @import("tests.zig"); }