Merge pull request #438 from fluffysquirrels/status-query-docs

Add `pueue status` query documentation

CHANGELOG.md

@@ -14,6 +14,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - Add the `-j/--json` flag to `pueue group` to get a machine readable list of all current groups. [#430](https://github.com/Nukesor/pueue/issues/430)
 - Add `pueued.plist` template to run pueue with launchd on MacOS. [#429](https://github.com/Nukesor/pueue/issues/429)
+- Add query syntax documentation to `pueue status` [#438](https://github.com/Nukesor/pueue/issues/429)
 
 ## [3.1.2] - 2023-02-26
 

pueue/src/client/cli.rs

@@ -289,6 +289,47 @@ pub enum SubCommand {
     Status {
         /// Users can specify a custom query to filter for specific values, order by a column
         /// or limit the amount of tasks listed.
+        /// Use `--help` for the full syntax definition.
+        #[arg(
+            long_help = "Users can specify a custom query to filter for specific values, order by a column
+or limit the amount of tasks listed.
+
+Syntax:
+   [column_selection]? [filter]* [order_by]? [limit]?
+
+where:
+  - column_selection := `columns=[column]([column],)*`
+  - column := `id | status | command | label | path | enqueue_at | dependencies | start | end`
+  - filter := `[filter_column] [filter_op] [filter_value]`
+    (note: not all columns support all operators, see \"Filter columns\" below.)
+  - filter_column := `start | end | enqueue_at | status | label`
+  - filter_op := `= | != | < | > | %=`
+    (`%=` means 'contains', as in the test value is a substring of the column value)
+  - order_by := `order_by [column] [order_direction]`
+  - order_direction := `asc | desc`
+  - limit := `[limit_type]? [limit_count]`
+  - limit_type := `first | last`
+  - limit_count := a positive integer
+
+Filter columns:
+  - `start`, `end`, `enqueue_at` contain a datetime
+    which support the operators `=`, `!=`, `<`, `>`
+    against test values that are:
+      - date like `YYYY-MM-DD`
+      - time like `HH:mm:ss` or `HH:mm`
+      - datetime like `YYYY-MM-DDHH:mm:ss`
+        (note there is currently no separator between the date and the time)
+
+Examples:
+  - `status=running`
+  - `columns=id,status,command status=running start > 2023-05-2112:03:17 order_by command first 5`
+
+The formal syntax is defined here:
+https://github.com/Nukesor/pueue/blob/main/pueue/src/client/query/syntax.pest
+
+More documention is on the query syntax PR:
+https://github.com/Nukesor/pueue/issues/350#issue-1359083118"
+        )]
         query: Vec<String>,
 
         /// Print the current state as json to stdout.