docs: update with search details

2025-04-08 17:05:59 +02:00 · 2020-05-02 23:46:07 -04:00 · 2020-05-02 23:46:07 -04:00 · 73c16e259d
commit 73c16e259d
parent 8307b06c56
9 changed files with 117 additions and 22 deletions
--- a/README.md
+++ b/README.md
@ -32,8 +32,13 @@ A cross-platform graphical process/system monitor with a customizable interface
  - [Process bindings](#process-bindings)
  - [Process search bindings](#process-search-bindings)
  - [Battery bindings](#battery-bindings)
+  - [Process searching keywords](#process-searching-keywords)
+    - [Supported keywords](#supported-keywords)
+    - [Supported comparison operators](#supported-comparison-operators)
+    - [Supported logical operators](#supported-logical-operators)
+    - [Supported units](#supported-units)
 - [Features](#features)
-  - [Process filtering](#process-filtering)
+  - [Process searching](#process-searching)
  - [Zoom](#zoom)
  - [Expanding](#expanding)
  - [Basic mode](#basic-mode)
@ -231,6 +236,53 @@ Run using `btm`.
 | `Left, Alt-h`  | Go to the next battery     |
 | `Right, Alt-l` | Go to the previous battery |

+### Process searching keywords
+
+Note none of the keywords are case sensitive. Furthermore, if you want to search a reserved keyword, surround the text in quotes - for example, `"And" or "Or"` would be a valid search.
+
+#### Supported keywords
+
+|          |                 |                                                                                 |
+| -------- | --------------- | ------------------------------------------------------------------------------- |
+| `pid`    | `pid: 1044`     | Matches by PID; supports regex and requiring matching the entire PID            |
+| `cpu`    | `cpu > 0.5`     | Matches the condition for the CPU column; supports comparison operators         |
+| `mem`    | `mem < 0.5`     | Matches the condition for the memory column; supports comparison operators      |
+| `read`   | `read = 1`      | Matches the condition for the read/s column; supports comparison operators      |
+| `write`  | `write >= 1`    | Matches the condition for the write/s column; supports comparison operators     |
+| `tread`  | `tread <= 1024` | Matches the condition for the total read column; supports comparison operators  |
+| `twrite` | `twrite > 1024` | Matches the condition for the total write column; supports comparison operators |
+
+#### Supported comparison operators
+
+|      |                                                                |
+| ---- | -------------------------------------------------------------- |
+| `=`  | Checks if the values are equal                                 |
+| `>`  | Checks if the left value is strictly greater than the right    |
+| `<`  | Checks if the left value is strictly less than the right       |
+| `>=` | Checks if the left value is greater than or equal to the right |
+| `<=` | Checks if the left value is less than or equal to the right    |
+
+#### Supported logical operators
+
+|                    |                                              |                                                         |
+| ------------------ | -------------------------------------------- | ------------------------------------------------------- |
+| `and, &&, <Space>` | `<CONDITION 1> and/&&/<Space> <CONDITION 2>` | Will require both conditions to be true to match        |
+| `or, ||`           | `<CONDITION 1> or/|| <CONDITION 2>`          | Will require at least one condition to be true to match |
+
+#### Supported units
+
+|       |           |
+| ----- | --------- |
+| `B`   | Bytes     |
+| `KB`  | Kilobytes |
+| `MB`  | Megabytes |
+| `GB`  | Gigabytes |
+| `TB`  | Terabytes |
+| `KiB` | Kibibytes |
+| `MiB` | Mebibytes |
+| `GiB` | Gibibytes |
+| `TiB` | Tebibytes |
+
 ## Features

 As yet _another_ process/system visualization and management application, bottom supports the typical features:
@ -253,12 +305,29 @@ It also aims to be:

 In addition, bottom also currently has the following features:

-### Process filtering
+### Process searching

-<!--FIXME: [QUERY] Update this documentation...-->
+On any process widget, hit `/` to bring up a search bar. If the layout has multiple process widgets, note this search is independent of other widgets.

-On any process widget, hit `/` to bring up a search bar. If the layout has multiple process widgets, note this search is independent of other widgets. Searching supports regex, matching case, and matching entire words. Use `Tab` to toggle between
-searching by PID and by process name.
+![search bar image](assets/search_empty.png)
+
+By default, just typing in something will search by process name:
+
+![a simple search](assets/simple_search.png)
+
+This simple search can be refined by matching by case, matching the entire word, or by using regex:
+
+![a slightly better search](assets/simple_advanced_search.png)
+
+Now let's say you want to search for two things: luckily, we have the `AND` and `OR` logical operators:
+
+![logical operator demo](assets/or_search.png)
+
+Furthermore, one is able to refine their searches by CPU usage, memory usage, PID, and more. For example:
+
+![using cpu filter](assets/search_cpu_filter.png)
+
+One can see all available keywords and query options [here](#process-searching-keywords).

 ### Zoom

--- a/assets/basic_mode.png
+++ b/assets/basic_mode.png
--- a/assets/or_search.png
+++ b/assets/or_search.png
--- a/assets/search_cpu_filter.png
+++ b/assets/search_cpu_filter.png
--- a/assets/search_empty.png
+++ b/assets/search_empty.png
--- a/assets/simple_advanced_search.png
+++ b/assets/simple_advanced_search.png
--- a/assets/simple_search.png
+++ b/assets/simple_search.png
--- a/src/app/query.rs
+++ b/src/app/query.rs
@ -468,10 +468,10 @@ impl std::str::FromStr for PrefixType {
        match lower_case.as_str() {
            "cpu" => Ok(Cpu),
            "mem" => Ok(Mem),
-            "r" => Ok(Rps),
-            "w" => Ok(Wps),
-            "read" => Ok(TRead),
-            "write" => Ok(TWrite),
+            "read" => Ok(Rps),
+            "write" => Ok(Wps),
+            "tread" => Ok(TRead),
+            "twrite" => Ok(TWrite),
            "pid" => Ok(Pid),
            _ => Ok(Name),
        }
--- a/src/constants.rs
+++ b/src/constants.rs
@ -40,15 +40,15 @@ lazy_static! {
 // Help text
 pub const HELP_CONTENTS_TEXT: [&str; 6] = [
    "Press the corresponding numbers to jump to the section, or scroll:\n",
-    "1 - General bindings\n",
-    "2 - CPU bindings\n",
-    "3 - Process bindings\n",
-    "4 - Process search bindings\n",
-    "5 - Battery bindings",
+    "1 - General\n",
+    "2 - CPU widget\n",
+    "3 - Process widget\n",
+    "4 - Process search widget\n",
+    "5 - Battery widget",
 ];

 pub const GENERAL_HELP_TEXT: [&str; 20] = [
-    "1 - General bindings\n",
+    "1 - General\n",
    "q, Ctrl-c      Quit\n",
    "Esc            Close dialog windows, search, widgets, or exit expanded mode\n",
    "Ctrl-r         Reset display and any collected data\n",
@ -71,14 +71,14 @@ pub const GENERAL_HELP_TEXT: [&str; 20] = [
 ];

 pub const CPU_HELP_TEXT: [&str; 4] = [
-    "2 - CPU bindings\n",
+    "2 - CPU widget\n",
    "/              Open filtering for showing certain CPU cores\n",
    "Space          Toggle enabled/disabled cores\n",
    "Esc            Exit filtering mode",
 ];

 pub const PROCESS_HELP_TEXT: [&str; 8] = [
-    "3 - Process bindings\n",
+    "3 - Process widget\n",
    "dd             Kill the selected process\n",
    "c              Sort by memory usage, press again to reverse sorting order\n",
    "m              Sort by memory usage\n",
@ -88,9 +88,8 @@ pub const PROCESS_HELP_TEXT: [&str; 8] = [
    "Ctrl-f, /      Open process search widget",
 ];

-// FIXME: [QUERY] This likely needs to be updated.
-pub const SEARCH_HELP_TEXT: [&str; 13] = [
-    "4 - Process search bindings\n",
+pub const SEARCH_HELP_TEXT: [&str; 40] = [
+    "4 - Process search widget\n",
    "Tab            Toggle between searching for PID and name\n",
    "Esc            Close the search widget (retains the filter)\n",
    "Ctrl-a         Skip to the start of the search query\n",
@ -102,11 +101,38 @@ pub const SEARCH_HELP_TEXT: [&str; 13] = [
    "Alt-w/F2       Toggle matching the entire word\n",
    "Alt-r/F3       Toggle using regex\n",
    "Left, Alt-h    Move cursor left\n",
-    "Right, Alt-l   Move cursor right",
+    "Right, Alt-l   Move cursor right\n",
+    "Search keywords\n",
+    "pid\n",
+    "cpu\n",
+    "mem\n",
+    "pid\n",
+    "read\n",
+    "write\n",
+    "tread\n",
+    "twrite\n\n",
+    "\nComparison operators\n",
+    "=\n",
+    ">\n",
+    "<\n",
+    ">=\n",
+    "<=\n",
+    "\nLogical operators\n",
+    "and/&&\n",
+    "or/||\n",
+    "\nSupported units\n",
+    "B\n",
+    "KB\n",
+    "MB\n",
+    "TB\n",
+    "KiB\n",
+    "MiB\n",
+    "GiB\n",
+    "TiB\n",
 ];

 pub const BATTERY_HELP_TEXT: [&str; 3] = [
-    "5 - Battery bindings\n",
+    "5 - Battery widget\n",
    "Left           Go to previous battery\n",
    "Right          Go to next battery",
 ];