From b7e6ebf36e2ac4314e6bff65f1d64466ea82a18a Mon Sep 17 00:00:00 2001 From: Jimmi Holst Christensen Date: Tue, 10 Nov 2020 18:53:57 +0100 Subject: Deprecate ComptimeClap in favor of parseEx --- README.md | 56 ++-------------------------------------------- build.zig | 3 +-- clap.zig | 21 ++++++++++++----- clap/comptime.zig | 8 +++---- example/README.md.template | 11 ++------- example/comptime-clap.zig | 45 ------------------------------------- example/simple-ex.zig | 43 +++++++++++++++++++++++++++++++++++ 7 files changed, 68 insertions(+), 119 deletions(-) delete mode 100644 example/comptime-clap.zig create mode 100644 example/simple-ex.zig diff --git a/README.md b/README.md index ebcebbb..3156539 100644 --- a/README.md +++ b/README.md @@ -99,59 +99,7 @@ zig-clap/example/simple-error.zig:16:18: note: called from here _ = args.flag("--helps"); ``` -### `ComptimeClap` - -The `ComptimeClap` is the parser used by `clap.parse`. It allows the user to use a custom argument -iterator. - -```zig -const std = @import("std"); -const clap = @import("clap"); - -const debug = std.debug; - -pub fn main() !void { - const allocator = std.heap.page_allocator; - - // First we specify what parameters our program can take. - // We can use `parseParam` to parse a string to a `Param(Help)` - const params = comptime [_]clap.Param(clap.Help){ - clap.parseParam("-h, --help Display this help and exit. ") catch unreachable, - clap.parseParam("-n, --number An option parameter, which takes a value.") catch unreachable, - clap.parseParam("-s, --string ... An option parameter which can be specified multiple times.") catch unreachable, - clap.parseParam("...") catch unreachable, - }; - const Clap = clap.ComptimeClap(clap.Help, clap.args.OsIterator, ¶ms); - - // We then initialize an argument iterator. We will use the OsIterator as it nicely - // wraps iterating over arguments the most efficient way on each os. - var iter = try clap.args.OsIterator.init(allocator); - 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; - - // Parse the arguments - var args = Clap.parse(allocator, &iter, &diag) catch |err| { - // Report useful error and exit - diag.report(std.io.getStdErr().outStream(), err) catch {}; - return err; - }; - defer args.deinit(); - - if (args.flag("--help")) - debug.warn("--help\n", .{}); - if (args.option("--number")) |n| - debug.warn("--number = {}\n", .{n}); - for (args.options("--string")) |s| - debug.warn("--string = {}\n", .{s}); - for (args.positionals()) |pos| - debug.warn("{}\n", .{pos}); -} - -``` +There is also a `parseEx` variant that takes an argument iterator. ### `StreamingClap` @@ -222,7 +170,7 @@ pub fn main() !void { ``` -Currently, this parse is the only parser that allow an array of `Param` that +Currently, this parse is the only parser that allow an array of `Param` tha is generated at runtime. ### `help` diff --git a/build.zig b/build.zig index 9baf1d4..c32f4c2 100644 --- a/build.zig +++ b/build.zig @@ -32,8 +32,8 @@ pub fn build(b: *Builder) void { const example_step = b.step("examples", "Build examples"); inline for ([_][]const u8{ "simple", + "simple-ex", //"simple-error", - "comptime-clap", "streaming-clap", "help", "usage", @@ -70,7 +70,6 @@ fn readMeStep(b: *Builder) *std.build.Step { try stream.print(@embedFile("example/README.md.template"), .{ @embedFile("example/simple.zig"), @embedFile("example/simple-error.zig"), - @embedFile("example/comptime-clap.zig"), @embedFile("example/streaming-clap.zig"), @embedFile("example/help.zig"), @embedFile("example/usage.zig"), diff --git a/clap.zig b/clap.zig index 8624c88..4548a48 100644 --- a/clap.zig +++ b/clap.zig @@ -303,7 +303,7 @@ test "Diagnostic.report" { pub fn Args(comptime Id: type, comptime params: []const Param(Id)) type { return struct { arena: std.heap.ArenaAllocator, - clap: ComptimeClap(Id, args.OsIterator, params), + clap: ComptimeClap(Id, params), exe_arg: ?[]const u8, pub fn deinit(a: *@This()) void { @@ -329,8 +329,7 @@ pub fn Args(comptime Id: type, comptime params: []const Param(Id)) type { }; } -/// Parses the command line arguments passed into the program based on an -/// array of `Param`s. +/// Same as `parseEx` but uses the `args.OsIterator` by default. pub fn parse( comptime Id: type, comptime params: []const Param(Id), @@ -338,8 +337,7 @@ pub fn parse( diag: ?*Diagnostic, ) !Args(Id, params) { var iter = try args.OsIterator.init(allocator); - const Clap = ComptimeClap(Id, args.OsIterator, params); - const clap = try Clap.parse(allocator, &iter, diag); + const clap = try parseEx(Id, params, allocator, &iter, diag); return Args(Id, params){ .arena = iter.arena, .clap = clap, @@ -347,6 +345,19 @@ pub fn parse( }; } +/// Parses the command line arguments passed into the program based on an +/// array of `Param`s. +pub fn parseEx( + comptime Id: type, + comptime params: []const Param(Id), + allocator: *mem.Allocator, + iter: anytype, + diag: ?*Diagnostic, +) !ComptimeClap(Id, params) { + const Clap = ComptimeClap(Id, params); + return try Clap.parse(allocator, iter, diag); +} + /// Will print a help message in the following format: /// -s, --long helpText /// -s, helpText diff --git a/clap/comptime.zig b/clap/comptime.zig index 80eb428..8ab61cb 100644 --- a/clap/comptime.zig +++ b/clap/comptime.zig @@ -6,9 +6,9 @@ const heap = std.heap; const mem = std.mem; const debug = std.debug; +/// Deprecated: Use `parseEx` instead pub fn ComptimeClap( comptime Id: type, - comptime ArgIter: type, comptime params: []const clap.Param(Id), ) type { var flags: usize = 0; @@ -42,7 +42,7 @@ pub fn ComptimeClap( pos: []const []const u8, allocator: *mem.Allocator, - pub fn parse(allocator: *mem.Allocator, iter: *ArgIter, diag: ?*clap.Diagnostic) !@This() { + pub fn parse(allocator: *mem.Allocator, iter: anytype, diag: ?*clap.Diagnostic) !@This() { var multis = [_]std.ArrayList([]const u8){undefined} ** multi_options; for (multis) |*multi| { multi.* = std.ArrayList([]const u8).init(allocator); @@ -58,7 +58,7 @@ pub fn ComptimeClap( .allocator = allocator, }; - var stream = clap.StreamingClap(usize, ArgIter){ + var stream = clap.StreamingClap(usize, @typeInfo(@TypeOf(iter)).Pointer.child){ .params = converted_params, .iter = iter, }; @@ -147,7 +147,7 @@ pub fn ComptimeClap( } test "" { - const Clap = ComptimeClap(clap.Help, clap.args.SliceIterator, comptime &[_]clap.Param(clap.Help){ + const Clap = ComptimeClap(clap.Help, comptime &[_]clap.Param(clap.Help){ clap.parseParam("-a, --aa ") catch unreachable, clap.parseParam("-b, --bb ") catch unreachable, clap.parseParam("-c, --cc ") catch unreachable, diff --git a/example/README.md.template b/example/README.md.template index 65b507d..530cea4 100644 --- a/example/README.md.template +++ b/example/README.md.template @@ -50,14 +50,7 @@ zig-clap/example/simple-error.zig:16:18: note: called from here _ = args.flag("--helps"); ``` -### `ComptimeClap` - -The `ComptimeClap` is the parser used by `clap.parse`. It allows the user to use a custom argument -iterator. - -```zig -{} -``` +There is also a `parseEx` variant that takes an argument iterator. ### `StreamingClap` @@ -68,7 +61,7 @@ The `StreamingClap` is the base of all the other parsers. It's a streaming parse {} ``` -Currently, this parse is the only parser that allow an array of `Param` that +Currently, this parse is the only parser that allow an array of `Param` tha is generated at runtime. ### `help` diff --git a/example/comptime-clap.zig b/example/comptime-clap.zig deleted file mode 100644 index e5d02ff..0000000 --- a/example/comptime-clap.zig +++ /dev/null @@ -1,45 +0,0 @@ -const std = @import("std"); -const clap = @import("clap"); - -const debug = std.debug; - -pub fn main() !void { - const allocator = std.heap.page_allocator; - - // First we specify what parameters our program can take. - // We can use `parseParam` to parse a string to a `Param(Help)` - const params = comptime [_]clap.Param(clap.Help){ - clap.parseParam("-h, --help Display this help and exit. ") catch unreachable, - clap.parseParam("-n, --number An option parameter, which takes a value.") catch unreachable, - clap.parseParam("-s, --string ... An option parameter which can be specified multiple times.") catch unreachable, - clap.parseParam("...") catch unreachable, - }; - const Clap = clap.ComptimeClap(clap.Help, clap.args.OsIterator, ¶ms); - - // We then initialize an argument iterator. We will use the OsIterator as it nicely - // wraps iterating over arguments the most efficient way on each os. - var iter = try clap.args.OsIterator.init(allocator); - 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; - - // Parse the arguments - var args = Clap.parse(allocator, &iter, &diag) catch |err| { - // Report useful error and exit - diag.report(std.io.getStdErr().outStream(), err) catch {}; - return err; - }; - defer args.deinit(); - - if (args.flag("--help")) - debug.warn("--help\n", .{}); - if (args.option("--number")) |n| - debug.warn("--number = {}\n", .{n}); - for (args.options("--string")) |s| - debug.warn("--string = {}\n", .{s}); - for (args.positionals()) |pos| - debug.warn("{}\n", .{pos}); -} diff --git a/example/simple-ex.zig b/example/simple-ex.zig new file mode 100644 index 0000000..d6ecc44 --- /dev/null +++ b/example/simple-ex.zig @@ -0,0 +1,43 @@ +const std = @import("std"); +const clap = @import("clap"); + +const debug = std.debug; + +pub fn main() !void { + const allocator = std.heap.page_allocator; + + // First we specify what parameters our program can take. + // We can use `parseParam` to parse a string to a `Param(Help)` + const params = comptime [_]clap.Param(clap.Help){ + clap.parseParam("-h, --help Display this help and exit. ") catch unreachable, + clap.parseParam("-n, --number An option parameter, which takes a value.") catch unreachable, + clap.parseParam("-s, --string ... An option parameter which can be specified multiple times.") catch unreachable, + clap.parseParam("...") catch unreachable, + }; + + // We then initialize an argument iterator. We will use the OsIterator as it nicely + // wraps iterating over arguments the most efficient way on each os. + var iter = try clap.args.OsIterator.init(allocator); + 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| { + // Report useful error and exit + diag.report(std.io.getStdErr().outStream(), err) catch {}; + return err; + }; + defer args.deinit(); + + if (args.flag("--help")) + debug.warn("--help\n", .{}); + if (args.option("--number")) |n| + debug.warn("--number = {}\n", .{n}); + for (args.options("--string")) |s| + debug.warn("--string = {}\n", .{s}); + for (args.positionals()) |pos| + debug.warn("{}\n", .{pos}); +} -- cgit v1.2.3