feat(clap-complete): Introduce fallible generator

It may happen that writing completion fails due to whichever reason.
Currently clap-complete panics without letting calling code to react on
that error (i.e. ignore). Introduce fallible version of the `generate`
function by mostly only getting rid of except and instead exposing
Result. For backwards compatibility make default trait
implementation of `try_generate` function to call `generate` not to
break users defining their own `generate`.

Issue: #5993

Author: gtema

clap_complete/src/aot/generator/mod.rs

@@ -21,7 +21,7 @@ pub trait Generator {
     /// # Examples
     ///
     /// ```
-    /// # use std::io::Write;
+    /// # use std::io::{Error, Write};
     /// # use clap::Command;
     /// use clap_complete::Generator;
     ///
@@ -32,6 +32,7 @@ pub trait Generator {
     ///         format!("{name}.fish")
     ///     }
     /// #   fn generate(&self, cmd: &Command, buf: &mut dyn Write) {}
+    /// #   fn try_generate(&self, cmd: &Command, buf: &mut dyn Write) -> Result<(), Error> {Ok(())}
     /// }
     /// ```
     fn file_name(&self, name: &str) -> String;
@@ -48,7 +49,7 @@ pub trait Generator {
     /// as if it is printed using [`std::println`].
     ///
     /// ```
-    /// use std::{io::Write, fmt::write};
+    /// use std::{io::{Error, Write}, fmt::write};
     /// use clap::Command;
     /// use clap_complete::Generator;
     ///
@@ -61,9 +62,46 @@ pub trait Generator {
     ///     fn generate(&self, cmd: &Command, buf: &mut dyn Write) {
     ///         write!(buf, "{cmd}").unwrap();
     ///     }
+    /// #   fn try_generate(&self, cmd: &Command, buf: &mut dyn Write) -> Result<(), Error> {
+    /// #       write!(buf, "{cmd}")
+    /// #   }
     /// }
     /// ```
     fn generate(&self, cmd: &Command, buf: &mut dyn Write);
+
+    ///
+    /// Fallible version to generate output out of [`clap::Command`].
+    ///
+    /// # Examples
+    ///
+    /// The following example generator displays the [`clap::Command`]
+    /// as if it is printed using [`std::println`].
+    ///
+    /// ```
+    /// use std::{io::{Error, Write}, fmt::write};
+    /// use clap::Command;
+    /// use clap_complete::Generator;
+    ///
+    /// pub struct ClapDebug;
+    ///
+    /// impl Generator for ClapDebug {
+    /// #   fn file_name(&self, name: &str) -> String {
+    /// #       name.into()
+    /// #   }
+    /// #   fn generate(&self, cmd: &Command, buf: &mut dyn Write) {
+    /// #       self.try_generate(cmd, buf).expect("failed to write completion file");
+    /// #   }
+    ///     fn try_generate(&self, cmd: &Command, buf: &mut dyn Write) -> Result<(), Error> {
+    ///         write!(buf, "{cmd}")
+    ///     }
+    /// }
+    /// ```
+    fn try_generate(&self, cmd: &Command, buf: &mut dyn Write) -> Result<(), Error> {
+        // NOTE(gtema): It is done this way to introduce new function but not break downstream
+        // users. Before cutting major version this should be turned around with [`generate`]
+        // calling [`try_generate`].
+        Ok(self.generate(cmd, buf))
+    }
 }
 
 /// Generate a completions file for a specified shell at compile-time.

clap_complete/src/aot/shells/bash.rs

@@ -1,4 +1,7 @@
-use std::{fmt::Write as _, io::Write};
+use std::{
+    fmt::Write as _,
+    io::{Error, Write},
+};
 
 use clap::{Arg, Command, ValueHint};
 
@@ -14,6 +17,11 @@ impl Generator for Bash {
     }
 
     fn generate(&self, cmd: &Command, buf: &mut dyn Write) {
+        self.try_generate(cmd, buf)
+            .expect("failed to write completion file");
+    }
+
+    fn try_generate(&self, cmd: &Command, buf: &mut dyn Write) -> Result<(), Error> {
         let bin_name = cmd
             .get_bin_name()
             .expect("crate::generate should have set the bin_name");
@@ -75,7 +83,7 @@ fi
             name_opts_details = option_details_for_path(cmd, bin_name),
             subcmds = all_subcommands(cmd, &fn_name),
             subcmd_details = subcommand_details(cmd)
-        ).expect("failed to write completion file");
+        )
     }
 }
 

clap_complete/src/aot/shells/elvish.rs

@@ -1,4 +1,4 @@
-use std::io::Write;
+use std::io::{Error, Write};
 
 use clap::builder::StyledStr;
 use clap::Command;
@@ -16,6 +16,11 @@ impl Generator for Elvish {
     }
 
     fn generate(&self, cmd: &Command, buf: &mut dyn Write) {
+        self.try_generate(cmd, buf)
+            .expect("failed to write completion file");
+    }
+
+    fn try_generate(&self, cmd: &Command, buf: &mut dyn Write) -> Result<(), Error> {
         let bin_name = cmd
             .get_bin_name()
             .expect("crate::generate should have set the bin_name");
@@ -48,7 +53,6 @@ set edit:completion:arg-completer[{bin_name}] = {{|@words|
 }}
 "#,
         )
