Zig 0.17.0-dev (Split by item)

This is an example of documentation generated by ZigDoc, an alternative to Zig's built-in Auto Doc feature. See also examples in other modes/formats. The project being documented here (as the example) is the Zig library itself.

Templates

Maker.Templates
const Templates = struct

File

lib/compiler/Maker.zig:3602

Code

const Templates = struct {
    zig_lib_directory: Cache.Directory,
    dir: Io.Dir,
    buffer: std.array_list.Managed(u8),

    fn deinit(templates: *Templates, io: Io) void {
        templates.zig_lib_directory.handle.close(io);
        templates.dir.close(io);
        templates.buffer.deinit();
        templates.* = undefined;
    }

    fn write(
        templates: *Templates,
        arena: Allocator,
        io: Io,
        out_dir: Io.Dir,
        root_name: []const u8,
        template_path: []const u8,
        fingerprint: Package.Fingerprint,
    ) !void {
        if (Dir.path.dirname(template_path)) |dirname| {
            out_dir.createDirPath(io, dirname) catch |err| {
                fatal("unable to make path {q}: {t}", .{ dirname, err });
            };
        }

        const max_bytes = 10 * 1024 * 1024;
        const contents = templates.dir.readFileAlloc(io, template_path, arena, .limited(max_bytes)) catch |err| {
            fatal("unable to read template file {q}: {t}", .{ template_path, err });
        };
        templates.buffer.clearRetainingCapacity();
        try templates.buffer.ensureUnusedCapacity(contents.len);
        var i: usize = 0;
        while (i < contents.len) {
            if (contents[i] == '_' or contents[i] == '.') {
                // Both '_' and '.' are allowed because depending on the context
                // one prefix will be valid, while the other might not.
                if (std.mem.startsWith(u8, contents[i + 1 ..], "NAME")) {
                    try templates.buffer.appendSlice(root_name);
                    i += "_NAME".len;
                    continue;
                } else if (std.mem.startsWith(u8, contents[i + 1 ..], "FINGERPRINT")) {
                    try templates.buffer.print("0x{x}", .{fingerprint.int()});
                    i += "_FINGERPRINT".len;
                    continue;
                } else if (std.mem.startsWith(u8, contents[i + 1 ..], "ZIGVER")) {
                    try templates.buffer.appendSlice(builtin.zig_version_string);
                    i += "_ZIGVER".len;
                    continue;
                }
            }

            try templates.buffer.append(contents[i]);
            i += 1;
        }

        return out_dir.writeFile(io, .{
            .sub_path = template_path,
            .data = templates.buffer.items,
            .flags = .{ .exclusive = true },
        });
    }

    fn find(gpa: Allocator, io: Io, zig_lib_directory: Cache.Directory) Templates {
        const template_path: Path = .{
            .root_dir = zig_lib_directory,
            .sub_path = "init",
        };
        const template_dir = template_path.root_dir.handle.openDir(io, template_path.sub_path, .{}) catch |err|
            fatal("unable to open zig project template directory {f}: {t}", .{ template_path, err });
        return .{
            .zig_lib_directory = zig_lib_directory,
            .dir = template_dir,
            .buffer = std.array_list.Managed(u8).init(gpa),
        };
    }

    fn writeSimpleFile(io: Io, file_name: []const u8, comptime format: []const u8, args: anytype) !void {
        const f = try Io.Dir.cwd().createFile(io, file_name, .{ .exclusive = true });
        defer f.close(io);
        var buf: [4096]u8 = undefined;
        var fw = f.writer(io, &buf);
        try fw.interface.print(format, args);
        try fw.interface.flush();
    }
}