Repository: obsidian-tasks-group/obsidian-tasks
Pull request #919 (2022-07-23 14:55:27)

feat: Add 'group by priority'
<!--- Provide a general summary of your changes in the Title above -->

## Description

Add new priority  grouping command:

- `group by priority`
- update the Grouping docs page
- update the Quick Reference docs page

From the new docs, the group names will be one of:

* `Priority 1: High`
* `Priority 2: Medium`
* `Priority 3: None`
* `Priority 4: Low`

## Motivation and Context

I have found this useful in my fork of this project, so am making it available to others.


## How has this been tested?

- Via new unit tests
- At length in my main vault

## Screenshots (if appropriate):

## Types of changes
<!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] Refactor (non-breaking change which only improves the design or structure of existing code, and making no changes to its external behaviour)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)

## Checklist:
<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
<!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
- [x] My code follows the code style of this project and passes `yarn run lint`.
- [x] My change requires a change to the documentation.
- [x] I have updated the documentation accordingly.
- [x] My change has adequate Unit Test coverage.

By creating a Pull Request you agree to our [Code of Conduct](https://github.com/obsidian-tasks-group/obsidian-tasks/blob/main/CODE_OF_CONDUCT.md). For further guidance on contributing please see [contributing guide](https://github.com/obsidian-tasks-group/obsidian-tasks/blob/main/CONTRIBUTING.md)



Patch:
diff --git a/docs/queries/grouping.md b/docs/queries/grouping.md
index 2a3b3c3e..1d49e6cc 100644
--- a/docs/queries/grouping.md
+++ b/docs/queries/grouping.md
@@ -57,6 +57,12 @@ Task properties:
     * The due date of the task, including the week-day, or `No due date`.
 1. `done`
     * The done date of the task, including the week-day, or `No done date`.
+1. `priority`
+    * The priority of the task, namely one of:
+        * `Priority 1: High`
+        * `Priority 2: Medium`
+        * `Priority 3: None`
+        * `Priority 4: Low`
 1. `recurring`
     * Whether the task is recurring: either `Recurring` or `Not Recurring`.
 1. `recurrence`
diff --git a/docs/quick-reference/index.md b/docs/quick-reference/index.md
index 71ce29aa..d1b52876 100644
--- a/docs/quick-reference/index.md
+++ b/docs/quick-reference/index.md
@@ -24,7 +24,7 @@ This table summarizes the filters and other options available inside a `tasks` b
 | `happens (before, after, on) <date>`<br>`has happens date`<br>`no  happens date`       |                                             |                       |                        |
 | `is recurring`<br>`is not recurring`                                                   |                                             | `group by recurring`  |                        |
 |                                                                                        |                                             | `group by recurrence` | `hide recurrence rule` |
-| `priority is (above, below)? (low, none, medium, high)`                                | `sort by priority`                          |                       | `hide priority`        |
+| `priority is (above, below)? (low, none, medium, high)`                                | `sort by priority`                          | `group by priority`   | `hide priority`        |
 |                                                                                        | `sort by urgency`                           |                       |                        |
 | `path (includes, does not include) <path>`                                             | `sort by path`                              | `group by path`       |                        |
 |                                                                                        |                                             | `group by folder`     |                        |
diff --git a/src/Query.ts b/src/Query.ts
index 5be70217..21ecba0c 100644
--- a/src/Query.ts
+++ b/src/Query.ts
@@ -32,6 +32,7 @@ export type GroupingProperty =
     | 'folder'
     | 'heading'
     | 'path'
+    | 'priority'
     | 'recurrence'
     | 'recurring'
     | 'scheduled'
@@ -56,7 +57,7 @@ export class Query implements IQuery {
         /^sort by (urgency|status|priority|start|scheduled|due|done|path|description|tag)( reverse)?[\s]*(\d+)?/;
 
     private readonly groupByRegexp =
-        /^group by (backlink|done|due|filename|folder|heading|path|recurrence|recurring|scheduled|start|status|tags)/;
+        /^group by (backlink|done|due|filename|folder|heading|path|priority|recurrence|recurring|scheduled|start|status|tags)/;
 
     private readonly hideOptionsRegexp =
         /^hide (task count|backlink|priority|start date|scheduled date|done date|due date|recurrence rule|edit button)/;
diff --git a/src/Query/Group.ts b/src/Query/Group.ts
index 9f83c5e6..37501c8d 100644
--- a/src/Query/Group.ts
+++ b/src/Query/Group.ts
@@ -1,5 +1,6 @@
 import type { Grouping, GroupingProperty } from '../Query';
 import type { Task } from '../Task';
+import { Priority } from '../Task';
 import { TaskGroups } from './TaskGroups';
 
 /**
@@ -43,6 +44,7 @@ export class Group {
         folder: Group.groupByFolder,
         heading: Group.groupByHeading,
         path: Group.groupByPath,
+        priority: Group.groupByPriority,
         recurrence: Group.groupByRecurrence,
         recurring: Group.groupByRecurring,
         scheduled: Group.groupByScheduledDate,
@@ -51,6 +53,25 @@ export class Group {
         tags: Group.groupByTags,
     };
 
+    private static groupByPriority(task: Task): string[] {
+        let priorityName = 'ERROR';
+        switch (task.priority) {
+            case Priority.High:
+                priorityName = 'High';
+                break;
+            case Priority.Medium:
+                priorityName = 'Medium';
+                break;
+            case Priority.None:
+                priorityName = 'None';
+                break;
+            case Priority.Low:
+                priorityName = 'Low';
+                break;
+        }
+        return [`Priority ${task.priority}: ${priorityName}`];
+    }
+
     private static groupByRecurrence(task: Task): string[] {
         if (task.recurrence !== null) {
             return [task.recurrence!.toText()];


Test patch:
diff --git a/tests/Group.test.ts b/tests/Group.test.ts
index 0c921afb..a4af62ab 100644
--- a/tests/Group.test.ts
+++ b/tests/Group.test.ts
@@ -329,6 +329,29 @@ describe('Group names', () => {
             expectedGroupNames: ['a/b/c'],
         },
 
+        // -----------------------------------------------------------
+        // group by priority
+        {
+            groupBy: 'priority',
+            taskLine: '- [ ] a ⏫',
+            expectedGroupNames: ['Priority 1: High'],
+        },
+        {
+            groupBy: 'priority',
+            taskLine: '- [ ] a 🔼',
+            expectedGroupNames: ['Priority 2: Medium'],
+        },
+        {
+            groupBy: 'priority',
+            taskLine: '- [ ] a',
+            expectedGroupNames: ['Priority 3: None'],
+        },
+        {
+            groupBy: 'priority',
+            taskLine: '- [ ] a 🔽',
+            expectedGroupNames: ['Priority 4: Low'],
+        },
+
         // -----------------------------------------------------------
         // group by recurrence
         {
diff --git a/tests/Query.test.ts b/tests/Query.test.ts
index c5b1cf02..e332991f 100644
--- a/tests/Query.test.ts
+++ b/tests/Query.test.ts
@@ -166,6 +166,7 @@ describe('Query parsing', () => {
             'group by folder',
             'group by heading',
             'group by path',
+            'group by priority',
             'group by recurrence',
             'group by recurring',
             'group by scheduled',