Skip to content

Filter Expressions for Advanced Search

Jump to bottom
ransome edited this page Feb 3, 2024 · 7 revisions

Overview

This page describes an advanced search feature which can be used in the sleek search bar. If the text you type in the search bar is not a well-formed filter expression, sleek will try to search for exactly what you typed as a literal string match.

The advanced search functionality seamlessly integrates with the search filter feature, enabling a faster and more efficient use of the application.

Quick Start

Here are some examples of filter expressions that you can type. Go ahead and experiment on your own!

+bills and due: < tomorrow
pri=A and due: and +
(A) or due:2021-06
"some words in the todo" and +bugs
@home or (@work and priority < D and due: < today+3b)
@home and +bills
not complete and !+
due: < tomorrow

The + begins a project name and the @ begins a context name, just as in a todo.txt task. The " string lets you specify a literal text match on the text of the todo. You can also use a single-quoted string, or even a JavaScript regular expression like /[a-zA-Z][0-9]+.*/.

Don't be concerned if you see no matches while you are typing your filter expression. If the filter expression is not syntactically correct, there may be no matches until you complete the expression. Sleek will try to keep the last valid query if you continue to type. So for instance, if you type +bills and pr that is not valid, but sleek will continue to show the result of the expression +bills until you reach another valid query like +bills and pri > A. (This could be a little confusing or surprising, and we are working on ideas to give you more feedback about the query as you type it.)

The remainder of this page goes through all of the features of the filter expression language in detail. You don't necessarily have to read any or all of this to use the filter expressions, but all of the details should be here if you need to know them.

Syntax Rules

Logical Operators

A filter expression is a logical expression whose value must ultimately be a boolean (true or false) to decide whether the expression matches or not. Sub-expressions can be combined with the three boolean operators or, and, and not to build bigger expressions. Each of these operators has three names so that you can use whichever ones seem most natural to you:

  • or can also be specified as OR or as ||.
  • and can also be specified as AND or as &&.
  • not can also be specified as NOT or as !.

Logical expressions can also be parenthesized to control the order of evaluation. OR has the weakest precedence, AND the next stronger precedence, and NOT the strongest precedence. Examples of logical expressions:

  • (+bills or +errands) and @home and not complete
  • due: <= today && !priority

The logical operators are used to combine lower-level values, each of which results from one of:

  • project match
  • context match
  • due date comparison
  • priority comparison
  • literal text match
  • regular expression match

Each of these will be described in more detail in the following sections.

Project Match

  • The symbol + introduces a project match. By itself, the + matches any todo with a project.
  • +bi will match any todo with a project that contains the sub-string bi, eg: it will match projects +bills and +ambitious.
  • +"big" or +big" specifies an exact match, so it will match the project big but not any longer project name like bigtask.
  • if your project name contains parentheses, you will need to match it exactly with the quote syntax, eg: +"project(A)".

Context Match

  • The symbol @ introduces a context match. By itself, the @ matches any todo with a context.
  • @ho will match any todo with a context that contains the sub-string ho.
  • @"home" or @home" specifies an exact match, so it will match the context home but not any longer context name like homeland.
  • if your context name contains parentheses, you will need to match it exactly with the quote syntax, eg: @"my(main)place".

Due Date Comparison

  • due dates can be tested using the keyword due:. By itself, due: is true if the todo has a due date.
  • due: followed by a comparison operator (==, =, !=, <, <=, >, or >=) and a DATE will test against specific dates. DATE can be an ISO date string (YYYY-MM-DD) or the keywords today, tomorrow, or yesterday. Examples: due: <= 2021-08-14, due: = today.
  • You can also add or subtract an INTERVAL to/from a DATE. The intervals are the same ones used in the recurrence expressions: an integer followed by one of dbwmy. Example: due: > tomorrow-2w.
  • a due date prefix match expression consists of due: immediately followed by the date string. The date string may be an ISO date or the first part of an ISO date. Examples: due:2021-06-28 will match a due date of exactly 2021-06-28, so that is the same effect as due: == 2021-06-28. However, due:2021 will match any due date in 2021, which is the same effect as due: >= 2021-01-01 and due: <= 2021-12-31.

Threshold Date Comparison

  • t: (threshold) dates can be tested using the keyword t:. By itself, t: is true if the todo has a threshold date.
  • t: followed by a comparison operator (==, =, !=, <, <=, >, or >=) and a DATE will test against specific dates. DATE can be an ISO date string (YYYY-MM-DD) or the keywords today, tomorrow, or yesterday. Examples: t: <= 2021-08-14, t: = today.
  • You can also add or subtract an INTERVAL to/from a DATE. The intervals are the same ones used in the recurrence expressions: an integer followed by one of dbwmy. Example: t: > tomorrow-2w.
  • a threshold date prefix match expression consists of t: immediately followed by the date string. The date string may be an ISO date or the first part of an ISO date. Examples: t:2021-06-28 will match a threshold date of exactly 2021-06-28, so that is the same effect as t: == 2021-06-28. However, t:2021 will match any threshold date in 2021, which is the same effect as t: >= 2021-01-01 and t: <= 2021-12-31.

Priority Comparison

  • priority will match any todo with a priority, and the expression priority <= B will match any todo with priority A or B. You can also use the ==, =, !=, <, >, or >= operators, and any letter from A to Z to form a comparison.
  • pri can be used as an abbreviation for priority.
  • the alternate form (B) can be used as an equivalent to pri == B.

Literal Text Match

  • if sleek can't parse your search string as a filter expression, it will default to doing a literal text match of your search against the string form of each todo.
  • you can add a literal text match to a filter expression by surrounding it with quotes, either double quotes or single quotes. Examples: "this text must be in the todo", 'single quotes', +bill and "some words".

Regular Expression Match

  • a regular expression is delimited by slashes, for example: /[0-9]+/ will match any sequence of digits. It is matched against the string form of the todo using JavaScript regular expression syntax. For example, due: < today and / rec:+?[0-9]*[dbwmy]/ could be used to look for todos with a recurrence value that are due before today.
Clone this wiki locally