Skip to main content Link Search Menu Expand Document (external link)

Regular Expressions

Table of contents
  1. Regular Expressions
    1. Introduction
      1. Take Care
    2. Basics
    3. Notes
    4. Escaping special characters
    5. Special characters
    6. Important links
    7. Known limitations
    8. Regular expression examples
      1. Searching the start of a field
      2. Finding empty fields
      3. Finding tasks that are waiting
      4. Finding times
      5. Finding sub-tags
      6. Finding short tags

Introduction

Introduced in Tasks 1.12.0.

Regular expression (“regex”) searches are a powerful alternative to the simple includes and does not include searches.

Take Care

Warning

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.

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.

For example, \d does not match the two characters \d, it matches any one of the following characters: 0123456789.

This documentation gives only a brief overview of the facility, with a few motivating examples, and then links to other resources, for thorough treatment.

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.

Basics

The components of a regex search filter are:

  1. The field name, for example description or path
  2. Either regex matches or regex does not match
  3. The search pattern, inside a pair of forwards slashes, for example /pc_abigail|pc_edwina|at_work/
    • That pattern searches for pc_abigail, pc_edwina or at_work, without the need to create a boolean combination of three separate filters
  4. Optionally, an extra flag at the end, such as i, that can change the meaning of the expression
    • 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.

Case-sensitive example, showing the components:

description regex matches /pc_abigail|pc_edwina|at_work/
^1          ^2            ^3

Case-INsensitive example, showing the components:

description regex matches /pc_abigail|pc_edwina|at_work/i
^1          ^2            ^3                            ^4

Notes

  • Regex searches are case-sensitive, unlike the simpler includes and does not include
  • 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
  • Tasks does not support multi-line regex searches, as each task is a single line.

Escaping special characters

To search for any of the characters [ \ ^ $ . | ? * + ( ) / literally in Tasks, you should put a \ character before each of them.

This is called ‘escaping’. See Escaping, special characters.

See the next section for the meaning of some of these characters.

Special characters

If using regex searches, it is important to be aware of the available special characters for several reasons:

  1. They enable complex queries to written in simple ways
  2. They can cause confusing results or broken searches, if not “escaped” in the search.

Here are a few examples of the many special characters:

  • . matches any character
  • [...] means search for any of the characters in the square brackets.
  • Start and end
  • | is an OR in regular expressions
  • \ adds special meaning to some characters. For example:
    • \d matches one digit, from 0 to 9
    • \D matches character that is not a digit
    • See Character classes

For a thorough, clear introduction to all the options, see Regular expressions at JavaScript.info.

Learning resources:

Online tools for experimenting with - and testing - regular expressions:

Implementation details:

Known limitations

Please be aware of the following limitations in Tasks’ implementation of regular expression searching:

  • The single error message Tasks query: cannot parse regex (description); check your leading and trailing slashes for your query may mean any of:
    • The opening or closing / is missing from the query.
    • The regular expression is not valid, for example description regex matches /[123/.
    • Logged in #1038 and #1039
  • No error when part of the pattern is lost, for example because unescaped slashes are used inside the pattern.
    • For example, path regex matches /a/b/c/d/ actually searches for path regex matches /a/.
    • In this case, the query should be path regex matches /a\/b\/c\/d/.
    • Logged in #1037
  • Illegal flags are ignored.
    • For example, the query description regex matches /CASE/& should give an error that & (and similar) are unrecognised flags.
  • Lookahead and Lookbehind searches are untested, and are presumed not to work on Apple mobile devices, or to cause serious performance problems with slow searches.

Regular expression examples

Below are some example regex searches, to give some ideas of what can be done.

There are some more examples in the Tasks-Demo sample vault, in the file Regular Expression Searches.

Searching the start of a field

Find tasks whose description begins with Log, exact capitalisation:

description regex matches /^Log/

Find tasks whose description begins with Log, ignoring capitalisation

description regex matches /^Log/i

Finding empty fields

I want to find tasks that have no description, perhaps because they were created from a template:

description regex matches /^$/

I want to exclude tasks with no description:

description regex does not match /^$/

How this works: in regular expressions, /^$/ matches text where there is nothing between the start and the end.

Finding tasks that are waiting

I want to find tasks that are waiting for something else. But ‘waiting’ can be spelled in several different ways:

description regex matches /waiting|waits|wartet/i

Finding times

Find tasks containing a time in the description - simple version. This matches invalid times, such as 99:99, as \d means ‘any digit’.

description regex matches /\d\d:\d\d/

Find tasks containing a time in the description. This is more precise than the previous example, thanks to specifying which digits are allowed in each position.

description regex matches /[012][0-9]:[0-5][0-9]/

Finding sub-tags

Suppose you wanted to search for tags of this form: #tag/subtag3/subsubtag5, where the 3 and the 5 are allowed to be any single digit.

  • We can use either [0-9] or \d to match a single digit.
  • To find a sub-tag, any / characters must be ‘escaped’ to prevent them truncating the rest of the search pattern.

Escaping the / leads us to this instruction, which we have made case-insensitive to find capitalised tags too:

tags regex matches /#tag\/subtag[0-9]\/subsubtag[0-9]/i

Finding short tags

Suppose you wanted to search for tasks with a very short tag in: #t, and to not match tags like #task and #t/subtag.

tag regex matches /#t$/i

The $ prevents there being any more characters in the tag after the search pattern.

The i makes the search case-insensitive.