feat: Add the `WithUsage` function.

args.go

@@ -129,3 +129,16 @@ func MatchAll(pargs ...PositionalArgs) PositionalArgs {
 func ExactValidArgs(n int) PositionalArgs {
 	return MatchAll(ExactArgs(n), OnlyValidArgs)
 }
+
+// WithUsage wraps another PositionalArgs function. If the function fails
+// (returns a non-nil error), the error is supplemented with the command's
+// usage message, providing the user with the information required to run the
+// command correctly.
+func WithUsage(wrapped PositionalArgs) PositionalArgs {
+	return func(cmd *Command, args []string) error {
+		if err := wrapped(cmd, args); err != nil {
+			return fmt.Errorf("%w\n\n%s", err, cmd.UsageString())
+		}
+		return nil
+	}
+}

args_test.go

@@ -539,3 +539,27 @@ func TestLegacyArgsSubcmdAcceptsArgs(t *testing.T) {
 		t.Fatalf("Unexpected error: %v", err)
 	}
 }
+
+// WithUsage
+
+func TestWithUsage(t *testing.T) {
+	c := getCommand(WithUsage(ExactArgs(1)), false)
+
+	_, err := executeCommand(c /* no args */)
+	if err == nil {
+		t.Fatalf("Expected error, got nil")
+	}
+
+	got, want := err.Error(), c.UsageString()
+	if !strings.Contains(got, want) {
+		t.Errorf("Expected error containing %q, got %q", want, got)
+	}
+}
+
+func ExampleWithUsage() {
+	cmd := &Command{
+		Use:  "example <arg>",
+		Args: WithUsage(ExactArgs(1)),
+	}
+	_ = cmd // ignore unused
+}