From 0356f53d5bc46011efc6b6ffbfe0b202466d7b4f Mon Sep 17 00:00:00 2001
From: Jimmi Holst Christensen
Date: Tue, 22 Jul 2025 10:54:19 +0200
Subject: feat: Add `clap.usageToFile`

The code for printing usage became quite verbose after writegate.
Writing usage to a file like stdout and stderr is very common, so this
wrapper provides a default, buffered way to report to a file.
---
 README.md         | 12 ++++--------
 clap.zig          | 12 ++++++++++--
 example/usage.zig | 13 ++++---------
 3 files changed, 18 insertions(+), 19 deletions(-)

diff --git a/README.md b/README.md
index 6a1435f..b9fbda7 100644
--- a/README.md
+++ b/README.md
@@ -404,14 +404,10 @@ pub fn main() !void {
     });
     defer res.deinit();
 
-    // `clap.usage` is a function that can print a simple help message. It can print any `Param`
-    // where `Id` has a `value` method (`Param(Help)` is one such parameter).
-    if (res.args.help != 0) {
-        var buf: [1024]u8 = undefined;
-        var stderr = std.fs.File.stderr().writer(&buf);
-        try clap.usage(&stderr.interface, clap.Help, &params);
-        return stderr.interface.flush();
-    }
+    // `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.usage(.stdout(), clap.Help, &params);
 }
 
 const clap = @import("clap");
diff --git a/clap.zig b/clap.zig
index 4a001ce..1e710ea 100644
--- a/clap.zig
+++ b/clap.zig
@@ -569,7 +569,7 @@ pub const Diagnostic = struct {
         var buf: [1024]u8 = undefined;
         var writer = file.writer(&buf);
         try diag.report(&writer.interface, err);
-        return writer.end();
+        return writer.interface.flush();
     }
 };
 
@@ -1377,7 +1377,7 @@ pub fn helpToFile(
     var buf: [1024]u8 = undefined;
     var writer = file.writer(&buf);
     try help(&writer.interface, Id, params, opt);
-    return writer.end();
+    return writer.interface.flush();
 }
 
 /// Print a slice of `Param` formatted as a help string to `writer`. This function expects
@@ -2027,6 +2027,14 @@ test "clap.help" {
     );
 }
 
+/// Wrapper around `usage`, which writes to a file in a buffered manner
+pub fn usageToFile(file: std.fs.File, comptime Id: type, params: []const Param(Id)) !void {
+    var buf: [1024]u8 = undefined;
+    var writer = file.writer(&buf);
+    try usage(&writer.interface, Id, params);
+    return writer.interface.flush();
+}
+
 /// Will print a usage message in the following format:
 /// [-abc] [--longa] [-d <T>] [--longb <T>] <T>
 ///
diff --git a/example/usage.zig b/example/usage.zig
index 8bd25b7..b7308f5 100644
--- a/example/usage.zig
+++ b/example/usage.zig
@@ -14,15 +14,10 @@ pub fn main() !void {
     });
     defer res.deinit();
 
-    // `clap.usage` is a function that can print a simple help message. It can print any `Param`
-    // where `Id` has a `value` method (`Param(Help)` is one such parameter).
-    if (res.args.help != 0) {
-        var buf: [1024]u8 = undefined;
-        var stderr = std.fs.File.stderr().writer(&buf);
-        clap.usage(&stderr.interface, clap.Help, &params) catch {};
-        try stderr.interface.flush();
-        return;
-    }
+    // `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, &params);
 }
 
 const clap = @import("clap");
-- 
cgit v1.2.3