diff options
author | Clement Tsang <34804052+ClementTsang@users.noreply.github.com> | 2023-06-24 05:36:36 +0000 |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-06-24 01:36:36 -0400 |
commit | 4ac3b432602259efbd79efefbd016eebb7966675 (patch) | |
tree | 16a7c6f0e4e5ae8f6838f6fe8c7e01e82030aea6 | |
parent | cc3833289fa5063efe30c2a16da56a9b04117e1b (diff) |
docs: update time-related documentation (#1222)
* docs: update time-related documentation
* fix retention too
-rw-r--r-- | docs/content/configuration/command-line-flags.md | 84 | ||||
-rw-r--r-- | docs/content/configuration/config-file/flags.md | 2 | ||||
-rw-r--r-- | sample_configs/default_config.toml | 2 | ||||
-rw-r--r-- | src/args.rs | 16 | ||||
-rw-r--r-- | src/options.rs | 32 |
5 files changed, 73 insertions, 63 deletions
diff --git a/docs/content/configuration/command-line-flags.md b/docs/content/configuration/command-line-flags.md index cbaf6ee6..e0a7192f 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 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') | +| 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 <TIME> | Sets the data refresh rate. | +| -R, --regex | Enables regex by default. | +| --retention <TIME> | The timespan of data stored. | +| --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% usage 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 fd919bea..d5466041 100644 --- a/docs/content/configuration/config-file/flags.md +++ b/docs/content/configuration/config-file/flags.md @@ -20,7 +20,7 @@ each time: | `basic` | Boolean | Hides graphs and uses a more basic look. | | `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. | +| `rate` | Unsigned Int (represents milliseconds) or String (represents human time) | Sets a refresh rate in ms. | | `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. | diff --git a/sample_configs/default_config.toml b/sample_configs/default_config.toml index 74353b3c..e7b4058e 100644 --- a/sample_configs/default_config.toml +++ b/sample_configs/default_config.toml @@ -12,7 +12,7 @@ # Whether to use dot markers rather than braille. #dot_marker = false # The update rate of the application. -#rate = 1000 +#rate = "1s" # Whether to put the CPU legend to the left. #left_legend = false # Whether to set CPU% on a process to be based on the total CPU or just current usage. diff --git a/src/args.rs b/src/args.rs index b384acc0..88cfe3fb 100644 --- a/src/args.rs +++ b/src/args.rs @@ -149,9 +149,9 @@ pub fn build_app() -> Command { .short('n') .long("unnormalized_cpu") .action(ArgAction::SetTrue) - .help("Show process CPU% without normalizing over the number of cores.") + .help("Show process CPU% usage without normalizing over the number of cores.") .long_help( - "Shows process CPU usage without averaging over the number of CPU cores in the system.", + "Shows all process CPU% usage without averaging over the number of CPU cores in the system.", ); let disable_click = Arg::new("disable_click") @@ -304,7 +304,7 @@ Defaults to \"default\". .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.", + "Default time value for graphs. Takes a number in milliseconds or a human duration (e.g. 60s). The minimum time is 30s, and the default is 60s.", ); // TODO: Charts are broken in the manpage @@ -352,9 +352,9 @@ use CPU (3) as the default instead. .short('r') .long("rate") .action(ArgAction::Set) - .value_name("MS") + .value_name("TIME") .help("Sets the data refresh rate.") - .long_help("Sets the data refresh rate. The minimum is 250ms, and defaults to 1000ms. Smaller values may take more computer resources."); + .long_help("Sets the data refresh rate. Takes a number in milliseconds or a human duration (e.g. 5s). The minimum is 250ms, and defaults to 1000ms. Smaller values may take more computer resources."); let time_delta = Arg::new("time_delta") .short('d') @@ -362,7 +362,7 @@ use CPU (3) as the default instead. .action(ArgAction::Set) .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."); + .long_help("The amount of time changed when zooming in/out. Takes a number in milliseconds or a human duration (e.g. 30s). The minimum is 1s, and defaults to 15s."); let tree = Arg::new("tree") .short('T') @@ -395,8 +395,8 @@ use CPU (3) as the default instead. .long("retention") .action(ArgAction::Set) .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."); + .help("The timespan of data stored.") + .long_help("How much data is stored at once in terms of time. Takes a number in milliseconds or a human duration (e.g. 20m), with a minimum of 1 minute. Note higher values will take up more memory. Defaults to 10 minutes."); let version = Arg::new("version") .short('V') diff --git a/src/options.rs b/src/options.rs index 412748a6..26b21d7f 100644 --- a/src/options.rs +++ b/src/options.rs @@ -102,9 +102,7 @@ pub struct ConfigFlags { network_use_binary_prefix: Option<bool>, enable_gpu_memory: Option<bool>, enable_cache_memory: Option<bool>, - #[serde(with = "humantime_serde")] - #[serde(default)] - retention: Option<Duration>, + retention: Option<StringOrNum>, } #[derive(Clone, Debug, Default, Deserialize, Serialize)] @@ -200,7 +198,7 @@ pub fn build_app( let config = &config; let retention_ms = - get_retention_ms(matches, config).context("Update `retention` in your config file.")?; + get_retention(matches, config).context("Update `retention` in your config file.")?; let autohide_time = is_flag_enabled!(autohide_time, matches, config); let default_time_value = get_default_time_value(matches, config, retention_ms) .context("Update 'default_time_value' in your config file.")?; @@ -887,16 +885,17 @@ fn get_network_scale_type(matches: &ArgMatches, config: &Config) -> AxisScaling AxisScaling::Linear } -fn get_retention_ms(matches: &ArgMatches, config: &Config) -> error::Result<u64> { +fn get_retention(matches: &ArgMatches, config: &Config) -> error::Result<u64> { const DEFAULT_RETENTION_MS: u64 = 600 * 1000; // Keep 10 minutes of data. if let Some(retention) = matches.get_one::<String>("retention") { - humantime::parse_duration(retention) - .map(|dur| dur.as_millis() as u64) - .map_err(|err| BottomError::ConfigError(format!("invalid retention duration: {err:?}"))) + try_parse_ms(retention) } else if let Some(flags) = &config.flags { - if let Some(retention) = flags.retention { - Ok(retention.as_millis() as u64) + if let Some(retention) = &flags.retention { + Ok(match retention { + StringOrNum::String(s) => try_parse_ms(s)?, + StringOrNum::Num(n) => *n, + }) } else { Ok(DEFAULT_RETENTION_MS) } @@ -913,7 +912,9 @@ mod test { use crate::{ app::App, canvas::canvas_styling::CanvasStyling, - options::{get_default_time_value, get_update_rate, try_parse_ms, ConfigFlags}, + options::{ + get_default_time_value, get_retention, get_update_rate, try_parse_ms, ConfigFlags, + }, }; #[test] @@ -999,6 +1000,7 @@ mod test { time_delta: Some("2 min".to_string().into()), default_time_value: Some("300s".to_string().into()), rate: Some("1s".to_string().into()), + retention: Some("10m".to_string().into()), ..Default::default() }; @@ -1015,6 +1017,8 @@ mod test { ); assert_eq!(get_update_rate(&matches, &config), Ok(1000)); + + assert_eq!(get_retention(&matches, &config), Ok(600000)); } #[test] @@ -1027,6 +1031,7 @@ mod test { time_delta: Some("120000".to_string().into()), default_time_value: Some("300000".to_string().into()), rate: Some("1000".to_string().into()), + retention: Some("600000".to_string().into()), ..Default::default() }; @@ -1043,6 +1048,8 @@ mod test { ); assert_eq!(get_update_rate(&matches, &config), Ok(1000)); + + assert_eq!(get_retention(&matches, &config), Ok(600000)); } #[test] @@ -1055,6 +1062,7 @@ mod test { time_delta: Some(120000.into()), default_time_value: Some(300000.into()), rate: Some(1000.into()), + retention: Some(600000.into()), ..Default::default() }; @@ -1071,6 +1079,8 @@ mod test { ); assert_eq!(get_update_rate(&matches, &config), Ok(1000)); + + assert_eq!(get_retention(&matches, &config), Ok(600000)); } fn create_app(config: Config, matches: ArgMatches) -> App { |