diff --git a/docs/Getting Started/Recurring Tasks.md b/docs/Getting Started/Recurring Tasks.md index 2362d77173..7aabd89d8f 100644 --- a/docs/Getting Started/Recurring Tasks.md +++ b/docs/Getting Started/Recurring Tasks.md @@ -15,7 +15,7 @@ When you toggle the status of a recurring task to anything but "todo" (i.e. "don In addition, _a new task will be put one line above the original task_ by default. -See [[#Location of the new task]] below, for how to change this behaviour and make the new task appear _on the line below the original task_. +See [[#Order of the new task]] below, for how to change this behaviour and make the new task appear _on the line below the original task_. The new task will have updated dates based off the original task. @@ -74,14 +74,14 @@ You can validate that tasks understands your rule by using the `Tasks: Create or --- -## Location of the new task +## Order of the new task Use this setting to control where the recurring task is inserted. The default is to put the new task before the original one. ![Setting for next recurrence appearance](../../images/settings-recurrence-location.png) > [!released] -> Control of the location of the new task was introduced in Tasks X.Y.Z +> Control of the location (or order) of the new task was introduced in Tasks X.Y.Z --- diff --git a/docs/Getting Started/Settings.md b/docs/Getting Started/Settings.md index bd160cf08a..23ec87e901 100644 --- a/docs/Getting Started/Settings.md +++ b/docs/Getting Started/Settings.md @@ -26,6 +26,6 @@ For convenience, here is a list of all those documentation pages (in the order t - [[Global Query]] - [[Status Settings]] - [[Dates#Date-tracking settings]] -- [[Recurring Tasks#Location of the new task]] +- [[Recurring Tasks#Order of the new task]] - [[Auto-Suggest]] - [[Create or edit Task#Turning off keyboard shortcuts]] diff --git a/docs/Introduction.md b/docs/Introduction.md index 58834a04b9..f4e881d59f 100644 --- a/docs/Introduction.md +++ b/docs/Introduction.md @@ -6,6 +6,8 @@ publish: true ## What's New? +- X.Y.Z: 🔥 Add [[Limiting#Limit number of tasks in each group|limiting tasks per group]] +- X.Y.Z: 🔥 Add option to control the [[Recurring Tasks#Order of the new task|order of new recurring tasks]] - 3.7.0: 🔥 Add [[Grouping#Reversing groups|reverse sorting of groups]] - 3.6.0: 🔥 Add [[Grouping#Other task properties|group by urgency]] - 3.6.0: 🔥 Add [[Sorting#Other task properties|sort by recurring]] diff --git a/docs/Queries/Grouping.md b/docs/Queries/Grouping.md index c14f7af461..432db8b510 100644 --- a/docs/Queries/Grouping.md +++ b/docs/Queries/Grouping.md @@ -117,7 +117,9 @@ See the [screenshots below](#screenshots) for how this looks in practice. > [!info] > Headings are displayed in case-sensitive alphabetical order, not the original order. -## Reversing groups +## Refining groups + +### Reversing groups > [!released] > Reversing of group headings was introduced in Tasks 3.7.0. @@ -139,6 +141,12 @@ For example: > > The [[Sorting|sort by]] facility, by contrast, controls the order in which displays are displayed *inside* each group. +### Limiting group size + +You can limit the number of tasks in each group, perhaps to work on the most important things first. + +See [[Limiting#Limit number of tasks in each group|Limit number of tasks in each group]]. + ## Notes > [!info] diff --git a/docs/Queries/Limiting.md b/docs/Queries/Limiting.md index 21a99ecfce..1f5cef44a0 100644 --- a/docs/Queries/Limiting.md +++ b/docs/Queries/Limiting.md @@ -4,18 +4,26 @@ publish: true # Limiting -## Total tasks +## Limit total number of tasks + +You can limit the total number of tasks to show as query results. -You can limit the number of total tasks to show as query results. Use the query string `limit to tasks`. -This will only list the `` first results of the query. +This will only list the first `` results of the query (after sorting). Shorthand is `limit `. -## Tasks per group +## Limit number of tasks in each group + +You can also limit the allowed number of tasks in each group, if [[Grouping|grouping]] is used. Otherwise this limit is ignored. -You can also limit the max number of tasks in groups if grouping is used. Otherwise this limit is ignored. Use the query string `limit groups to tasks`. -This will only list the `` first tasks in each group from the results of the query. +This will only list the first `` tasks in each group from the results of the query. Shorthand is `limit groups `. + +> [!NOTE] +> `limit groups` instructions are ignored if there are no `group by` instructions in the Tasks query. + +> [!released] +> `limit groups to tasks` was introduced in Tasks X.Y.Z. diff --git a/docs/Quick Reference.md b/docs/Quick Reference.md index d60a1746a0..8001fbc75c 100644 --- a/docs/Quick Reference.md +++ b/docs/Quick Reference.md @@ -24,7 +24,7 @@ This table summarizes the filters and other options available inside a `tasks` b | **[[Filters#Recurrence\|Recurrence]]** | | | | | `is recurring`
`is not recurring` | `sort by recurring` | `group by recurring` | | | `recurrence (includes, does not include) `
`recurrence (regex matches, regex does not match) /regex/i` | | `group by recurrence` | `hide recurrence rule` | -| **[[Filters#Priority\|Priority]]** and **[[Urgency\|urgency]]** | | | | +| **[[Filters#Priority\|Priority]]** and **[[Urgency\|urgency]]** | | | | | `priority is (above, below, not)? (low, none, medium, high)` | `sort by priority` | `group by priority` | `hide priority` | | | `sort by urgency` | `group by urgency` | `show urgency` | | **[[Filters#Filters for File Properties\|File properties]]** | | | | @@ -48,6 +48,7 @@ This table summarizes the filters and other options available inside a `tasks` b | **Other Filter Options** | | | | | `exclude sub-items` | | | | | `limit to tasks`
`limit ` | | | | +| `limit groups to tasks`
`limit groups ` | | | | | **Other Layout Options** | | | | | `hide edit button` | | | | | `hide task count` | | | | diff --git a/src/Query/Query.ts b/src/Query/Query.ts index c82306c247..ca644c8c8c 100644 --- a/src/Query/Query.ts +++ b/src/Query/Query.ts @@ -109,29 +109,37 @@ export class Query implements IQuery { result += this.filters[i].explainFilterIndented(''); } } + result += this.explainQueryLimits(); - if (this._limit !== undefined) { - result += `\n\nAt most ${this._limit} task`; - if (this._limit !== 1) { - result += 's'; - } - result += '.\n'; + const { debugSettings } = getSettings(); + if (debugSettings.ignoreSortInstructions) { + result += + "\n\nNOTE: All sort instructions, including default sort order, are disabled, due to 'ignoreSortInstructions' setting."; } - if (this._taskGroupLimit !== undefined) { - result += `\n\nAt most ${this._taskGroupLimit} task`; - if (this._taskGroupLimit !== 1) { - result += 's'; + return result; + } + + private explainQueryLimits() { + let result = ''; + + function getPluralisedText(limit: number) { + let text = `\n\nAt most ${limit} task`; + if (limit !== 1) { + text += 's'; } - result += ' per group.\n'; + return text; } - const { debugSettings } = getSettings(); - if (debugSettings.ignoreSortInstructions) { - result += - "\n\nNOTE: All sort instructions, including default sort order, are disabled, due to 'ignoreSortInstructions' setting."; + if (this._limit !== undefined) { + result += getPluralisedText(this._limit); + result += '.\n'; } + if (this._taskGroupLimit !== undefined) { + result += getPluralisedText(this._taskGroupLimit); + result += ' per group (if any "group by" options are supplied).\n'; + } return result; } diff --git a/tests/Query.test.ts b/tests/Query.test.ts index 5c40ca7fbb..bcc93a1056 100644 --- a/tests/Query.test.ts +++ b/tests/Query.test.ts @@ -885,7 +885,21 @@ At most 0 tasks. const expectedDisplayText = `No filters supplied. All tasks will match the query. -At most 4 tasks per group. +At most 4 tasks per group (if any "group by" options are supplied). +`; + expect(query.explainQuery()).toEqual(expectedDisplayText); + }); + + it('should explain all limit options', () => { + const input = 'limit 127\nlimit groups to 8 tasks'; + const query = new Query({ source: input }); + + const expectedDisplayText = `No filters supplied. All tasks will match the query. + +At most 127 tasks. + + +At most 8 tasks per group (if any "group by" options are supplied). `; expect(query.explainQuery()).toEqual(expectedDisplayText); });