fix(jobs): Add the symbol and number thresholds respecting the `thres…

…hold` option (starship#2908)

* feat: Add the symbol and number thresholds respecting the threshold option

* fix: Maintain the old behavior + add lots of tests

* docs: Fix the jobs module documentation

docs/config/README.md

@@ -1551,25 +1551,46 @@ symbol = "🌟 "
 
 The `jobs` module shows the current number of jobs running.
 The module will be shown only if there are background jobs running.
-The module will show the number of jobs running if there is more than 1 job, or
-more than the `threshold` config value, if it exists. If `threshold` is set to 0,
-then the module will also show when there are 0 jobs running.
+The module will show the number of jobs running if there are at least
+2 jobs, or more than the `number_threshold` config value, if it exists.
+The module will show a symbol if there is at least 1 job, or more than the
+`symbol_threshold` config value, if it exists. You can set both values
+to 0 in order to *always* show the symbol and number of jobs, even if there are
+0 jobs running.
+
+The default functionality is:
+
+- 0 jobs -> Nothing is shown.
+- 1 job -> `symbol` is shown.
+- 2 jobs or more -> `symbol` + `number` are shown.
 
 ::: warning
 
 This module is not supported on tcsh and nu.
 
 :::
 
+::: warning
+
+The `threshold` option is deprecated, but if you want to use it,
+the module will show the number of jobs running if there is more than 1 job, or
+more than the `threshold` config value, if it exists. If `threshold` is set to 0,
+then the module will also show when there are 0 jobs running.
+
+:::
+
 ### Options
 
-| Option      | Default                       | Description                                      |
-| ----------- | ----------------------------- | ------------------------------------------------ |
-| `threshold` | `1`                           | Show number of jobs if exceeded.                 |
-| `format`    | `"[$symbol$number]($style) "` | The format for the module.                       |
-| `symbol`    | `"✦"`                         | A format string representing the number of jobs. |
-| `style`     | `"bold blue"`                 | The style for the module.                        |
-| `disabled`  | `false`                       | Disables the `jobs` module.                      |
+| Option             | Default                       | Description                                                                                 |
+| -----------        | ----------------------------- | ------------------------------------------------                                            |
+| `threshold`\*      | `1`                           | Show number of jobs if exceeded.                                                            |
+| `symbol_threshold` | `1`                           | Show `symbol` if the job count is at least `symbol_threshold`.                              |
+| `number_threshold` | `2`                           | Show the number of jobs if the job count is at least `number_threshold`.                    |
+| `format`           | `"[$symbol$number]($style) "` | The format for the module.                                                                  |
+| `symbol`           | `"✦"`                         | The string used to represent the `symbol` variable.                                         |
+| `style`            | `"bold blue"`                 | The style for the module.                                                                   |
+| `disabled`         | `false`                       | Disables the `jobs` module.                                                                 |
+\*: This option is deprecated, please use the `number_threshold` and `symbol_threshold` options instead.
 
 ### Variables
 
@@ -1588,7 +1609,8 @@ This module is not supported on tcsh and nu.
 
 [jobs]
 symbol = "+ "
-threshold = 4
+number_threshold = 4
+symbol_threshold = 0
 ```
 
 ## Julia

src/configs/jobs.rs

@@ -6,6 +6,8 @@ use starship_module_config_derive::ModuleConfig;
 #[derive(Clone, ModuleConfig, Serialize)]
 pub struct JobsConfig<'a> {
     pub threshold: i64,
+    pub symbol_threshold: i64,
+    pub number_threshold: i64,
     pub format: &'a str,
     pub symbol: &'a str,
     pub style: &'a str,
@@ -16,6 +18,8 @@ impl<'a> Default for JobsConfig<'a> {
     fn default() -> Self {
         JobsConfig {
             threshold: 1,
+            symbol_threshold: 1,
+            number_threshold: 2,
             format: "[$symbol$number]($style) ",
             symbol: "✦",
             style: "bold blue",

src/modules/jobs.rs

@@ -8,6 +8,30 @@ pub fn module<'a>(context: &'a Context) -> Option<Module<'a>> {
     let mut module = context.new_module("jobs");
     let config = JobsConfig::try_load(module.config);
 
+    if config.threshold < 0 {
+        log::warn!(
+            "threshold in [jobs] ({}) was less than zero",
+            config.threshold
+        );
+        return None;
+    }
+
+    if config.symbol_threshold < 0 {
+        log::warn!(
+            "symbol_threshold in [jobs] ({}) was less than zero",
+            config.symbol_threshold
+        );
+        return None;
+    }
+
+    if config.number_threshold < 0 {
+        log::warn!(
+            "number_threshold in [jobs] ({}) was less than zero",
+            config.number_threshold
+        );
+        return None;
+    }
+
     let props = &context.properties;
     let num_of_jobs = props
         .get("jobs")
@@ -16,28 +40,44 @@ pub fn module<'a>(context: &'a Context) -> Option<Module<'a>> {
         .parse::<i64>()
         .ok()?;
 
-    if config.threshold < 0 {
-        log::warn!(
-            "threshold in [jobs] ({}) was less than zero",
-            config.threshold
-        );
+    if num_of_jobs == 0
+        && config.threshold > 0
+        && config.number_threshold > 0
+        && config.symbol_threshold > 0
+    {
         return None;
     }
 
-    if num_of_jobs == 0 && config.threshold > 0 {
-        return None;
-    }
+    let default_threshold = 1;
+    let mut module_symbol = "";
+    let mut module_number = String::new();
+    if config.threshold != default_threshold {
+        log::warn!("`threshold` in [jobs] is deprecated . Please remove it and use `symbol_threshold` and `number_threshold`.");
+
+        // The symbol should be shown if there are *any* background
+        // jobs running.
+        if num_of_jobs > 0 {
+            module_symbol = config.symbol;
+        }
 
-    let module_number = if num_of_jobs > config.threshold || config.threshold == 0 {
-        num_of_jobs.to_string()
+        if num_of_jobs > config.threshold || config.threshold == 0 {
+            module_symbol = config.symbol;
+            module_number = num_of_jobs.to_string();
+        }
     } else {
-        "".to_string()
-    };
+        if num_of_jobs >= config.symbol_threshold {
+            module_symbol = config.symbol;
+        }
+
+        if num_of_jobs >= config.number_threshold {
+            module_number = num_of_jobs.to_string();
+        }
+    }
 
     let parsed = StringFormatter::new(config.format).and_then(|formatter| {
         formatter
             .map_meta(|var, _| match var {
-                "symbol" => Some(config.symbol),
+                "symbol" => Some(module_symbol),
                 _ => None,
             })
             .map_style(|variable| match variable {
@@ -91,6 +131,96 @@ mod test {
         assert_eq!(expected, actual);
     }
 
+    #[test]
+    fn config_default_is_present_jobs_1() {
+        let actual = ModuleRenderer::new("jobs")
+            .config(toml::toml! {
+                [jobs]
+                threshold = 1
+            })
+            .jobs(1)
+            .collect();
+
+        let expected = Some(format!("{} ", Color::Blue.bold().paint("✦")));
+        assert_eq!(expected, actual);
+    }
+
+    #[test]
+    fn config_default_is_present_jobs_2() {
+        let actual = ModuleRenderer::new("jobs")
+            .config(toml::toml! {
+                [jobs]
+                threshold = 1
+            })
+            .jobs(2)
+            .collect();
+
+        let expected = Some(format!("{} ", Color::Blue.bold().paint("✦2")));
+        assert_eq!(expected, actual);
+    }
+
+    #[test]
+    fn config_conflicting_thresholds_default_jobs_1() {
+        let actual = ModuleRenderer::new("jobs")
+            .config(toml::toml! {
+                [jobs]
+                threshold = 1
+                number_threshold = 2
+            })
+            .jobs(1)
+            .collect();
+
+        let expected = Some(format!("{} ", Color::Blue.bold().paint("✦")));
+        assert_eq!(expected, actual);
+    }
+
+    #[test]
+    fn config_conflicting_thresholds_default_no_symbol_jobs_1() {
+        let actual = ModuleRenderer::new("jobs")
+            .config(toml::toml! {
+                [jobs]
+                threshold = 1
+                symbol_threshold = 0
+                number_threshold = 2
+            })
+            .jobs(1)
+            .collect();
+
+        let expected = Some(format!("{} ", Color::Blue.bold().paint("✦")));
+        assert_eq!(expected, actual);
+    }
+
+    #[test]
+    fn config_conflicting_thresholds_no_symbol_jobs_1() {
+        let actual = ModuleRenderer::new("jobs")
+            .config(toml::toml! {
+                [jobs]
+                threshold = 0
+                symbol_threshold = 0
+                number_threshold = 2
+            })
+            .jobs(1)
+            .collect();
+
+        let expected = Some(format!("{} ", Color::Blue.bold().paint("✦1")));
+        assert_eq!(expected, actual);
+    }
+
+    #[test]
+    fn config_conflicting_thresholds_jobs_2() {
+        let actual = ModuleRenderer::new("jobs")
+            .config(toml::toml! {
+                [jobs]
+                threshold = 1
+                number_threshold = 2
+            })
+            .jobs(2)
+            .collect();
+
+        let expected = Some(format!("{} ", Color::Blue.bold().paint("✦2")));
+        assert_eq!(expected, actual);
+    }
+
     #[test]
     fn config_2_job_2() {
         let actual = ModuleRenderer::new("jobs")
@@ -105,6 +235,35 @@ mod test {
         assert_eq!(expected, actual);
     }
 
+    #[test]
+    fn config_number_2_job_2() {
+        let actual = ModuleRenderer::new("jobs")
+            .config(toml::toml! {
+                [jobs]
+                number_threshold = 2
+            })
+            .jobs(2)
+            .collect();
+
+        let expected = Some(format!("{} ", Color::Blue.bold().paint("✦2")));
+        assert_eq!(expected, actual);
+    }
+
+    #[test]
+    fn config_number_2_symbol_3_job_2() {
+        let actual = ModuleRenderer::new("jobs")
+            .config(toml::toml! {
+                [jobs]
+                number_threshold = 2
+                symbol_threshold = 3
+            })
+            .jobs(2)
+            .collect();
+
+        let expected = Some(format!("{} ", Color::Blue.bold().paint("2")));
+        assert_eq!(expected, actual);
+    }
+
     #[test]
     fn config_2_job_3() {
         let actual = ModuleRenderer::new("jobs")
@@ -119,6 +278,36 @@ mod test {
         assert_eq!(expected, actual);
     }
 
+    #[test]
+    fn config_thresholds_0_jobs_0() {
+        let actual = ModuleRenderer::new("jobs")
+            .config(toml::toml! {
+                [jobs]
+                number_threshold = 0
+                symbol_threshold = 0
+            })
+            .jobs(0)
+            .collect();
+
+        let expected = Some(format!("{} ", Color::Blue.bold().paint("✦0")));
+        assert_eq!(expected, actual);
+    }
+
+    #[test]
+    fn config_thresholds_0_jobs_1() {
+        let actual = ModuleRenderer::new("jobs")
+            .config(toml::toml! {
+                [jobs]
+                number_threshold = 0
+                symbol_threshold = 0
+            })
+            .jobs(1)
+            .collect();
+
+        let expected = Some(format!("{} ", Color::Blue.bold().paint("✦1")));
+        assert_eq!(expected, actual);
+    }
+
     #[test]
     fn config_0_job_0() {
         let actual = ModuleRenderer::new("jobs")