From aa334d8c1df252f48960e0253eb25544678a6023 Mon Sep 17 00:00:00 2001 From: Komari Spaghetti Date: Mon, 26 Apr 2021 16:23:15 +0200 Subject: Refactor Diagnostic (and others) into a ParseOption struct This allows for default arguments, which we can also extend without breaking peoples code in the future. This is a breaking change right now though. --- README.md | 26 ++++++++++++-------------- clap.zig | 36 ++++++++++++++++++++++++++---------- clap/comptime.zig | 19 ++++++++----------- clap/streaming.zig | 40 +++++++++++++++++++++------------------- example/simple-ex.zig | 14 ++++++++------ example/simple.zig | 11 +++++------ example/streaming-clap.zig | 15 +++++++-------- 7 files changed, 87 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index 3156539..ad9f026 100644 --- a/README.md +++ b/README.md @@ -25,8 +25,8 @@ into master on every `zig` release. The simplest way to use this library is to just call the `clap.parse` function. ```zig -const std = @import("std"); const clap = @import("clap"); +const std = @import("std"); const debug = std.debug; @@ -41,11 +41,10 @@ pub fn main() !void { }; // Initalize our diagnostics, which can be used for reporting useful errors. - // This is optional. You can also just pass `null` to `parser.next` if you - // don't care about the extra information `Diagnostics` provides. - var diag: clap.Diagnostic = undefined; - - var args = clap.parse(clap.Help, ¶ms, std.heap.page_allocator, &diag) catch |err| { + // 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 args = clap.parse(clap.Help, ¶ms, .{ .diagnostic = &diag }) catch |err| { // Report useful error and exit diag.report(std.io.getStdErr().outStream(), err) catch {}; return err; @@ -107,8 +106,8 @@ The `StreamingClap` is the base of all the other parsers. It's a streaming parse `args.Iterator` to provide it with arguments lazily. ```zig -const std = @import("std"); const clap = @import("clap"); +const std = @import("std"); const debug = std.debug; @@ -137,19 +136,18 @@ pub fn main() !void { var iter = try clap.args.OsIterator.init(allocator); defer iter.deinit(); - // Initialize our streaming parser. + // Initalize our diagnostics, which can be used for reporting useful errors. + // This is optional. You can also leave the `diagnostic` field unset if you + // don't care about the extra information `Diagnostic` provides. + var diag = clap.Diagnostic{}; var parser = clap.StreamingClap(u8, clap.args.OsIterator){ .params = ¶ms, .iter = &iter, + .diagnostic = &diag, }; - // Initalize our diagnostics, which can be used for reporting useful errors. - // This is optional. You can also just pass `null` to `parser.next` if you - // don't care about the extra information `Diagnostics` provides. - var diag: clap.Diagnostic = undefined; - // Because we use a streaming parser, we have to consume each argument parsed individually. - while (parser.next(&diag) catch |err| { + while (parser.next() catch |err| { // Report useful error and exit diag.report(std.io.getStdErr().outStream(), err) catch {}; return err; diff --git a/clap.zig b/clap.zig index 4548a48..b31cd1d 100644 --- a/clap.zig +++ b/clap.zig @@ -1,6 +1,7 @@ const std = @import("std"); const debug = std.debug; +const heap = std.heap; const io = std.io; const mem = std.mem; const testing = std.testing; @@ -307,7 +308,6 @@ pub fn Args(comptime Id: type, comptime params: []const Param(Id)) type { exe_arg: ?[]const u8, pub fn deinit(a: *@This()) void { - a.clap.deinit(); a.arena.deinit(); } @@ -329,20 +329,37 @@ pub fn Args(comptime Id: type, comptime params: []const Param(Id)) type { }; } +/// Options that can be set to customize the behavior of parsing. +pub const ParseOptions = struct { + /// The allocator used for all memory allocations. Defaults to the `heap.page_allocator`. + /// Note: You should probably override this allocator if you are calling `parseEx`. Unlike + /// `parse`, `parseEx` does not wrap the allocator so the heap allocator can be + /// quite expensive. (TODO: Can we pick a better default? For `parse`, this allocator + /// is fine, as it wraps it in an arena) + allocator: *mem.Allocator = heap.page_allocator, + diagnostic: ?*Diagnostic = null, +}; + /// Same as `parseEx` but uses the `args.OsIterator` by default. pub fn parse( comptime Id: type, comptime params: []const Param(Id), - allocator: *mem.Allocator, - diag: ?*Diagnostic, + opt: ParseOptions, ) !Args(Id, params) { - var iter = try args.OsIterator.init(allocator); - const clap = try parseEx(Id, params, allocator, &iter, diag); - return Args(Id, params){ + var iter = try args.OsIterator.init(opt.allocator); + var res = Args(Id, params){ .arena = iter.arena, - .clap = clap, .exe_arg = iter.exe_arg, + .clap = undefined, }; + + // Let's reuse the arena from the `OSIterator` since we already have + // it. + res.clap = try parseEx(Id, params, &iter, .{ + .allocator = &res.arena.allocator, + .diagnostic = opt.diagnostic, + }); + return res; } /// Parses the command line arguments passed into the program based on an @@ -350,12 +367,11 @@ pub fn parse( pub fn parseEx( comptime Id: type, comptime params: []const Param(Id), - allocator: *mem.Allocator, iter: anytype, - diag: ?*Diagnostic, + opt: ParseOptions, ) !ComptimeClap(Id, params) { const Clap = ComptimeClap(Id, params); - return try Clap.parse(allocator, iter, diag); + return try Clap.parse(iter, opt); } /// Will print a help message in the following format: diff --git a/clap/comptime.zig b/clap/comptime.zig index 8ab61cb..9bec38e 100644 --- a/clap/comptime.zig +++ b/clap/comptime.zig @@ -1,10 +1,10 @@ const clap = @import("../clap.zig"); const std = @import("std"); -const testing = std.testing; +const debug = std.debug; const heap = std.heap; const mem = std.mem; -const debug = std.debug; +const testing = std.testing; /// Deprecated: Use `parseEx` instead pub fn ComptimeClap( @@ -42,7 +42,8 @@ pub fn ComptimeClap( pos: []const []const u8, allocator: *mem.Allocator, - pub fn parse(allocator: *mem.Allocator, iter: anytype, diag: ?*clap.Diagnostic) !@This() { + pub fn parse(iter: anytype, opt: clap.ParseOptions) !@This() { + const allocator = opt.allocator; var multis = [_]std.ArrayList([]const u8){undefined} ** multi_options; for (multis) |*multi| { multi.* = std.ArrayList([]const u8).init(allocator); @@ -62,7 +63,7 @@ pub fn ComptimeClap( .params = converted_params, .iter = iter, }; - while (try stream.next(diag)) |arg| { + while (try stream.next()) |arg| { const param = arg.param; if (param.names.long == null and param.names.short == null) { try pos.append(arg.value.?); @@ -81,19 +82,17 @@ pub fn ComptimeClap( } } - for (multis) |*multi, i| { + for (multis) |*multi, i| res.multi_options[i] = multi.toOwnedSlice(); - } res.pos = pos.toOwnedSlice(); return res; } - pub fn deinit(parser: *@This()) void { + pub fn deinit(parser: @This()) void { for (parser.multi_options) |o| parser.allocator.free(o); parser.allocator.free(parser.pos); - parser.* = undefined; } pub fn flag(parser: @This(), comptime name: []const u8) bool { @@ -155,14 +154,12 @@ test "" { clap.parseParam("

") catch unreachable, }); - var buf: [1024]u8 = undefined; - var fb_allocator = heap.FixedBufferAllocator.init(buf[0..]); var iter = clap.args.SliceIterator{ .args = &[_][]const u8{ "-a", "-c", "0", "something", "-d", "a", "--dd", "b", }, }; - var args = try Clap.parse(&fb_allocator.allocator, &iter, null); + var args = try Clap.parse(&iter, .{ .allocator = testing.allocator }); defer args.deinit(); testing.expect(args.flag("-a")); diff --git a/clap/streaming.zig b/clap/streaming.zig index 11145f0..8030a67 100644 --- a/clap/streaming.zig +++ b/clap/streaming.zig @@ -40,12 +40,13 @@ pub fn StreamingClap(comptime Id: type, comptime ArgIterator: type) type { iter: *ArgIterator, state: State = .normal, positional: ?*const clap.Param(Id) = null, + diagnostic: ?*clap.Diagnostic = null, /// Get the next Arg that matches a Param. - pub fn next(parser: *@This(), diag: ?*clap.Diagnostic) !?Arg(Id) { + pub fn next(parser: *@This()) !?Arg(Id) { switch (parser.state) { - .normal => return try parser.normal(diag), - .chaining => |state| return try parser.chainging(state, diag), + .normal => return try parser.normal(), + .chaining => |state| return try parser.chainging(state), .rest_are_positional => { const param = parser.positionalParam() orelse unreachable; const value = (try parser.iter.next()) orelse return null; @@ -54,7 +55,7 @@ pub fn StreamingClap(comptime Id: type, comptime ArgIterator: type) type { } } - fn normal(parser: *@This(), diag: ?*clap.Diagnostic) !?Arg(Id) { + fn normal(parser: *@This()) !?Arg(Id) { const arg_info = (try parser.parseNextArg()) orelse return null; const arg = arg_info.arg; switch (arg_info.kind) { @@ -70,7 +71,7 @@ pub fn StreamingClap(comptime Id: type, comptime ArgIterator: type) type { continue; if (param.takes_value == .None) { if (maybe_value != null) - return err(diag, arg, .{ .long = name }, error.DoesntTakeValue); + return parser.err(arg, .{ .long = name }, error.DoesntTakeValue); return Arg(Id){ .param = param }; } @@ -80,18 +81,18 @@ pub fn StreamingClap(comptime Id: type, comptime ArgIterator: type) type { break :blk v; break :blk (try parser.iter.next()) orelse - return err(diag, arg, .{ .long = name }, error.MissingValue); + return parser.err(arg, .{ .long = name }, error.MissingValue); }; return Arg(Id){ .param = param, .value = value }; } - return err(diag, arg, .{ .long = name }, error.InvalidArgument); + return parser.err(arg, .{ .long = name }, error.InvalidArgument); }, .short => return try parser.chainging(.{ .arg = arg, .index = 0, - }, diag), + }), .positional => if (parser.positionalParam()) |param| { // If we find a positional with the value `--` then we // interpret the rest of the arguments as positional @@ -104,12 +105,12 @@ pub fn StreamingClap(comptime Id: type, comptime ArgIterator: type) type { return Arg(Id){ .param = param, .value = arg }; } else { - return err(diag, arg, .{}, error.InvalidArgument); + return parser.err(arg, .{}, error.InvalidArgument); }, } } - fn chainging(parser: *@This(), state: State.Chaining, diag: ?*clap.Diagnostic) !?Arg(Id) { + fn chainging(parser: *@This(), state: State.Chaining) !?Arg(Id) { const arg = state.arg; const index = state.index; const next_index = index + 1; @@ -136,13 +137,13 @@ pub fn StreamingClap(comptime Id: type, comptime ArgIterator: type) type { const next_is_eql = if (next_index < arg.len) arg[next_index] == '=' else false; if (param.takes_value == .None) { if (next_is_eql) - return err(diag, arg, .{ .short = short }, error.DoesntTakeValue); + return parser.err(arg, .{ .short = short }, error.DoesntTakeValue); return Arg(Id){ .param = param }; } if (arg.len <= next_index) { const value = (try parser.iter.next()) orelse - return err(diag, arg, .{ .short = short }, error.MissingValue); + return parser.err(arg, .{ .short = short }, error.MissingValue); return Arg(Id){ .param = param, .value = value }; } @@ -153,7 +154,7 @@ pub fn StreamingClap(comptime Id: type, comptime ArgIterator: type) type { return Arg(Id){ .param = param, .value = arg[next_index..] }; } - return err(diag, arg, .{ .short = arg[index] }, error.InvalidArgument); + return parser.err(arg, .{ .short = arg[index] }, error.InvalidArgument); } fn positionalParam(parser: *@This()) ?*const clap.Param(Id) { @@ -194,8 +195,8 @@ pub fn StreamingClap(comptime Id: type, comptime ArgIterator: type) type { return ArgInfo{ .arg = full_arg, .kind = .positional }; } - fn err(diag: ?*clap.Diagnostic, arg: []const u8, names: clap.Names, _err: anytype) @TypeOf(_err) { - if (diag) |d| + fn err(parser: @This(), arg: []const u8, names: clap.Names, _err: anytype) @TypeOf(_err) { + if (parser.diagnostic) |d| d.* = .{ .arg = arg, .name = names }; return _err; } @@ -210,7 +211,7 @@ fn testNoErr(params: []const clap.Param(u8), args_strings: []const []const u8, r }; for (results) |res| { - const arg = (c.next(null) catch unreachable) orelse unreachable; + const arg = (c.next() catch unreachable) orelse unreachable; testing.expectEqual(res.param, arg.param); const expected_value = res.value orelse { testing.expectEqual(@as(@TypeOf(arg.value), null), arg.value); @@ -220,18 +221,19 @@ fn testNoErr(params: []const clap.Param(u8), args_strings: []const []const u8, r testing.expectEqualSlices(u8, expected_value, actual_value); } - if (c.next(null) catch unreachable) |_| + if (c.next() catch unreachable) |_| unreachable; } fn testErr(params: []const clap.Param(u8), args_strings: []const []const u8, expected: []const u8) void { - var diag: clap.Diagnostic = undefined; + var diag = clap.Diagnostic{}; var iter = args.SliceIterator{ .args = args_strings }; var c = StreamingClap(u8, args.SliceIterator){ .params = params, .iter = &iter, + .diagnostic = &diag, }; - while (c.next(&diag) catch |err| { + while (c.next() catch |err| { var buf: [1024]u8 = undefined; var slice_stream = io.fixedBufferStream(&buf); diag.report(slice_stream.outStream(), err) catch unreachable; diff --git a/example/simple-ex.zig b/example/simple-ex.zig index d6ecc44..f504d63 100644 --- a/example/simple-ex.zig +++ b/example/simple-ex.zig @@ -1,5 +1,5 @@ -const std = @import("std"); const clap = @import("clap"); +const std = @import("std"); const debug = std.debug; @@ -21,11 +21,13 @@ pub fn main() !void { defer iter.deinit(); // Initalize our diagnostics, which can be used for reporting useful errors. - // This is optional. You can also just pass `null` to `parser.next` if you - // don't care about the extra information `Diagnostics` provides. - var diag: clap.Diagnostic = undefined; - - var args = clap.parseEx(clap.Help, ¶ms, allocator, &iter, &diag) catch |err| { + // 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 args = clap.parseEx(clap.Help, ¶ms, &iter, .{ + .allocator = allocator, + .diagnostic = &diag, + }) catch |err| { // Report useful error and exit diag.report(std.io.getStdErr().outStream(), err) catch {}; return err; diff --git a/example/simple.zig b/example/simple.zig index 270e344..392dca3 100644 --- a/example/simple.zig +++ b/example/simple.zig @@ -1,5 +1,5 @@ -const std = @import("std"); const clap = @import("clap"); +const std = @import("std"); const debug = std.debug; @@ -14,11 +14,10 @@ pub fn main() !void { }; // Initalize our diagnostics, which can be used for reporting useful errors. - // This is optional. You can also just pass `null` to `parser.next` if you - // don't care about the extra information `Diagnostics` provides. - var diag: clap.Diagnostic = undefined; - - var args = clap.parse(clap.Help, ¶ms, std.heap.page_allocator, &diag) catch |err| { + // 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 args = clap.parse(clap.Help, ¶ms, .{ .diagnostic = &diag }) catch |err| { // Report useful error and exit diag.report(std.io.getStdErr().outStream(), err) catch {}; return err; diff --git a/example/streaming-clap.zig b/example/streaming-clap.zig index 941070f..f8d873d 100644 --- a/example/streaming-clap.zig +++ b/example/streaming-clap.zig @@ -1,5 +1,5 @@ -const std = @import("std"); const clap = @import("clap"); +const std = @import("std"); const debug = std.debug; @@ -28,19 +28,18 @@ pub fn main() !void { var iter = try clap.args.OsIterator.init(allocator); defer iter.deinit(); - // Initialize our streaming parser. + // Initalize our diagnostics, which can be used for reporting useful errors. + // This is optional. You can also leave the `diagnostic` field unset if you + // don't care about the extra information `Diagnostic` provides. + var diag = clap.Diagnostic{}; var parser = clap.StreamingClap(u8, clap.args.OsIterator){ .params = ¶ms, .iter = &iter, + .diagnostic = &diag, }; - // Initalize our diagnostics, which can be used for reporting useful errors. - // This is optional. You can also just pass `null` to `parser.next` if you - // don't care about the extra information `Diagnostics` provides. - var diag: clap.Diagnostic = undefined; - // Because we use a streaming parser, we have to consume each argument parsed individually. - while (parser.next(&diag) catch |err| { + while (parser.next() catch |err| { // Report useful error and exit diag.report(std.io.getStdErr().outStream(), err) catch {}; return err; -- cgit v1.2.3