Advanced todo.txt filtering

[harshad1]

Description of the advanced filter syntax

The todo.txt advanced filter syntax allows one to filter todo items using a simple query language.

For example (pri:A | pri:B) & +home will match tasks with priority A or priority B and which have the project +home

Filter types

• Priority: pri:[(A through Z)].
  • pri:A will match tasks with priority A
  • pri will match any task with a priority
  • !pri with therefore match tasks with no priority
• Context: Words starting with '@' will match contexts. @ alone will match tasks with any context
  • Use !@ to match tasks with no contexts
• Project: Words starting with '+' wll match projects. + alone will match tasks with any project
  • Use !+ to match tasks with no projects
• Due date:
  • 'due' will match tasks with any due date
    • Use !due to match tasks with no due date
  • 'due=' will match tasks with due date today
  • 'due<' or will match tasks with due date which has already passed (overdue)
  • 'due>' will match tasks which are due in the future
• Done: the word done will match done tasks

Operators

Operation	Symbol	Examples	Translation
NOT	!	!done	not done
AND	&	pri:A & due=	priority A and due today
OR	|	pri:C | pri:D | !pri	priority C or priority D or no priority

• ( and ) can be used to group expressions
• Each element in the expression must be surrounded by spaces. Exceptions are:
  1. No need for a space after open parenthesis
  2. No need for a space before closing parenthesis
  3. No need for space following !
  4. No need for spaces at the beginning and end of the query

Evaluation

The filter expression is evaluated left to right (i.e. 'and' and 'or' have the same precedence). 'Not' is applied to the result of the expression to it's immediate right.

Done tasks are not excluded by default. They must be excluded explicitly.

Examples:

• !+ & !@ & !pri & !done - No projects, no contexts, no priority and not done
• !+ | !@ & !done - will match tasks which have either no projects or no contexts and which are not done
  • i.e. this is equivalent to (!+ | !@) & !done

A note on implementation:

• A series of preprocessing stages are used to split the query into a sequence of symbols - operators and queries
• Each query of the expression is evaluated to construct a boolean expression. For example the expression (pri:C | pri:D | ~) & !done applied to the todo D 2022-01-01 foo will evaluate to the string "( F | T | F ) & !F" (spaces added here for clarity)
• The boolean expression is then evaluated to 'T' or 'F' using a simple stack based algorithm
• Any errors (syntax errors, mismatched parenthesis etc) will cause a task to evaluate to 'F' (i.e. false)

[gsantner]

@harshad1
This discussion is merely meant to write down how it works right? Do you think it would fit for the doc folder? https://github.com/gsantner/markor/tree/master/doc