feat(catalog): better list cli API

src/config.rs

@@ -11,21 +11,32 @@ use crate::management::{backup::BackupStatus, compaction::Strategy};
 /// Catalog subcommands.
 #[derive(Debug, Subcommand)]
 pub enum CatalogSubcommand {
-    /// List backups in the catalog to stdout.
+    /// Print a list of backups to stdout.
     ///
-    /// If `--only disposable` or `--only retainable` are passed, print the corresponding list of
-    /// paths, otherwise print all backups in a table format.
+    /// By default, this prints a table of backups, age and status with colors. The flag `--details`
+    /// prints additional columns.
+    ///
+    /// If the flag `--filepaths` is set, only absolute filepaths are printed. This can be used in
+    /// scripting scenarios.
+    ///
+    /// Options `--only disposable` or `--only retainable` will list only the corresponding backups.
+    /// They will activate the flag `--filepaths` automatically.
     List {
-        /// List only backups having this status.
-        #[clap(long = "only", value_enum, value_parser)]
-        backup_status: Option<BackupStatus>,
-
-        /// Print additional details (slower)
+        /// Add details columns to the table.
         ///
         /// Print number of sessions, windows and panes in the backup and the backup's format
-        /// version. This requires each backup file to be partially read.
+        /// version. This is slightly slower because it requires each backup file to be partially
+        /// read.
         #[clap(long = "details", action = ArgAction::SetTrue)]
         details_flag: bool,
+
+        /// List only backups having this status.
+        #[clap(long = "only", value_enum, value_parser)]
+        only_backup_status: Option<BackupStatus>,
+
+        /// Print filepaths instead of the table format.
+        #[clap(long = "filepaths", action = ArgAction::SetTrue)]
+        filepaths_flag: bool,
     },
     /// Delete disposable backups by applying the catalog's compaction strategy.
     Compact,

src/main.rs

@@ -31,9 +31,14 @@ async fn run(config: Config) {
     match config.command {
         Command::Catalog { command } => match command {
             CatalogSubcommand::List {
-                backup_status,
                 details_flag,
-            } => catalog.list(backup_status, details_flag).await,
+                only_backup_status,
+                filepaths_flag,
+            } => {
+                catalog
+                    .list(details_flag, only_backup_status, filepaths_flag)
+                    .await
+            }
             CatalogSubcommand::Compact => match catalog.compact().await {
                 Ok(n) => {
                     let message = format!("✅ deleted {n} outdated backups");

src/management/catalog.rs

@@ -129,37 +129,49 @@ impl Catalog {
 
     /// List backups.
     ///
-    /// If a specific backup status is passed (`status` is `Some(..)`), then the function prints
-    /// only the absolute paths of the corresponding backups, otherwise it prints a
-    /// Docker/Podman-like table.
-    ///
-    /// If `details_flag` is `true`, the function prints an overview of the content of the
-    /// backup:
+    /// By default, this prints a table of backups, age and status with colors. If `details_flag`
+    /// is `true`, the table has additional columns:
     ///
     /// - version of the archive's format
     /// - number of sessions
     /// - number of windows
     /// - number of panes
     ///
-    /// but this is slower because it needs to read partially each backup file.
-    pub async fn list(&self, status: Option<BackupStatus>, details_flag: bool) {
-        if let Some(status) = status {
-            match status {
-                BackupStatus::Disposable => {
+    /// but this requires to read partially each backup file.
+    ///
+    /// If `filepaths_flag` is `true`, only absolute filepaths are printed. This can be used in
+    /// scripting scenarios.
+    ///
+    /// If `only_status` is a `Some(..)`, this lists only the corresponding backup filepaths,
+    /// acting as if `filepaths_flag` is `true`.
+    pub async fn list(
+        &self,
+        details_flag: bool,
+        only_status: Option<BackupStatus>,
+        filepaths_flag: bool,
+    ) {
+        if filepaths_flag || only_status.is_some() {
+            match only_status {
+                Some(BackupStatus::Disposable) => {
                     let Plan { disposable, .. } = self.plan();
-                    for backup in disposable.iter() {
+                    for backup in disposable {
                         println!("{}", backup.filepath.to_string_lossy());
                     }
                 }
-                BackupStatus::Retainable => {
+                Some(BackupStatus::Retainable) => {
                     let Plan { retainable, .. } = self.plan();
-                    for backup in retainable.iter() {
+                    for backup in retainable {
+                        println!("{}", backup.filepath.to_string_lossy());
+                    }
+                }
+                None => {
+                    for backup in self.backups.iter() {
                         println!("{}", backup.filepath.to_string_lossy());
                     }
                 }
             }
         } else {
-            self.full_list(details_flag).await;
+            self.print_table(details_flag).await;
         }
     }
 }
@@ -250,7 +262,7 @@ impl Catalog {
         format!("{} seconds ago", duration_secs)
     }
 
-    async fn full_list(&self, details_flag: bool) {
+    async fn print_table(&self, details_flag: bool) {
         println!("Strategy: {}", &self.strategy);
         println!("Location: `{}`\n", self.dirpath.to_string_lossy());