Skip to content

Commit c3b50d5

Browse files
claremacraeclaremacrae
authored
docs: More group limits docs (+minor test & refactor) (#1973)
* docs: Add 'limit groups' options to Quick Reference page * docs: Minor improvements to Limiting docs * docs: Add 'limit groups' to "What's new?" * docs: Slightly clarify headings in Limiting.md * docs: Add link in Grouping.md to 'limit groups' feature * docs: Add order of reoccurring tasks option to "What's new?" * test: Test explanation of both limit options. There is a curious double-blank line, which I intend to ignore for now. * fix: Explanation now says 'limit groups' ignored if no groups * refactor: Extract method Query.explainQueryLimits() * refactor: Remove unnecessary parameter from Query.explainQueryLimits() * refactor: Remove some repetition in Query.explainQueryLimits()
1 parent ecc4c15 commit c3b50d5

File tree

8 files changed

+69
-28
lines changed

8 files changed

+69
-28
lines changed

‎docs/Getting Started/Recurring Tasks.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ When you toggle the status of a recurring task to anything but "todo" (i.e. "don
1515

1616
In addition, _a new task will be put one line above the original task_ by default.
1717

18-
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_.
18+
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_.
1919

2020
The new task will have updated dates based off the original task.
2121

@@ -74,14 +74,14 @@ You can validate that tasks understands your rule by using the `Tasks: Create or
7474

7575
---
7676

77-
## Location of the new task
77+
## Order of the new task
7878

7979
Use this setting to control where the recurring task is inserted. The default is to put the new task before the original one.
8080

8181
![Setting for next recurrence appearance](../../images/settings-recurrence-location.png)
8282

8383
> [!released]
84-
> Control of the location of the new task was introduced in Tasks X.Y.Z
84+
> Control of the location (or order) of the new task was introduced in Tasks X.Y.Z
8585
8686
---
8787

‎docs/Getting Started/Settings.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,6 @@ For convenience, here is a list of all those documentation pages (in the order t
2626
- [[Global Query]]
2727
- [[Status Settings]]
2828
- [[Dates#Date-tracking settings]]
29-
- [[Recurring Tasks#Location of the new task]]
29+
- [[Recurring Tasks#Order of the new task]]
3030
- [[Auto-Suggest]]
3131
- [[Create or edit Task#Turning off keyboard shortcuts]]

‎docs/Introduction.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ publish: true
66

77
## What's New?
88

9+
- X.Y.Z: 🔥 Add [[Limiting#Limit number of tasks in each group|limiting tasks per group]]
10+
- X.Y.Z: 🔥 Add option to control the [[Recurring Tasks#Order of the new task|order of new recurring tasks]]
911
- 3.7.0: 🔥 Add [[Grouping#Reversing groups|reverse sorting of groups]]
1012
- 3.6.0: 🔥 Add [[Grouping#Other task properties|group by urgency]]
1113
- 3.6.0: 🔥 Add [[Sorting#Other task properties|sort by recurring]]

‎docs/Queries/Grouping.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,9 @@ See the [screenshots below](#screenshots) for how this looks in practice.
117117
> [!info]
118118
> Headings are displayed in case-sensitive alphabetical order, not the original order.
119119
120-
## Reversing groups
120+
## Refining groups
121+
122+
### Reversing groups
121123

122124
> [!released]
123125
> Reversing of group headings was introduced in Tasks 3.7.0.
@@ -139,6 +141,12 @@ For example:
139141
>
140142
> The [[Sorting|sort by]] facility, by contrast, controls the order in which displays are displayed *inside* each group.
141143
144+
### Limiting group size
145+
146+
You can limit the number of tasks in each group, perhaps to work on the most important things first.
147+
148+
See [[Limiting#Limit number of tasks in each group|Limit number of tasks in each group]].
149+
142150
## Notes
143151

144152
> [!info]

‎docs/Queries/Limiting.md

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,18 +4,26 @@ publish: true
44

55
# Limiting
66

7-
## Total tasks
7+
## Limit total number of tasks
8+
9+
You can limit the total number of tasks to show as query results.
810

9-
You can limit the number of total tasks to show as query results.
1011
Use the query string `limit to <number> tasks`.
11-
This will only list the `<number>` first results of the query.
12+
This will only list the first `<number>` results of the query (after sorting).
1213

1314
Shorthand is `limit <number>`.
1415

15-
## Tasks per group
16+
## Limit number of tasks in each group
17+
18+
You can also limit the allowed number of tasks in each group, if [[Grouping|grouping]] is used. Otherwise this limit is ignored.
1619

17-
You can also limit the max number of tasks in groups if grouping is used. Otherwise this limit is ignored.
1820
Use the query string `limit groups to <number> tasks`.
19-
This will only list the `<number>` first tasks in each group from the results of the query.
21+
This will only list the first `<number>` tasks in each group from the results of the query.
2022

2123
Shorthand is `limit groups <number>`.
24+
25+
> [!NOTE]
26+
> `limit groups` instructions are ignored if there are no `group by` instructions in the Tasks query.
27+
28+
> [!released]
29+
> `limit groups to <number> tasks` was introduced in Tasks X.Y.Z.

‎docs/Quick Reference.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ This table summarizes the filters and other options available inside a `tasks` b
2424
| **[[Filters#Recurrence\|Recurrence]]** | | | |
2525
| `is recurring`<br>`is not recurring` | `sort by recurring` | `group by recurring` | |
2626
| `recurrence (includes, does not include) <string>`<br>`recurrence (regex matches, regex does not match) /regex/i` | | `group by recurrence` | `hide recurrence rule` |
27-
| **[[Filters#Priority\|Priority]]** and **[[Urgency\|urgency]]** | | | |
27+
| **[[Filters#Priority\|Priority]]** and **[[Urgency\|urgency]]** | | | |
2828
| `priority is (above, below, not)? (low, none, medium, high)` | `sort by priority` | `group by priority` | `hide priority` |
2929
| | `sort by urgency` | `group by urgency` | `show urgency` |
3030
| **[[Filters#Filters for File Properties\|File properties]]** | | | |
@@ -48,6 +48,7 @@ This table summarizes the filters and other options available inside a `tasks` b
4848
| **Other Filter Options** | | | |
4949
| `exclude sub-items` | | | |
5050
| `limit to <number> tasks`<br>`limit <number>` | | | |
51+
| `limit groups to <number> tasks`<br>`limit groups <number>` | | | |
5152
| **Other Layout Options** | | | |
5253
| `hide edit button` | | | |
5354
| `hide task count` | | | |

‎src/Query/Query.ts

Lines changed: 23 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -109,29 +109,37 @@ export class Query implements IQuery {
109109
result += this.filters[i].explainFilterIndented('');
110110
}
111111
}
112+
result += this.explainQueryLimits();
112113

113-
if (this._limit !== undefined) {
114-
result += `\n\nAt most ${this._limit} task`;
115-
if (this._limit !== 1) {
116-
result += 's';
117-
}
118-
result += '.\n';
114+
const { debugSettings } = getSettings();
115+
if (debugSettings.ignoreSortInstructions) {
116+
result +=
117+
"\n\nNOTE: All sort instructions, including default sort order, are disabled, due to 'ignoreSortInstructions' setting.";
119118
}
120119

121-
if (this._taskGroupLimit !== undefined) {
122-
result += `\n\nAt most ${this._taskGroupLimit} task`;
123-
if (this._taskGroupLimit !== 1) {
124-
result += 's';
120+
return result;
121+
}
122+
123+
private explainQueryLimits() {
124+
let result = '';
125+
126+
function getPluralisedText(limit: number) {
127+
let text = `\n\nAt most ${limit} task`;
128+
if (limit !== 1) {
129+
text += 's';
125130
}
126-
result += ' per group.\n';
131+
return text;
127132
}
128133

129-
const { debugSettings } = getSettings();
130-
if (debugSettings.ignoreSortInstructions) {
131-
result +=
132-
"\n\nNOTE: All sort instructions, including default sort order, are disabled, due to 'ignoreSortInstructions' setting.";
134+
if (this._limit !== undefined) {
135+
result += getPluralisedText(this._limit);
136+
result += '.\n';
133137
}
134138

139+
if (this._taskGroupLimit !== undefined) {
140+
result += getPluralisedText(this._taskGroupLimit);
141+
result += ' per group (if any "group by" options are supplied).\n';
142+
}
135143
return result;
136144
}
137145

‎tests/Query.test.ts

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -885,7 +885,21 @@ At most 0 tasks.
885885

886886
const expectedDisplayText = `No filters supplied. All tasks will match the query.
887887
888-
At most 4 tasks per group.
888+
At most 4 tasks per group (if any "group by" options are supplied).
889+
`;
890+
expect(query.explainQuery()).toEqual(expectedDisplayText);
891+
});
892+
893+
it('should explain all limit options', () => {
894+
const input = 'limit 127\nlimit groups to 8 tasks';
895+
const query = new Query({ source: input });
896+
897+
const expectedDisplayText = `No filters supplied. All tasks will match the query.
898+
899+
At most 127 tasks.
900+
901+
902+
At most 8 tasks per group (if any "group by" options are supplied).
889903
`;
890904
expect(query.explainQuery()).toEqual(expectedDisplayText);
891905
});

0 commit comments

Comments
 (0)