diff --git a/stdx/flags.zig b/stdx/flags.zig index 52a9e6a4..13f509a4 100644 --- a/stdx/flags.zig +++ b/stdx/flags.zig @@ -12,8 +12,9 @@ //! - In particular, check that no options are repeated. //! - Use only long options (`--addresses`). //! - Exception: `-h/--help` is allowed. -//! - Use `--key=value` syntax for an option with an argument. -//! Don't use `--key value`, as that can be ambiguous (e.g., `--key --verbose`). +//! - Use `--key=value` or `--key value` syntax for an option with an argument. +//! With `--key value`, a value starting with `--` is rejected to avoid ambiguity +//! (e.g., `--key --verbose`); use `--key=--value` for such values. //! - Use subcommand syntax when appropriate. //! - Use positional arguments when appropriate. //! @@ -94,7 +95,7 @@ pub fn parseProcessArgs(init_: std.process.Init.Minimal, comptime CliArgs: type) fn parse_commands(args: *std.process.Args.Iterator, comptime Commands: type) Commands { comptime assert(@typeInfo(Commands) == .@"union"); - const field_names = std.meta.fieldNames(Commands); + const field_names = comptime std.meta.fieldNames(Commands); comptime assert(field_names.len >= 2); const first_arg = args.next() orelse fatal( @@ -110,7 +111,7 @@ fn parse_commands(args: *std.process.Args.Iterator, comptime Commands: type) Com } } - inline for (field_names, std.meta.fieldTypes(Commands)) |field_name, FieldType| { + inline for (field_names, comptime std.meta.fieldTypes(Commands)) |field_name, FieldType| { comptime assert(std.mem.indexOf(u8, field_name, "_") == null); if (std.mem.eql(u8, first_arg, field_name)) { return @unionInit(Commands, field_name, parse_flags(args, FieldType)); @@ -246,8 +247,15 @@ fn parse_flags(args: *std.process.Args.Iterator, comptime Flags: type) Flags { } @field(counts, field_name) += 1; - const flag_value = parse_flag(FieldType, flag, arg); - @field(result, field_name) = flag_value; + // `--flag=value` carries its value inline; a bare non-bool `--flag` takes + // the next argument as its value. + const value: ?[:0]const u8 = if (arg.len > flag.len) + parse_flag_split_value(flag, arg) + else if (FieldType == bool) + null + else + parse_flag_next_value(flag, args); + @field(result, field_name) = parse_flag(FieldType, flag, value); continue :next_arg; } } @@ -331,20 +339,34 @@ fn assert_valid_value_type(comptime T: type) void { } } -/// Parse, e.g., `--cluster=123` into `123` integer -fn parse_flag(comptime T: type, flag: []const u8, arg: [:0]const u8) T { +/// Parse the value of a matched flag into `T`, e.g. `123` for `--cluster=123` or `--cluster 123`. +/// +/// - `flag`: the flag name with its leading dashes, e.g. `--cluster`. +/// - `value`: the flag's value with the separator stripped, e.g. `123`, or `null` if the flag was +/// given without a value (only valid for `bool` flags, where presence means `true`). +fn parse_flag(comptime T: type, flag: []const u8, value: ?[:0]const u8) T { assert(flag[0] == '-' and flag[1] == '-'); if (T == bool) { - if (!std.mem.eql(u8, arg, flag)) { - fatal("{s}: argument does not require a value in '{s}'", .{ flag, arg }); + if (value) |v| { + fatal("{s}: argument does not require a value, but found '{s}'", .{ flag, v }); } return true; } - const value = parse_flag_split_value(flag, arg); - assert(value.len > 0); - return parse_value(T, flag, value); + // The caller always resolves a value for non-bool flags (or exits). + assert(value.?.len > 0); + return parse_value(T, flag, value.?); +} + +/// Takes the value from the next argument for `--flag value` syntax. +fn parse_flag_next_value(flag: []const u8, args: *std.process.Args.Iterator) [:0]const u8 { + const value = args.next() orelse fatal("{s}: argument requires a value", .{flag}); + if (value.len == 0) fatal("{s}: argument requires a value", .{flag}); + if (std.mem.startsWith(u8, value, "--")) { + fatal("{s}: argument requires a value, but found '{s}' (use {s}=)", .{ flag, value, flag }); + } + return value; } /// Splits the value part from a `--arg=value` syntax. @@ -591,25 +613,19 @@ fn fields_to_comma_list(comptime E: type) []const u8 { } } +/// Maps a field name to its CLI flag, e.g. `model_path` to `--model-path`. pub fn flag_name(comptime field_name: []const u8) []const u8 { - // TODO(Zig): Cleanup when this is fixed after Zig 0.11. - // Without comptime blk, the compiler thinks the result is a runtime slice returning a UAF. - return comptime blk: { - assert(!std.mem.eql(u8, field_name, "positional")); - - var result: []const u8 = "--"; - var index = 0; - while (std.mem.indexOf(u8, field_name[index..], "_")) |i| { - result = result ++ field_name[index..][0..i] ++ "-"; - index = index + i + 1; - } - result = result ++ field_name[index..]; - break :blk result; - }; + comptime assert(!std.mem.eql(u8, field_name, "positional")); + comptime var name = field_name[0..field_name.len].*; + comptime std.mem.replaceScalar(u8, &name, '_', '-'); + const dashed = name; + return "--" ++ dashed; } test flag_name { - try std.testing.expectEqualStrings(flag_name("statsd"), "--statsd"); + try std.testing.expectEqualStrings("--statsd", flag_name("statsd")); + try std.testing.expectEqualStrings("--model-path", flag_name("model_path")); + try std.testing.expectEqualStrings("--a-b-c", flag_name("a_b_c")); } fn flag_name_positional(comptime field_name: []const u8) []const u8 { @@ -621,3 +637,109 @@ pub fn defaultValue(comptime FieldType: type, default_value_ptr: ?*const anyopaq const dp: *const FieldType = @ptrCast(@alignCast(default_value_ptr orelse return null)); return dp.*; } + +/// Builds a real args iterator over `args` (POSIX only, where `Args` is a plain argv vector). +fn testArgsIterator(args: []const [*:0]const u8) std.process.Args.Iterator { + const process_args: std.process.Args = .{ .vector = args }; + return process_args.iterate(); +} + +fn testParseFlags(comptime Flags: type, args: []const [*:0]const u8) Flags { + var it = testArgsIterator(args); + const result = parse_flags(&it, Flags); + std.debug.assert(it.next() == null); + return result; +} + +const TestFlags = struct { + model: []const u8, + boolean_flag: bool = false, + count: u32 = 1, + ratio: f32 = 0.5, + mode: enum { fast, slow } = .fast, + seed: ?i64 = null, +}; + +test "parse_flags: --flag=value syntax" { + const flags = testParseFlags(TestFlags, &.{ "--model=AA", "--count=3", "--ratio=0.25", "--mode=slow", "--seed=-7" }); + try std.testing.expectEqualStrings("AA", flags.model); + try std.testing.expectEqual(false, flags.boolean_flag); + try std.testing.expectEqual(3, flags.count); + try std.testing.expectEqual(0.25, flags.ratio); + try std.testing.expectEqual(.slow, flags.mode); + try std.testing.expectEqual(-7, flags.seed); +} + +test "parse_flags: --flag value syntax" { + const flags = testParseFlags(TestFlags, &.{ "--model", "AA", "--count", "3", "--ratio", "0.25", "--mode", "slow", "--seed", "-7" }); + try std.testing.expectEqualStrings("AA", flags.model); + try std.testing.expectEqual(3, flags.count); + try std.testing.expectEqual(0.25, flags.ratio); + try std.testing.expectEqual(.slow, flags.mode); + try std.testing.expectEqual(-7, flags.seed); +} + +test "parse_flags: bool flag after spaced value is not consumed as a value" { + const flags = testParseFlags(TestFlags, &.{ "--model", "AA", "--boolean-flag" }); + try std.testing.expectEqualStrings("AA", flags.model); + try std.testing.expectEqual(true, flags.boolean_flag); +} + +test "parse_flags: bool flag before spaced value" { + const flags = testParseFlags(TestFlags, &.{ "--boolean-flag", "--model", "AA" }); + try std.testing.expectEqualStrings("AA", flags.model); + try std.testing.expectEqual(true, flags.boolean_flag); +} + +test "parse_flags: mixed syntaxes and defaults" { + const flags = testParseFlags(TestFlags, &.{ "--count=2", "--model", "hf://org/repo", "--boolean-flag" }); + try std.testing.expectEqualStrings("hf://org/repo", flags.model); + try std.testing.expectEqual(true, flags.boolean_flag); + try std.testing.expectEqual(2, flags.count); + try std.testing.expectEqual(0.5, flags.ratio); + try std.testing.expectEqual(.fast, flags.mode); + try std.testing.expectEqual(null, flags.seed); +} + +test "parse_flags: --flag=value allows values starting with --" { + const flags = testParseFlags(TestFlags, &.{"--model=--AA"}); + try std.testing.expectEqualStrings("--AA", flags.model); +} + +test "parse_flags: spaced value containing '='" { + const flags = testParseFlags(TestFlags, &.{ "--model", "a=b" }); + try std.testing.expectEqualStrings("a=b", flags.model); +} + +test "parse_flags: longer flag names are not confused with prefixes" { + const Flags = struct { + model: []const u8 = "", + model_path: []const u8 = "", + }; + const flags = testParseFlags(Flags, &.{ "--model-path", "P", "--model", "M" }); + try std.testing.expectEqualStrings("M", flags.model); + try std.testing.expectEqualStrings("P", flags.model_path); +} + +test "parse_flags: spaced value followed by positional" { + const Flags = struct { + model: []const u8, + positional: struct { + path: []const u8, + }, + }; + const flags = testParseFlags(Flags, &.{ "--model", "AA", "some/path" }); + try std.testing.expectEqualStrings("AA", flags.model); + try std.testing.expectEqualStrings("some/path", flags.positional.path); +} + +test "parse_commands: subcommand with spaced value" { + const Commands = union(enum) { + run: struct { model: []const u8, verbose: bool = false }, + list: void, + }; + var it = testArgsIterator(&.{ "run", "--model", "AA", "--verbose" }); + const cmd = parse_commands(&it, Commands); + try std.testing.expectEqualStrings("AA", cmd.run.model); + try std.testing.expectEqual(true, cmd.run.verbose); +}