From 3b73a8edaff14039d917b1958715d1d54659851b Mon Sep 17 00:00:00 2001 From: Jimmi Holst Christensen Date: Wed, 7 Jan 2026 21:01:09 +0100 Subject: chore: Update examples in README to use new std.Io --- README.md | 77 +++++++++++++++++++++++++++++----------------- example/help.zig | 14 ++++----- example/simple-ex.zig | 11 ++++--- example/simple.zig | 12 +++++--- example/streaming-clap.zig | 12 +++++--- example/subcommands.zig | 12 +++----- example/usage.zig | 15 +++++---- 7 files changed, 88 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index d686f56..bbf1ea0 100644 --- a/README.md +++ b/README.md @@ -55,8 +55,12 @@ The simplest way to use this library is to just call the `clap.parse` function. ```zig pub fn main() !void { - var gpa = std.heap.DebugAllocator(.{}){}; - defer _ = gpa.deinit(); + var gpa_state = std.heap.DebugAllocator(.{}){}; + const gpa = gpa_state.allocator(); + defer _ = gpa_state.deinit(); + + var threaded: std.Io.Threaded = .init_single_threaded; + const io: std.Io = threaded.io(); // First we specify what parameters our program can take. // We can use `parseParamsComptime` to parse a string into an array of `Param(Help)`. @@ -70,14 +74,14 @@ pub fn main() !void { // Initialize our diagnostics, which can be used for reporting useful errors. // This is optional. You can also pass `.{}` to `clap.parse` if you don't - // care about the extra information `Diagnostic` provides. + // care about the extra information `Diagnostics` provides. var diag = clap.Diagnostic{}; var res = clap.parse(clap.Help, ¶ms, clap.parsers.default, .{ .diagnostic = &diag, - .allocator = gpa.allocator(), + .allocator = gpa, }) catch |err| { // Report useful error and exit. - try diag.reportToFile(.stderr(), err); + try diag.reportToFile(io, .stderr(), err); return err; }; defer res.deinit(); @@ -109,8 +113,12 @@ if you want some other mapping. ```zig pub fn main() !void { - var gpa = std.heap.DebugAllocator(.{}){}; - defer _ = gpa.deinit(); + var gpa_state = std.heap.DebugAllocator(.{}){}; + const gpa = gpa_state.allocator(); + defer _ = gpa_state.deinit(); + + var threaded: std.Io.Threaded = .init_single_threaded; + const io: std.Io = threaded.io(); // First we specify what parameters our program can take. // We can use `parseParamsComptime` to parse a string into an array of `Param(Help)`. @@ -136,12 +144,13 @@ pub fn main() !void { var diag = clap.Diagnostic{}; var res = clap.parse(clap.Help, ¶ms, parsers, .{ .diagnostic = &diag, - .allocator = gpa.allocator(), + .allocator = gpa, // The assignment separator can be configured. `--number=1` and `--number:1` is now // allowed. .assignment_separators = "=:", }) catch |err| { - try diag.reportToFile(.stderr(), err); + // Report useful error and exit. + try diag.reportToFile(io, .stderr(), err); return err; }; defer res.deinit(); @@ -194,6 +203,9 @@ pub fn main() !void { const gpa = gpa_state.allocator(); defer _ = gpa_state.deinit(); + var threaded: std.Io.Threaded = .init_single_threaded; + const io: std.Io = threaded.io(); + var iter = try std.process.ArgIterator.initWithAllocator(gpa); defer iter.deinit(); @@ -211,7 +223,7 @@ pub fn main() !void { // not fully consumed. It can then be reused to parse the arguments for subcommands. .terminating_positional = 0, }) catch |err| { - try diag.reportToFile(.stderr(), err); + try diag.reportToFile(io, .stderr(), err); return err; }; defer res.deinit(); @@ -222,11 +234,11 @@ pub fn main() !void { const command = res.positionals[0] orelse return error.MissingCommand; switch (command) { .help => std.debug.print("--help\n", .{}), - .math => try mathMain(gpa, &iter, res), + .math => try mathMain(io, gpa, &iter, res), } } -fn mathMain(gpa: std.mem.Allocator, iter: *std.process.ArgIterator, main_args: MainArgs) !void { +fn mathMain(io: std.Io, gpa: std.mem.Allocator, iter: *std.process.ArgIterator, main_args: MainArgs) !void { // The parent arguments are not used here, but there are cases where it might be useful, so // this example shows how to pass the arguments around. _ = main_args; @@ -247,7 +259,7 @@ fn mathMain(gpa: std.mem.Allocator, iter: *std.process.ArgIterator, main_args: M .diagnostic = &diag, .allocator = gpa, }) catch |err| { - try diag.reportToFile(.stderr(), err); + try diag.reportToFile(io, .stderr(), err); return err; // propagate error }; defer res.deinit(); @@ -273,7 +285,12 @@ The `streaming.Clap` is the base of all the other parsers. It's a streaming pars ```zig pub fn main() !void { - const allocator = std.heap.page_allocator; + var gpa_state = std.heap.DebugAllocator(.{}){}; + const gpa = gpa_state.allocator(); + defer _ = gpa_state.deinit(); + + var threaded: std.Io.Threaded = .init_single_threaded; + const io: std.Io = threaded.io(); // First we specify what parameters our program can take. const params = [_]clap.Param(u8){ @@ -289,7 +306,7 @@ pub fn main() !void { .{ .id = 'f', .takes_value = .one }, }; - var iter = try std.process.ArgIterator.initWithAllocator(allocator); + var iter = try std.process.ArgIterator.initWithAllocator(gpa); defer iter.deinit(); // Skip exe argument. @@ -308,7 +325,7 @@ pub fn main() !void { // Because we use a streaming parser, we have to consume each argument parsed individually. while (parser.next() catch |err| { // Report useful error and exit. - try diag.reportToFile(.stderr(), err); + try diag.reportToFile(io, .stderr(), err); return err; }) |arg| { // arg.param will point to the parameter which matched the argument. @@ -347,8 +364,12 @@ is passed to `help` to control how the help message is printed. ```zig pub fn main() !void { - var gpa = std.heap.DebugAllocator(.{}){}; - defer _ = gpa.deinit(); + var gpa_state = std.heap.DebugAllocator(.{}){}; + const gpa = gpa_state.allocator(); + defer _ = gpa_state.deinit(); + + var threaded: std.Io.Threaded = .init_single_threaded; + const io: std.Io = threaded.io(); const params = comptime clap.parseParamsComptime( \\-h, --help Display this help and exit. @@ -356,9 +377,7 @@ pub fn main() !void { \\ ); - var res = try clap.parse(clap.Help, ¶ms, clap.parsers.default, .{ - .allocator = gpa.allocator(), - }); + var res = try clap.parse(clap.Help, ¶ms, clap.parsers.default, .{ .allocator = gpa }); defer res.deinit(); // `clap.help` is a function that can print a simple help message. It can print any `Param` @@ -366,7 +385,7 @@ pub fn main() !void { // The last argument contains options as to how `help` should print those parameters. Using // `.{}` means the default options. if (res.args.help != 0) - return clap.helpToFile(.stderr(), clap.Help, ¶ms, .{}); + return clap.helpToFile(io, .stderr(), clap.Help, ¶ms, .{}); } const clap = @import("clap"); @@ -389,8 +408,12 @@ $ zig-out/bin/help --help ```zig pub fn main() !void { - var gpa = std.heap.DebugAllocator(.{}){}; - defer _ = gpa.deinit(); + var gpa_state = std.heap.DebugAllocator(.{}){}; + const gpa = gpa_state.allocator(); + defer _ = gpa_state.deinit(); + + var threaded: std.Io.Threaded = .init_single_threaded; + const io: std.Io = threaded.io(); const params = comptime clap.parseParamsComptime( \\-h, --help Display this help and exit. @@ -399,15 +422,13 @@ pub fn main() !void { \\ ); - var res = try clap.parse(clap.Help, ¶ms, clap.parsers.default, .{ - .allocator = gpa.allocator(), - }); + var res = try clap.parse(clap.Help, ¶ms, clap.parsers.default, .{ .allocator = gpa }); defer res.deinit(); // `clap.usageToFile` is a function that can print a simple usage string. It can print any // `Param` where `Id` has a `value` method (`Param(Help)` is one such parameter). if (res.args.help != 0) - return clap.usageToFile(.stdout(), clap.Help, ¶ms); + return clap.usageToFile(io, .stdout(), clap.Help, ¶ms); } const clap = @import("clap"); diff --git a/example/help.zig b/example/help.zig index a4379de..b07bc52 100644 --- a/example/help.zig +++ b/example/help.zig @@ -1,6 +1,10 @@ pub fn main() !void { - var gpa = std.heap.DebugAllocator(.{}){}; - defer _ = gpa.deinit(); + var gpa_state = std.heap.DebugAllocator(.{}){}; + const gpa = gpa_state.allocator(); + defer _ = gpa_state.deinit(); + + var threaded: std.Io.Threaded = .init_single_threaded; + const io: std.Io = threaded.io(); const params = comptime clap.parseParamsComptime( \\-h, --help Display this help and exit. @@ -8,13 +12,9 @@ pub fn main() !void { \\ ); - var res = try clap.parse(clap.Help, ¶ms, clap.parsers.default, .{ - .allocator = gpa.allocator(), - }); + var res = try clap.parse(clap.Help, ¶ms, clap.parsers.default, .{ .allocator = gpa }); defer res.deinit(); - var threaded: std.Io.Threaded = .init_single_threaded; - const io: std.Io = threaded.io(); // `clap.help` is a function that can print a simple help message. It can print any `Param` // where `Id` has a `description` and `value` method (`Param(Help)` is one such parameter). // The last argument contains options as to how `help` should print those parameters. Using diff --git a/example/simple-ex.zig b/example/simple-ex.zig index 7ab8d1e..f6a1c7f 100644 --- a/example/simple-ex.zig +++ b/example/simple-ex.zig @@ -1,6 +1,10 @@ pub fn main() !void { - var gpa = std.heap.DebugAllocator(.{}){}; - defer _ = gpa.deinit(); + var gpa_state = std.heap.DebugAllocator(.{}){}; + const gpa = gpa_state.allocator(); + defer _ = gpa_state.deinit(); + + var threaded: std.Io.Threaded = .init_single_threaded; + const io: std.Io = threaded.io(); // First we specify what parameters our program can take. // We can use `parseParamsComptime` to parse a string into an array of `Param(Help)`. @@ -23,9 +27,6 @@ pub fn main() !void { .ANSWER = clap.parsers.enumeration(YesNo), }; - var threaded: std.Io.Threaded = .init_single_threaded; - const io: std.Io = threaded.io(); - var diag = clap.Diagnostic{}; var res = clap.parse(clap.Help, ¶ms, parsers, .{ .diagnostic = &diag, diff --git a/example/simple.zig b/example/simple.zig index 67313aa..a7772c6 100644 --- a/example/simple.zig +++ b/example/simple.zig @@ -1,6 +1,10 @@ pub fn main() !void { - var gpa = std.heap.DebugAllocator(.{}){}; - defer _ = gpa.deinit(); + var gpa_state = std.heap.DebugAllocator(.{}){}; + const gpa = gpa_state.allocator(); + defer _ = gpa_state.deinit(); + + var threaded: std.Io.Threaded = .init_single_threaded; + const io: std.Io = threaded.io(); // First we specify what parameters our program can take. // We can use `parseParamsComptime` to parse a string into an array of `Param(Help)`. @@ -16,11 +20,9 @@ pub fn main() !void { // This is optional. You can also pass `.{}` to `clap.parse` if you don't // care about the extra information `Diagnostics` provides. var diag = clap.Diagnostic{}; - var threaded: std.Io.Threaded = .init_single_threaded; - const io: std.Io = threaded.io(); var res = clap.parse(clap.Help, ¶ms, clap.parsers.default, .{ .diagnostic = &diag, - .allocator = gpa.allocator(), + .allocator = gpa, }) catch |err| { // Report useful error and exit. try diag.reportToFile(io, .stderr(), err); diff --git a/example/streaming-clap.zig b/example/streaming-clap.zig index c58cd24..9d0a3ca 100644 --- a/example/streaming-clap.zig +++ b/example/streaming-clap.zig @@ -1,5 +1,10 @@ pub fn main() !void { - const allocator = std.heap.page_allocator; + var gpa_state = std.heap.DebugAllocator(.{}){}; + const gpa = gpa_state.allocator(); + defer _ = gpa_state.deinit(); + + var threaded: std.Io.Threaded = .init_single_threaded; + const io: std.Io = threaded.io(); // First we specify what parameters our program can take. const params = [_]clap.Param(u8){ @@ -15,7 +20,7 @@ pub fn main() !void { .{ .id = 'f', .takes_value = .one }, }; - var iter = try std.process.ArgIterator.initWithAllocator(allocator); + var iter = try std.process.ArgIterator.initWithAllocator(gpa); defer iter.deinit(); // Skip exe argument. @@ -31,9 +36,6 @@ pub fn main() !void { .diagnostic = &diag, }; - var threaded: std.Io.Threaded = .init_single_threaded; - const io: std.Io = threaded.io(); - // Because we use a streaming parser, we have to consume each argument parsed individually. while (parser.next() catch |err| { // Report useful error and exit. diff --git a/example/subcommands.zig b/example/subcommands.zig index 6eb919b..bd8625b 100644 --- a/example/subcommands.zig +++ b/example/subcommands.zig @@ -24,14 +24,14 @@ pub fn main() !void { const gpa = gpa_state.allocator(); defer _ = gpa_state.deinit(); + var threaded: std.Io.Threaded = .init_single_threaded; + const io: std.Io = threaded.io(); + var iter = try std.process.ArgIterator.initWithAllocator(gpa); defer iter.deinit(); _ = iter.next(); - var threaded: std.Io.Threaded = .init_single_threaded; - const io: std.Io = threaded.io(); - var diag = clap.Diagnostic{}; var res = clap.parseEx(clap.Help, &main_params, main_parsers, &iter, .{ .diagnostic = &diag, @@ -55,11 +55,11 @@ pub fn main() !void { const command = res.positionals[0] orelse return error.MissingCommand; switch (command) { .help => std.debug.print("--help\n", .{}), - .math => try mathMain(gpa, &iter, res), + .math => try mathMain(io, gpa, &iter, res), } } -fn mathMain(gpa: std.mem.Allocator, iter: *std.process.ArgIterator, main_args: MainArgs) !void { +fn mathMain(io: std.Io, gpa: std.mem.Allocator, iter: *std.process.ArgIterator, main_args: MainArgs) !void { // The parent arguments are not used here, but there are cases where it might be useful, so // this example shows how to pass the arguments around. _ = main_args; @@ -76,8 +76,6 @@ fn mathMain(gpa: std.mem.Allocator, iter: *std.process.ArgIterator, main_args: M // Here we pass the partially parsed argument iterator. var diag = clap.Diagnostic{}; - var threaded: std.Io.Threaded = .init_single_threaded; - const io: std.Io = threaded.io(); var res = clap.parseEx(clap.Help, ¶ms, clap.parsers.default, iter, .{ .diagnostic = &diag, .allocator = gpa, diff --git a/example/usage.zig b/example/usage.zig index c1440b9..2d51cc4 100644 --- a/example/usage.zig +++ b/example/usage.zig @@ -1,6 +1,10 @@ pub fn main() !void { - var gpa = std.heap.DebugAllocator(.{}){}; - defer _ = gpa.deinit(); + var gpa_state = std.heap.DebugAllocator(.{}){}; + const gpa = gpa_state.allocator(); + defer _ = gpa_state.deinit(); + + var threaded: std.Io.Threaded = .init_single_threaded; + const io: std.Io = threaded.io(); const params = comptime clap.parseParamsComptime( \\-h, --help Display this help and exit. @@ -9,14 +13,9 @@ pub fn main() !void { \\ ); - var res = try clap.parse(clap.Help, ¶ms, clap.parsers.default, .{ - .allocator = gpa.allocator(), - }); + var res = try clap.parse(clap.Help, ¶ms, clap.parsers.default, .{ .allocator = gpa }); defer res.deinit(); - var threaded: std.Io.Threaded = .init_single_threaded; - const io: std.Io = threaded.io(); - // `clap.usageToFile` is a function that can print a simple usage string. It can print any // `Param` where `Id` has a `value` method (`Param(Help)` is one such parameter). if (res.args.help != 0) -- cgit v1.2.3