Respect PAGER env var when paging in uv help command

crates/uv/src/commands/help.rs

@@ -1,4 +1,6 @@
-use std::ffi::OsStr;
+use std::ffi::OsString;
+use std::path::PathBuf;
+use std::str::FromStr;
 use std::{fmt::Display, fmt::Write};
 
 use anstream::{stream::IsTerminal, ColorChoice};
@@ -71,13 +73,16 @@ pub(crate) fn help(query: &[String], printer: Printer, no_pager: bool) -> Result
     let should_page = !no_pager && !is_root && is_terminal;
 
     if should_page {
-        if let Ok(less) = which("less") {
-            // When using less, we use the command name as the file name and can support colors
-            let prompt = format!("help: uv {}", query.join(" "));
-            spawn_pager(less, &["-R", "-P", &prompt], &help_ansi)?;
-        } else if let Ok(more) = which("more") {
-            // When using more, we skip the ANSI color codes
-            spawn_pager(more, &[], &help)?;
+        if let Some(pager) = Pager::try_from_env() {
+            let content = if pager.supports_colors() {
+                help_ansi
+            } else {
+                Either::Right(help.clone())
+            };
+            pager.spawn(
+                format!("{}: {}", "uv help".bold(), query.join(" ")),
+                &content,
+            )?;
         } else {
             writeln!(printer.stdout(), "{help_ansi}")?;
         }
@@ -103,25 +108,141 @@ fn find_command<'a>(
     find_command(&query[1..], subcommand)
 }
 
-/// Spawn a paging command to display contents.
-fn spawn_pager(command: impl AsRef<OsStr>, args: &[&str], contents: impl Display) -> Result<()> {
-    use std::io::Write;
+#[derive(Debug)]
+enum PagerKind {
+    Less,
+    More,
+    Other(String),
+}
+
+#[derive(Debug)]
+struct Pager {
+    kind: PagerKind,
+    args: Vec<String>,
+    path: Option<PathBuf>,
+}
+
+impl PagerKind {
+    fn default_args(&self, prompt: String) -> Vec<String> {
+        match self {
+            Self::Less => vec!["-R".to_string(), "-P".to_string(), prompt],
+            Self::More => vec![],
+            Self::Other(_) => vec![],
+        }
+    }
+}
+
+impl std::fmt::Display for PagerKind {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Less => write!(f, "less"),
+            Self::More => write!(f, "more"),
+            Self::Other(name) => write!(f, "{name}"),
+        }
+    }
+}
+
+impl FromStr for Pager {
+    type Err = ();
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let mut split = s.split_ascii_whitespace();
+
+        // Empty string
+        let Some(first) = split.next() else {
+            return Err(());
+        };
+
+        match first {
+            "less" => Ok(Self {
+                kind: PagerKind::Less,
+                args: split.map(str::to_string).collect(),
+                path: None,
+            }),
+            "more" => Ok(Self {
+                kind: PagerKind::More,
+                args: split.map(str::to_string).collect(),
+                path: None,
+            }),
+            _ => Ok(Self {
+                kind: PagerKind::Other(first.to_string()),
+                args: split.map(str::to_string).collect(),
+                path: None,
+            }),
+        }
+    }
+}
+
+impl Pager {
+    /// Display `contents` using the pager.
+    fn spawn(self, prompt: String, contents: impl Display) -> Result<()> {
+        use std::io::Write;
+
+        let command = self
+            .path
+            .as_ref()
+            .map(|path| path.as_os_str().to_os_string())
+            .unwrap_or(OsString::from(self.kind.to_string()));
+
+        let args = if self.args.is_empty() {
+            self.kind.default_args(prompt)
+        } else {
+            self.args
+        };
 
-    let mut child = std::process::Command::new(command)
-        .args(args)
-        .stdin(std::process::Stdio::piped())
-        .spawn()?;
+        let mut child = std::process::Command::new(command)
+            .args(args)
+            .stdin(std::process::Stdio::piped())
+            .spawn()?;
 
-    let mut stdin = child
-        .stdin
-        .take()
-        .ok_or_else(|| anyhow!("Failed to take child process stdin"))?;
+        let mut stdin = child
+            .stdin
+            .take()
+            .ok_or_else(|| anyhow!("Failed to take child process stdin"))?;
 
-    let contents = contents.to_string();
-    let writer = std::thread::spawn(move || stdin.write_all(contents.as_bytes()));
+        let contents = contents.to_string();
+        let writer = std::thread::spawn(move || stdin.write_all(contents.as_bytes()));
 
-    drop(child.wait());
-    drop(writer.join());
+        drop(child.wait());
+        drop(writer.join());
 
-    Ok(())
+        Ok(())
+    }
+
+    /// Get a pager to use and its path, if available.
+    ///
+    /// Supports the `PAGER` environment variable, otherwise checks for `less` and `more` in the
+    /// search path.
+    fn try_from_env() -> Option<Pager> {
+        if let Some(pager) = std::env::var_os("PAGER") {
+            if !pager.is_empty() {
+                return Pager::from_str(&pager.to_string_lossy()).ok();
+            }
+        }
+
+        if let Ok(less) = which("less") {
+            Some(Pager {
+                kind: PagerKind::Less,
+                args: vec![],
+                path: Some(less),
+            })
+        } else if let Ok(more) = which("more") {
+            Some(Pager {
+                kind: PagerKind::More,
+                args: vec![],
+                path: Some(more),
+            })
+        } else {
+            None
+        }
+    }
+
+    fn supports_colors(&self) -> bool {
+        match self.kind {
+            // The `-R` flag is required for color support. We will provide it by default.
+            PagerKind::Less => self.args.is_empty() || self.args.iter().any(|arg| arg == "-R"),
+            PagerKind::More => false,
+            PagerKind::Other(_) => false,
+        }
+    }
 }