From 5745e170847ee3a07ba978cbe228fefa5a1ee800 Mon Sep 17 00:00:00 2001 From: Alex Helfet Date: Sun, 21 May 2023 12:09:10 +0100 Subject: [PATCH 1/5] Add pueue status query documentation --- pueue/src/client/cli.rs | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/pueue/src/client/cli.rs b/pueue/src/client/cli.rs index 4945cf60..1303137b 100644 --- a/pueue/src/client/cli.rs +++ b/pueue/src/client/cli.rs @@ -289,6 +289,37 @@ 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) + - 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 + +Examples: + - `columns=id,status,command status=running start > 2023-05-2112:03:17 order_by command first 5` + (note that a datetime has no separator between the end of the date and the start of the time) + +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, /// Print the current state as json to stdout. From bfdd24ef5e330567f9376cfd9c334831a6b69142 Mon Sep 17 00:00:00 2001 From: Alex Helfet Date: Sun, 21 May 2023 12:12:08 +0100 Subject: [PATCH 2/5] Add CHANGELOG.md entry --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index d2122766..ae670aeb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,8 @@ 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 From 7df63660fe3c986f8f9a040f381fa371f0f99387 Mon Sep 17 00:00:00 2001 From: Alex Helfet Date: Sun, 21 May 2023 12:13:13 +0100 Subject: [PATCH 3/5] cargo fmt --- pueue/src/client/cli.rs | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/pueue/src/client/cli.rs b/pueue/src/client/cli.rs index 1303137b..38428772 100644 --- a/pueue/src/client/cli.rs +++ b/pueue/src/client/cli.rs @@ -290,8 +290,8 @@ pub enum SubCommand { /// 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 + #[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: @@ -319,7 +319,8 @@ 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")] +https://github.com/Nukesor/pueue/issues/350#issue-1359083118" + )] query: Vec, /// Print the current state as json to stdout. From e4cbd4a6273f6675165b1d06216638ece2f01fac Mon Sep 17 00:00:00 2001 From: Alex Helfet Date: Sun, 21 May 2023 12:21:20 +0100 Subject: [PATCH 4/5] Describe filter columns --- pueue/src/client/cli.rs | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/pueue/src/client/cli.rs b/pueue/src/client/cli.rs index 38428772..15294578 100644 --- a/pueue/src/client/cli.rs +++ b/pueue/src/client/cli.rs @@ -301,7 +301,7 @@ 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) + (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) @@ -311,9 +311,18 @@ where: - 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` - (note that a datetime has no separator between the end of the date and the start of the time) The formal syntax is defined here: https://github.com/Nukesor/pueue/blob/main/pueue/src/client/query/syntax.pest From 600400e6dd80cabdb349a974ca889ef5e478f183 Mon Sep 17 00:00:00 2001 From: Alex Helfet Date: Sun, 21 May 2023 12:25:46 +0100 Subject: [PATCH 5/5] CHANGELOG.md whitespace --- CHANGELOG.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ae670aeb..71f29ec1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,8 +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) +- Add query syntax documentation to `pueue status` [#438](https://github.com/Nukesor/pueue/issues/429) ## [3.1.2] - 2023-02-26