|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +title: Regular Expressions |
| 4 | +nav_order: 2 |
| 5 | +parent: Queries |
| 6 | +has_toc: false |
| 7 | +--- |
| 8 | + |
| 9 | +# Regular Expressions |
| 10 | + |
| 11 | +{: .no_toc } |
| 12 | + |
| 13 | +<details open markdown="block"> |
| 14 | + <summary> |
| 15 | + Table of contents |
| 16 | + </summary> |
| 17 | + {: .text-delta } |
| 18 | +1. TOC |
| 19 | +{:toc} |
| 20 | +</details> |
| 21 | + |
| 22 | +--- |
| 23 | + |
| 24 | +## Introduction |
| 25 | + |
| 26 | +> Introduced in Tasks 1.12.0. |
| 27 | +
|
| 28 | +[Regular expression](https://en.wikipedia.org/wiki/Regular_expression) ("regex") searches are a powerful alternative to the simple `includes` and `does not include` searches. |
| 29 | + |
| 30 | +### Take Care |
| 31 | + |
| 32 | +<div class="code-example" markdown="1"> |
| 33 | + |
| 34 | +Warning |
| 35 | +{: .label .label-yellow} |
| 36 | + |
| 37 | +Regular expression (or 'regex') searching is a powerful but advanced feature that requires thorough knowledge in order to use successfully, and not miss intended search results. |
| 38 | + |
| 39 | +It is easy to write a regular expression that looks like it is correct, but which uses a special character that completely changes the meaning of the search string. |
| 40 | + |
| 41 | +For example, `\d` does **not** match the **two** characters `\d`, it matches any **one** of the following characters: `0123456789`. |
| 42 | + |
| 43 | +This documentation gives only a brief overview of the facility, with a few motivating examples, and then links to other resources, for thorough treatment. |
| 44 | + |
| 45 | +Having said that, regex searches are a valuable tool, used in many other tools, and time invested in learning about them can pay off well in future, in many other tools and scenarios. |
| 46 | +</div> |
| 47 | + |
| 48 | +## Basics |
| 49 | + |
| 50 | +The components of a regex search filter are: |
| 51 | + |
| 52 | +1. The field name, for example `description` or `path` |
| 53 | +2. Either `regex matches` or `regex does not match` |
| 54 | +3. The search pattern, inside a pair of forwards slashes, for example `/pc_abigail|pc_edwina|at_work/` |
| 55 | + - That pattern searches for `pc_abigail`, `pc_edwina` or `at_work`, without the need to create a boolean combination of three separate filters |
| 56 | +4. Optionally, an extra [flag](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#advanced_searching_with_flags) at the end, such as `i`, that can change the meaning of the expression |
| 57 | + - Note that many of the allowed flags are not relevant in the Tasks context, because there are no multi-line searches or global searches, for example. |
| 58 | + |
| 59 | +Case-sensitive example, showing the components: |
| 60 | + |
| 61 | +```text |
| 62 | +description regex matches /pc_abigail|pc_edwina|at_work/ |
| 63 | +^1 ^2 ^3 |
| 64 | +``` |
| 65 | + |
| 66 | +Case-INsensitive example, showing the components: |
| 67 | + |
| 68 | +```text |
| 69 | +description regex matches /pc_abigail|pc_edwina|at_work/i |
| 70 | +^1 ^2 ^3 ^4 |
| 71 | +``` |
| 72 | + |
| 73 | +## Notes |
| 74 | + |
| 75 | +- Regex searches are **case-sensitive**, unlike the simpler `includes` and `does not include` |
| 76 | +- A regex search can be made **insensitive** by appending a `i` flag after the closing `/`, for example: `/I aM cAsE INsensitive because of the LiTle i after the closing slash/i` |
| 77 | +- Tasks does not support multi-line regex searches, as each task is a single line. |
| 78 | +- Note that `tags` searches do not yet support regex searches. |
| 79 | + - As a workaround, search `description` instead. |
| 80 | + |
| 81 | +## Special characters |
| 82 | + |
| 83 | +If using regex searches, it is important to be aware of the available special characters for several reasons: |
| 84 | + |
| 85 | +1. They enable complex queries to written in simple ways |
| 86 | +2. They can cause confusing results or broken searches, if not "escaped" in the search. |
| 87 | + |
| 88 | +Here are a few examples of the [many special characters](https://www.rexegg.com/regex-quickstart.html): |
| 89 | + |
| 90 | +- `.` matches any character |
| 91 | +- `^` matches the start of the string (but when `[^inside brackets]`, it means "not") |
| 92 | +- `$` matches the end of the string |
| 93 | +- `\` adds special meaning to some characters. For example: |
| 94 | + - `\d` matches one digit, from 0 to 9 |
| 95 | + - `\D` matches character that is not a digit |
| 96 | + |
| 97 | +## Important links |
| 98 | + |
| 99 | +- [Regex Tutorial](https://regexone.com/) |
| 100 | +- [Regex Cheat Sheet](https://www.rexegg.com/regex-quickstart.html) |
| 101 | +- [Regex Testing Tool: regex101](https://regex101.com/): Select the flavor 'ECMAScript (JavaScript)' |
| 102 | +- Implemented using [JavaScript's RegExp implementation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) |
| 103 | +- Supports [JavaScript RegExp Flags](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#advanced_searching_with_flags), although not all of them are relevant in this context. |
| 104 | + |
| 105 | +## Known limitations |
| 106 | + |
| 107 | +Please be aware of the following limitations in Tasks' implementation of regular expression searching: |
| 108 | + |
| 109 | +- The single error message `Tasks query: cannot parse regex (description); check your leading and trailing slashes for your query` may mean any of: |
| 110 | + - The opening or closing `/` is missing from the query. |
| 111 | + - The regular expression is not valid, for example `description regex matches /[123/`. |
| 112 | +- No error when part of the pattern is lost, for example because unescaped slashes are used inside the pattern. |
| 113 | + - For example, `path regex matches /a/b/c/d/` actually searches for `path regex matches /a/`. |
| 114 | + - In this case, the query should be `path regex matches /a\/b\/c\/d/`. |
| 115 | +- Illegal flags are ignored. |
| 116 | + - For example, the query `description regex matches /CASE/&` should give an error that `&` (and similar) are unrecognised flags. |
| 117 | +- The `tag` or `tags` instruction does not yet support regular expression searches. |
| 118 | +- [Lookahead and Lookbehind](https://www.regular-expressions.info/lookaround.html) searches are untested, and are presumed not to work on Apple mobile devices, or to cause serious performance problems with slow searches. |
| 119 | + |
| 120 | +## Regular expression examples |
| 121 | + |
| 122 | +Example searches: |
| 123 | + |
| 124 | +```text |
| 125 | +# Find tasks whose description begins with Log, exact capitalisation |
| 126 | +description regex matches /^Log/ |
| 127 | +
|
| 128 | +# Find tasks whose description begins with Log, ignoring capitalisation |
| 129 | +description regex matches /^Log/i |
| 130 | +``` |
0 commit comments