feat: Introduce an ability to display proper arg's value placeholder in help

Signed-off-by: prajwalch <[email protected]>

Author: prajwalch

examples/ls.zig

@@ -30,8 +30,15 @@ pub fn main() anyerror!void {
     try myls.addArg(Arg.booleanOption("one-line", '1', "List each entries in new line"));
     try myls.addArg(Arg.booleanOption("size", 's', "Display file size"));
     try myls.addArg(Arg.booleanOption("version", null, "Display program version number"));
-    try myls.addArg(Arg.singleValueOption("ignore", 'I', "Ignore the given pattern"));
-    try myls.addArg(Arg.singleValueOption("hide", null, "Don't display hidden entries"));
+
+    var ignore_opt = Arg.singleValueOption("ignore", 'I', "Ignore the given pattern");
+    ignore_opt.setValuePlaceholder("PATTERN");
+
+    var hide_opt = Arg.singleValueOption("hide", null, "Don't display hidden entries");
+    hide_opt.setValuePlaceholder("PATTERN");
+
+    try myls.addArg(ignore_opt);
+    try myls.addArg(hide_opt);
     try myls.addArg(Arg.singleValueOptionWithValidValues(
         "color",
         'C',

src/Arg.zig

@@ -30,6 +30,7 @@ short_name: ?u8 = null,
 long_name: ?[]const u8 = null,
 min_values: ?usize = null,
 max_values: ?usize = null,
+value_placeholder: ?[]const u8 = null,
 valid_values: ?[]const []const u8 = null,
 values_delimiter: ?[]const u8 = null,
 index: ?usize = null,
@@ -321,6 +322,42 @@ pub fn setMaxValues(self: *Arg, num: usize) void {
     self.max_values = if (num >= 1) num else null;
 }
 
+/// Sets the placeholder for the argument value in the help message.
+///
+/// The placeholder is only used to display on help message and by default,
+/// if the placeholder is not set, argument name is displayed.
+///
+/// **NOTE:** If the argument doesn't take value, placeholder is ignored.
+///
+/// ## Examples
+///
+/// ```zig
+/// var app = App.init(allocator, "myapp", "My app description");
+/// defer app.deinit();
+///
+/// var root = app.rootCommand();
+///
+/// var arg = Arg.singleValueOption("exp-time", 't', "Set max expire time")
+/// arg.setValuePlaceholder("SECS");
+///
+/// root.addArg(arg);
+/// ```
+///
+/// On command line:
+///
+/// ```sh
+/// $ myapp -h
+/// My app description
+///
+/// Usage: myapp [OPTIONS]
+///
+/// Options:
+///     -t, --exp-time=<SECS>       Set max expire time
+/// ```
+pub fn setValuePlaceholder(self: *Arg, placeholder: []const u8) void {
+    self.value_placeholder = placeholder;
+}
+
 /// Sets the valid values for an argument.
 ///
 /// ## Examples

src/HelpMessageWriter.zig

@@ -141,34 +141,12 @@ fn writeOption(self: *HelpMessageWriter, option: *const Arg) !void {
 
     // Value name.
     if (option.hasProperty(.takes_value)) {
-        try signature_writer.writeByte('=');
+        // Otherwise print the option actual value name or option name itself.
+        const value_name = option.value_placeholder orelse option.name;
+        try signature_writer.print("=<{s}>", .{value_name});
 
-        // If the option has set acceptable values, print that.
-        if (option.valid_values) |valid_values| {
-            try signature_writer.writeByte('<');
-
-            for (valid_values, 0..) |value, idx| {
-                try signature_writer.print("{s}", .{value});
-
-                // Don't print `|` at first and last.
-                //
-                // For e.x.: --format=<json|toml|yaml>
-                if (idx < (valid_values.len - 1)) {
-                    try signature_writer.writeByte('|');
-                }
-            }
-
-            try signature_writer.writeByte('>');
-        } else {
-            // Otherwise print the option name.
-            //
-            // TODO: Add new `Arg.placeholderName()` to display correct value
-            //       or placeholder name. For e.x.: --time=SECS.
-            try signature_writer.print("<{s}>", .{option.name});
-
-            if (option.hasProperty(.takes_multiple_values)) {
-                try signature_writer.writeAll("...");
-            }
+        if (option.hasProperty(.takes_multiple_values)) {
+            try signature_writer.writeAll("...");
         }
     }
 
@@ -178,6 +156,11 @@ fn writeOption(self: *HelpMessageWriter, option: *const Arg) !void {
     // Then write the description.
     if (option.description) |description| {
         try writer.print("\t\t{s}", .{description});
+
+        if (option.valid_values) |valid_values| {
+            // FIXME: Remove this hacky implmentation
+            try writer.print("\n\t\t\t\t\t\t values: {s}", .{valid_values});
+        }
     }
 
     // End of line.