-        .expect("failed to write completion file");
     }
 }
 

clap_complete/src/aot/shells/fish.rs

@@ -1,4 +1,4 @@
-use std::io::Write;
+use std::io::{Error, Write};
 
 use clap::{builder, Arg, Command, ValueHint};
 
@@ -16,6 +16,11 @@ impl Generator for Fish {
     }
 
     fn generate(&self, cmd: &Command, buf: &mut dyn Write) {
+        self.try_generate(cmd, buf)
+            .expect("failed to write completion file");
+    }
+
+    fn try_generate(&self, cmd: &Command, buf: &mut dyn Write) -> Result<(), Error> {
         let bin_name = cmd
             .get_bin_name()
             .expect("crate::generate should have set the bin_name");
@@ -42,7 +47,7 @@ impl Generator for Fish {
             needs_fn_name,
             using_fn_name,
         );
-        write!(buf, "{buffer}").expect("failed to write completion file");
+        write!(buf, "{buffer}")
     }
 }
 

clap_complete/src/aot/shells/powershell.rs

@@ -1,4 +1,4 @@
-use std::io::Write;
+use std::io::{Error, Write};
 
 use clap::builder::StyledStr;
 use clap::{Arg, Command};
@@ -16,6 +16,11 @@ impl Generator for PowerShell {
     }
 
     fn generate(&self, cmd: &Command, buf: &mut dyn Write) {
+        self.try_generate(cmd, buf)
+            .expect("failed to write completion file");
+    }
+
+    fn try_generate(&self, cmd: &Command, buf: &mut dyn Write) -> Result<(), Error> {
         let bin_name = cmd
             .get_bin_name()
             .expect("crate::generate should have set the bin_name");
@@ -53,7 +58,6 @@ Register-ArgumentCompleter -Native -CommandName '{bin_name}' -ScriptBlock {{
 }}
 "#
         )
-        .expect("failed to write completion file");
     }
 }
 

clap_complete/src/aot/shells/shell.rs

@@ -1,4 +1,5 @@
 use std::fmt::Display;
+use std::io::Error;
 use std::path::Path;
 use std::str::FromStr;
 
@@ -81,12 +82,17 @@ impl Generator for Shell {
     }
 
     fn generate(&self, cmd: &clap::Command, buf: &mut dyn std::io::Write) {
+        self.try_generate(cmd, buf)
+            .expect("failed to write completion file");
+    }
+
+    fn try_generate(&self, cmd: &clap::Command, buf: &mut dyn std::io::Write) -> Result<(), Error> {
         match self {
-            Shell::Bash => shells::Bash.generate(cmd, buf),
-            Shell::Elvish => shells::Elvish.generate(cmd, buf),
-            Shell::Fish => shells::Fish.generate(cmd, buf),
-            Shell::PowerShell => shells::PowerShell.generate(cmd, buf),
-            Shell::Zsh => shells::Zsh.generate(cmd, buf),
+            Shell::Bash => shells::Bash.try_generate(cmd, buf),
+            Shell::Elvish => shells::Elvish.try_generate(cmd, buf),
+            Shell::Fish => shells::Fish.try_generate(cmd, buf),
+            Shell::PowerShell => shells::PowerShell.try_generate(cmd, buf),
+            Shell::Zsh => shells::Zsh.try_generate(cmd, buf),
         }
     }
 }

clap_complete/src/aot/shells/zsh.rs

@@ -1,4 +1,4 @@
-use std::io::Write;
+use std::io::{Error, Write};
 
 use clap::{Arg, ArgAction, Command, ValueHint};
 
@@ -15,6 +15,11 @@ impl Generator for Zsh {
     }
 
     fn generate(&self, cmd: &Command, buf: &mut dyn Write) {
+        self.try_generate(cmd, buf)
+            .expect("failed to write completion file");
+    }
+
+    fn try_generate(&self, cmd: &Command, buf: &mut dyn Write) -> Result<(), Error> {
         let bin_name = cmd
             .get_bin_name()
             .expect("crate::generate should have set the bin_name");
@@ -53,7 +58,6 @@ fi
             subcommands = get_subcommands_of(cmd),
             subcommand_details = subcommand_details(cmd)
         )
-        .expect("failed to write completion file");
     }
 }
 

clap_complete_nushell/src/lib.rs

@@ -36,6 +36,15 @@ impl Generator for Nushell {
     }
 
     fn generate(&self, cmd: &Command, buf: &mut dyn std::io::Write) {
+        self.try_generate(cmd, buf)
+            .expect("failed to write completion file");
+    }
+
+    fn try_generate(
+        &self,
+        cmd: &Command,
+        buf: &mut dyn std::io::Write,
+    ) -> Result<(), std::io::Error> {
         let mut completions = String::new();
 
         completions.push_str("module completions {\n\n");
@@ -50,7 +59,6 @@ impl Generator for Nushell {
         completions.push_str("export use completions *\n");
 
         buf.write_all(completions.as_bytes())
-            .expect("Failed to write to generated file");
     }
 }