other: fix humantime-related documentation, add tests, support numbers + strings in toml (#1220)

* update documentation and support either numerical times or human times for time_delta and default_time_value

* update docs

* give more human times on error

7 files changed, 122 insertions, 74 deletions

diff --git a/docs/content/configuration/command-line-flags.md b/docs/content/configuration/command-line-flags.md
index 1e0af411..cbaf6ee6 100644
--- a/docs/content/configuration/command-line-flags.md
+++ b/docs/content/configuration/command-line-flags.md
@@ -3,45 +3,45 @@
 The following flags can be provided to bottom in the command line to change the behaviour of the program. You can also
 see information on these flags by running `btm -h`, or run `btm --help` to display more detailed information on each flag:
 
-| Flag                                         | Behaviour                                                                            |
-| -------------------------------------------- | ------------------------------------------------------------------------------------ |
-| `--autohide_time`                            | Temporarily shows the time scale in graphs.                                          |
-| `-b`, `--basic`                              | Hides graphs and uses a more basic look.                                             |
-| `--battery`                                  | Shows the battery widget.                                                            |
-| `-S`, `--case_sensitive`                     | Enables case sensitivity by default.                                                 |
-| `-c`, `--celsius`                            | Sets the temperature type to Celsius.                                                |
-| `--color <COLOR SCHEME>`                     | Use a color scheme, use --help for supported values.                                 |
-| `-C <CONFIG PATH>`, `--config <CONFIG PATH>` | Sets the location of the config file.                                                |
-| `-u`, `--current_usage`                      | Sets process CPU% to be based on current CPU%.                                       |
-| `-t <MS>`, `--default_time_value <MS>`       | Default time value for graphs in ms.                                                 |
-| `--default_widget_count <INT>`               | Sets the n'th selected widget type as the default.                                   |
-| `--default_widget_type <WIDGET TYPE>`        | Sets the default widget type, use --help for more info.                              |
-| `--disable_advanced_kill`                    | Hides advanced options to stop a process on Unix-like systems.                       |
-| `--disable_click`                            | Disables mouse clicks.                                                               |
-| `-m`, `--dot_marker`                         | Uses a dot marker for graphs.                                                        |
-| `-f`, `--fahrenheit`                         | Sets the temperature type to Fahrenheit.                                             |
-| `-g`, `--group`                              | Groups processes with the same name by default.                                      |
-| `-h`, `--help`                               | Prints help information. Use --help for more info.                                   |
-| `-a`, `--hide_avg_cpu`                       | Hides the average CPU usage.                                                         |
-| `--hide_table_gap`                           | Hides the spacing between table headers and entries.                                 |
-| `--hide_time`                                | Hides the time scale.                                                                |
-| `-k`, `--kelvin`                             | Sets the temperature type to Kelvin.                                                 |
-| `-l`, `--left_legend`                        | Puts the CPU chart legend to the left side.                                          |
-| `--mem_as_value`                             | Defaults to showing process memory usage by value.                                   |
-| `--network_use_binary_prefix`                | Displays the network widget with binary prefixes.                                    |
-| `--network_use_bytes`                        | Displays the network widget using bytes.                                             |
-| `--network_use_log`                          | Displays the network widget with a log scale.                                        |
-| `--process_command`                          | Show processes as their commands by default.                                         |
-| `-r`, `--rate <MS>`                          | Sets a refresh rate in ms.                                                           |
-| `-R`, `--regex`                              | Enables regex by default.                                                            |
-| `--show_table_scroll_position`               | Shows the scroll position tracker in table widgets.                                  |
-| `-d <MS>`, `--time_delta <MS>`               | The amount in ms changed upon zooming.                                               |
-| `-T`, `--tree`                               | Defaults to showing the process widget in tree mode.                                 |
-| `--use_old_network_legend`                   | DEPRECATED - uses the older network legend.                                          |
-| `-V`, `--version`                            | Prints version information.                                                          |
-| `-W`, `--whole_word`                         | Enables whole-word matching by default.                                              |
-| `--enable_gpu_memory`                        | Enable collecting and displaying GPU memory usage.                                   |
-| `--enable_cache_memory`                      | Enable collecting and displaying cache and buffer memory (not available on Windows). |
-| `--retention`                                | How much data is stored at once in terms of time.                                    |
-| `-n`, `--unnormalized_cpu`                   | Show process CPU% without normalizing over the number of cores.                      |
-| `-e`, `--expanded`                           | Expand the default widget upon starting the app.                                     |
+| Flag                                | Behaviour                                                       |
+| ----------------------------------- | --------------------------------------------------------------- |
+| --autohide_time                     | Temporarily shows the time scale in graphs.                     |
+| -b, --basic                         | Hides graphs and uses a more basic look.                        |
+| --battery                           | Shows the battery widget.                                       |
+| -S, --case_sensitive                | Enables case sensitivity by default.                            |
+| -c, --celsius                       | Sets the temperature type to Celsius.                           |
+| --color <COLOR SCHEME>              | Use a color scheme, use --help for info.                        |
+| -C, --config <CONFIG PATH>          | Sets the location of the config file.                           |
+| -u, --current_usage                 | Sets process CPU% to be based on current CPU%.                  |
+| -t, --default_time_value <TIME>     | Default time value for graphs.                                  |
+| --default_widget_count <INT>        | Sets the n'th selected widget type as the default.              |
+| --default_widget_type <WIDGET TYPE> | Sets the default widget type, use --help for info.              |
+| --disable_advanced_kill             | Hides advanced process killing.                                 |
+| --disable_click                     | Disables mouse clicks.                                          |
+| -m, --dot_marker                    | Uses a dot marker for graphs.                                   |
+| --enable_cache_memory               | Enable collecting and displaying cache and buffer memory.       |
+| --enable_gpu_memory                 | Enable collecting and displaying GPU memory usage.              |
+| -e, --expanded                      | Expand the default widget upon starting the app.                |
+| -f, --fahrenheit                    | Sets the temperature type to Fahrenheit.                        |
+| -g, --group                         | Groups processes with the same name by default.                 |
+| -a, --hide_avg_cpu                  | Hides the average CPU usage.                                    |
+| --hide_table_gap                    | Hides spacing between table headers and entries.                |
+| --hide_time                         | Hides the time scale.                                           |
+| -k, --kelvin                        | Sets the temperature type to Kelvin.                            |
+| -l, --left_legend                   | Puts the CPU chart legend to the left side.                     |
+| --mem_as_value                      | Defaults to showing process memory usage by value.              |
+| --network_use_binary_prefix         | Displays the network widget with binary prefixes.               |
+| --network_use_bytes                 | Displays the network widget using bytes.                        |
+| --network_use_log                   | Displays the network widget with a log scale.                   |
+| --process_command                   | Show processes as their commands by default.                    |
+| -r, --rate <MS>                     | Sets a refresh rate in ms.                                      |
+| -R, --regex                         | Enables regex by default.                                       |
+| --retention <TIME>                  | The timespan of data kept.                                      |
+| --show_table_scroll_position        | Shows the scroll position tracker in table widgets.             |
+| -d, --time_delta <TIME>             | The amount of time changed upon zooming.                        |
+| -T, --tree                          | Defaults the process widget be in tree mode.                    |
+| -n, --unnormalized_cpu              | Show process CPU% without normalizing over the number of cores. |
+| --use_old_network_legend            | DEPRECATED - uses a separate network legend.                    |
+| -V, --version                       | Prints version information.                                     |
+| -W, --whole_word                    | Enables whole-word matching by default.                         |
+| -h, --help                          | Print help (see more with '--help')                             |
diff --git a/docs/content/configuration/config-file/flags.md b/docs/content/configuration/config-file/flags.md
index b3a6362c..fd919bea 100644
--- a/docs/content/configuration/config-file/flags.md
+++ b/docs/content/configuration/config-file/flags.md
@@ -8,7 +8,7 @@ Most of the [command line flags](../../command-line-flags) have config file equi
 each time:
 
 | Field                        | Type                                                                                           | Functionality                                                                        |
-|------------------------------|------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
+| ---------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
 | `hide_avg_cpu`               | Boolean                                                                                        | Hides the average CPU usage.                                                         |
 | `dot_marker`                 | Boolean                                                                                        | Uses a dot marker for graphs.                                                        |
 | `left_legend`                | Boolean                                                                                        | Puts the CPU chart legend to the left side.                                          |
@@ -21,8 +21,8 @@ each time:
 | `use_old_network_legend`     | Boolean                                                                                        | DEPRECATED - uses the older network legend.                                          |
 | `battery`                    | Boolean                                                                                        | Shows the battery widget.                                                            |
 | `rate`                       | Unsigned Int (represents milliseconds)                                                         | Sets a refresh rate in ms.                                                           |
-| `default_time_value`         | Unsigned Int (represents milliseconds)                                                         | Default time value for graphs in ms.                                                 |
-| `time_delta`                 | Unsigned Int (represents milliseconds)                                                         | The amount in ms changed upon zooming.                                               |
+| `default_time_value`         | Unsigned Int (represents milliseconds) or String (represents human time)                       | Default time value for graphs in ms.                                                 |
+| `time_delta`                 | Unsigned Int (represents milliseconds) or String (represents human time)                       | The amount in ms changed upon zooming.                                               |
 | `hide_time`                  | Boolean                                                                                        | Hides the time scale.                                                                |
 | `temperature_type`           | String (one of ["k", "f", "c", "kelvin", "fahrenheit", "celsius"])                             | Sets the temperature unit type.                                                      |
 | `default_widget_type`        | String (one of ["cpu", "proc", "net", "temp", "mem", "disk"], same as layout options)          | Sets the default widget type, use --help for more info.                              |
diff --git a/sample_configs/default_config.toml b/sample_configs/default_config.toml
index e2459762..74353b3c 100644
--- a/sample_configs/default_config.toml
+++ b/sample_configs/default_config.toml
@@ -35,7 +35,7 @@
 #temperature_type = "fahrenheit"
 #temperature_type = "celsius"
 # The default time interval (in milliseconds).
-#default_time_value = 60000
+#default_time_value = "60s"
 # The time delta on each zoom in/out action (in milliseconds).
 #time_delta = 15000
 # Hides the time scale.
@@ -157,7 +157,6 @@
 #    type="proc"
 #    default=true
 
-
 # Filters - you can hide specific temperature sensors, network interfaces, and disks using filters.  This is admittedly
 # a bit hard to use as of now, and there is a planned in-app interface for managing this in the future:
 #[disk_filter]
diff --git a/src/args.rs b/src/args.rs
index 9a715996..87035a6a 100644
--- a/src/args.rs
+++ b/src/args.rs
@@ -88,8 +88,6 @@ pub fn get_matches() -> clap::ArgMatches {
     build_app().get_matches()
 }
 
-// TODO: Refactor this a bit, it's quite messy atm
-// TODO: [DEBUG] Add a proper debugging solution.
 pub fn build_app() -> Command {
     // Temps
     let kelvin = Arg::new("kelvin")
@@ -303,11 +301,13 @@ Defaults to \"default\".
         .short('t')
         .long("default_time_value")
         .action(ArgAction::Set)
-        .value_name("MS")
-        .help("Default time value for graphs in ms.")
-        .long_help("Default time value for graphs in milliseconds. The minimum time is 30s (30000), and the default is 60s (60000).");
+        .value_name("TIME")
+        .help("Default time value for graphs.")
+        .long_help(
+            "Default time value for graphs. The minimum time is 30s, and the default is 60s.",
+        );
 
-    // TODO: Fix this, its broken in the manpage
+    // TODO: Charts are broken in the manpage
     let default_widget_count = Arg::new("default_widget_count")
         .long("default_widget_count")
         .action(ArgAction::Set)
@@ -360,9 +360,9 @@ use CPU (3) as the default instead.
         .short('d')
         .long("time_delta")
         .action(ArgAction::Set)
-        .value_name("MS")
-        .help("The amount in ms changed upon zooming.")
-        .long_help("The amount of time in milliseconds changed when zooming in/out. The minimum is 1s (1000), and defaults to 15s (15000).");
+        .value_name("TIME")
+        .help("The amount of time changed upon zooming.")
+        .long_help("The amount of time changed when zooming in/out. The minimum is 1s, and defaults to 15s.");
 
     let tree = Arg::new("tree")
         .short('T')
@@ -394,7 +394,7 @@ use CPU (3) as the default instead.
     let retention = Arg::new("retention")
         .long("retention")
         .action(ArgAction::Set)
-        .value_name("time")
+        .value_name("TIME")
         .help("The timespan of data kept.")
         .long_help("How much data is stored at once in terms of time. Takes in human-readable time spans (e.g. 10m, 1h), with a minimum of 1 minute. Note higher values will take up more memory. Defaults to 10 minutes.");
 
diff --git a/src/components/data_table/column.rs b/src/components/data_table/column.rs
index 8247a310..e7b82b29 100644
--- a/src/components/data_table/column.rs
+++ b/src/components/data_table/column.rs
@@ -188,7 +188,6 @@ where
 
                     let soft_limit = max(
                         if let Some(max_percentage) = max_percentage {
-                            // TODO: Rust doesn't have an `into()` or `try_into()` for floats to integers.
                             ((*max_percentage * f32::from(total_width)).ceil()) as u16
                         } else {
                             *desired
diff --git a/src/constants.rs b/src/constants.rs
index 9efea3ad..a76c8609 100644
--- a/src/constants.rs
+++ b/src/constants.rs
@@ -543,7 +543,7 @@ pub const CONFIG_TEXT: &str = r##"# This is a default config file for bottom.  A
 #temperature_type = "fahrenheit"
 #temperature_type = "celsius"
 # The default time interval (in milliseconds).
-#default_time_value = 60000
+#default_time_value = "60s"
 # The time delta on each zoom in/out action (in milliseconds).
 #time_delta = 15000
 # Hides the time scale.
diff --git a/src/options.rs b/src/options.rs
index 62243ba2..4a4d15f5 100644
--- a/src/options.rs
+++ b/src/options.rs
@@ -45,6 +45,25 @@ pub struct Config {
     pub processes: Option<ProcessConfig>,
 }
 
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(untagged)]
+enum StringOrNum {
+    String(String),
+    Num(u64),
+}
+
+impl From<String> for StringOrNum {
+    fn from(value: String) -> Self {
+        StringOrNum::String(value)
+    }
+}
+
+impl From<u64> for StringOrNum {
+    fn from(value: u64) -> Self {
+        StringOrNum::Num(value)
+    }
+}
+
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
 pub struct ConfigFlags {
     pub hide_avg_cpu: Option<bool>,
@@ -59,8 +78,8 @@ pub struct ConfigFlags {
     pub whole_word: Option<bool>,
     pub regex: Option<bool>,
     pub basic: Option<bool>,
-    pub default_time_value: Option<String>,
-    pub time_delta: Option<String>,
+    default_time_value: Option<StringOrNum>,
+    time_delta: Option<StringOrNum>,
     pub autohide_time: Option<bool>,
     pub hide_time: Option<bool>,
     pub default_widget_type: Option<String>,
@@ -615,7 +634,10 @@ fn get_default_time_value(
             try_parse_ms(default_time_value)?
         } else if let Some(flags) = &config.flags {
             if let Some(default_time_value) = &flags.default_time_value {
-                try_parse_ms(default_time_value)?
+                match default_time_value {
+                    StringOrNum::String(s) => try_parse_ms(s)?,
+                    StringOrNum::Num(n) => *n,
+                }
             } else {
                 DEFAULT_TIME_MILLISECONDS
             }
@@ -625,12 +647,12 @@ fn get_default_time_value(
 
     if default_time < 30000 {
         return Err(BottomError::ConfigError(
-            "set your default value to be at least 30000 milliseconds.".to_string(),
+            "set your default value to be at least 30s.".to_string(),
         ));
     } else if default_time > retention_ms {
         return Err(BottomError::ConfigError(format!(
-            "set your default value to be at most {} milliseconds.",
-            retention_ms
+            "set your default value to be at most {}.",
+            humantime::Duration::from(Duration::from_millis(retention_ms))
         )));
     }
 
@@ -644,7 +666,10 @@ fn get_time_interval(
         try_parse_ms(time_interval)?
     } else if let Some(flags) = &config.flags {
         if let Some(time_interval) = &flags.time_delta {
-            try_parse_ms(time_interval)?
+            match time_interval {
+                StringOrNum::String(s) => try_parse_ms(s)?,
+                StringOrNum::Num(n) => *n,
+            }
         } else {
             TIME_CHANGE_MILLISECONDS
         }
@@ -654,12 +679,12 @@ fn get_time_interval(
 
     if time_interval < 1000 {
         return Err(BottomError::ConfigError(
-            "set your time delta to be at least 1000 milliseconds.".to_string(),
+            "set your time delta to be at least 1s.".to_string(),
         ));
     } else if time_interval > retention_ms {
         return Err(BottomError::ConfigError(format!(
-            "set your time delta to be at most {} milliseconds.",
-            retention_ms
+            "set your time delta to be at most {}.",
+            humantime::Duration::from(Duration::from_millis(retention_ms))
         )));
     }
 
@@ -972,8 +997,33 @@ mod test {
 
         let mut config = Config::default();
         let flags = ConfigFlags {
-            time_delta: Some("2 min".to_string()),
-            default_time_value: Some("300s".to_string()),
+            time_delta: Some("2 min".to_string().into()),
+            default_time_value: Some("300s".to_string().into()),
+            ..Default::default()
+        };
+
+        config.flags = Some(flags);
+
+        assert_eq!(
+            get_time_interval(&matches, &config, 60 * 60 * 1000),
+            Ok(2 * 60 * 1000)
+        );
+
+        assert_eq!(
+            get_default_time_value(&matches, &config, 60 * 60 * 1000),
+            Ok(5 * 60 * 1000)
+        );
+    }
+
+    #[test]
+    fn config_number_times_as_string() {
+        let app = crate::args::build_app();
+        let matches = app.get_matches_from(["btm"]);
+
+        let mut config = Config::default();
+        let flags = ConfigFlags {
+            time_delta: Some("120000".to_string().into()),
+            default_time_value: Some("300000".to_string().into()),
             ..Default::default()
         };
 
@@ -991,14 +1041,14 @@ mod test {
     }
 
     #[test]
-    fn config_number_times() {
+    fn config_number_times_as_num() {
         let app = crate::args::build_app();
         let matches = app.get_matches_from(["btm"]);
 
         let mut config = Config::default();
         let flags = ConfigFlags {
-            time_delta: Some("120000".to_string()),
-            default_time_value: Some("300000".to_string()),
+            time_delta: Some(120000.into()),
+            default_time_value: Some(300000.into()),
             ..Default::default()
         };