Function: org-agenda-filter
org-agenda-filter is an interactive and byte-compiled function defined
in org-agenda.el.gz.
Signature
(org-agenda-filter &optional STRIP-OR-ACCUMULATE)
Documentation
Prompt for a general filter string and apply it to the agenda.
The string may contain filter elements like
+category
+tag
+<effort > and = are also allowed as effort operators
+/regexp/
Instead of +, - is allowed to strip the agenda of matching entries.
+ is optional if it is not required to separate two string parts.
Multiple filter elements can be concatenated without spaces, for example
+work-John<0:10-/plot/
selects entries with category work and effort estimates below 10 minutes,
and deselects entries with tag John or matching the regexp plot.
During entry of the filter, completion for tags, categories and effort values is offered. Since the syntax for categories and tags is identical there should be no overlap between categories and tags. If there is, tags get priority.
A single C-u (universal-argument) prefix arg STRIP-OR-ACCUMULATE will negate the
entire filter, which can be useful in connection with the prompt history.
A double C-u (universal-argument) C-u (universal-argument) prefix arg will add the new filter elements to the
existing ones. A shortcut for this is to add an additional + at the
beginning of the string, like +-John.
With a triple prefix argument, execute the computed filtering defined in
the variable org-agenda-auto-exclude-function.
Key Bindings
Source Code
;; Defined in /usr/src/emacs/lisp/org/org-agenda.el.gz
(defun org-agenda-filter (&optional strip-or-accumulate)
"Prompt for a general filter string and apply it to the agenda.
The string may contain filter elements like
+category
+tag
+<effort > and = are also allowed as effort operators
+/regexp/
Instead of `+', `-' is allowed to strip the agenda of matching entries.
`+' is optional if it is not required to separate two string parts.
Multiple filter elements can be concatenated without spaces, for example
+work-John<0:10-/plot/
selects entries with category `work' and effort estimates below 10 minutes,
and deselects entries with tag `John' or matching the regexp `plot'.
During entry of the filter, completion for tags, categories and effort
values is offered. Since the syntax for categories and tags is identical
there should be no overlap between categories and tags. If there is, tags
get priority.
A single `\\[universal-argument]' prefix arg STRIP-OR-ACCUMULATE will negate the
entire filter, which can be useful in connection with the prompt history.
A double `\\[universal-argument] \\[universal-argument]' prefix arg will add the new filter elements to the
existing ones. A shortcut for this is to add an additional `+' at the
beginning of the string, like `+-John'.
With a triple prefix argument, execute the computed filtering defined in
the variable `org-agenda-auto-exclude-function'."
(interactive "P")
(if (equal strip-or-accumulate '(64))
;; Execute the auto-exclude action
(if (not org-agenda-auto-exclude-function)
(user-error "`org-agenda-auto-exclude-function' is undefined")
(org-agenda-filter-show-all-tag)
(setq org-agenda-tag-filter nil)
(dolist (tag (org-agenda-get-represented-tags))
(let ((modifier (funcall org-agenda-auto-exclude-function tag)))
(when modifier
(push modifier org-agenda-tag-filter))))
(unless (null org-agenda-tag-filter)
(org-agenda-filter-apply org-agenda-tag-filter 'tag 'expand)))
;; Prompt for a filter and act
(let* ((tag-list (org-agenda-get-represented-tags))
(category-list (org-agenda-get-represented-categories))
(negate (equal strip-or-accumulate '(4)))
(cf (mapconcat #'identity org-agenda-category-filter ""))
(tf (mapconcat #'identity org-agenda-tag-filter ""))
;; (rpl-fn (lambda (c) (replace-regexp-in-string "^\\+" "" (or (car c) ""))))
(ef (replace-regexp-in-string "^\\+" "" (or (car org-agenda-effort-filter) "")))
(rf (replace-regexp-in-string "^\\+" "" (or (car org-agenda-regexp-filter) "")))
(ff (concat cf tf ef (when (not (equal rf "")) (concat "/" rf "/"))))
(f-string (completing-read
(concat
(if negate "Negative filter" "Filter")
" [+cat-tag<0:10-/regexp/]: ")
#'org-agenda-filter-completion-function
nil nil ff))
(keep (or (if (string-match "^\\+[+-]" f-string)
(progn (setq f-string (substring f-string 1)) t))
(equal strip-or-accumulate '(16))))
(fc (if keep org-agenda-category-filter))
(ft (if keep org-agenda-tag-filter))
(fe (if keep org-agenda-effort-filter))
(fr (if keep org-agenda-regexp-filter))
pm s)
;; If the filter contains a double-quoted string, replace a
;; single hyphen by the arbitrary and temporary string "~~~"
;; to disambiguate such hyphens from syntactic ones.
(setq f-string (replace-regexp-in-string
"\"\\([^\"]*\\)-\\([^\"]*\\)\"" "\"\\1~~~\\2\"" f-string))
(while (string-match "^[ \t]*\\([-+]\\)?\\(\\([^-+<>=/ \t]+\\)\\|\\([<>=][0-9:]+\\)\\|\\(/\\([^/]+\\)/?\\)\\)" f-string)
(setq pm (if (match-beginning 1) (match-string 1 f-string) "+"))
(when negate
(setq pm (if (equal pm "+") "-" "+")))
(cond
((match-beginning 3)
;; category or tag
(setq s (replace-regexp-in-string ; Remove the temporary special string.
"~~~" "-" (match-string 3 f-string)))
(cond
((member s tag-list)
(org-pushnew-to-end (concat pm s) ft))
((member s category-list)
(org-pushnew-to-end (concat pm ; Remove temporary double quotes.
(replace-regexp-in-string "\"\\(.*\\)\"" "\\1" s))
fc))
(t (message
"`%s%s' filter ignored because tag/category is not represented"
pm s))))
((match-beginning 4)
;; effort
(org-pushnew-to-end (concat pm (match-string 4 f-string)) fe))
((match-beginning 5)
;; regexp
(org-pushnew-to-end (concat pm (match-string 6 f-string)) fr)))
(setq f-string (substring f-string (match-end 0))))
(org-agenda-filter-remove-all)
(and fc (org-agenda-filter-apply
(setq org-agenda-category-filter fc) 'category))
(and ft (org-agenda-filter-apply
(setq org-agenda-tag-filter ft) 'tag 'expand))
(and fe (org-agenda-filter-apply
(setq org-agenda-effort-filter fe) 'effort))
(and fr (org-agenda-filter-apply
(setq org-agenda-regexp-filter fr) 'regexp))
(run-hooks 'org-agenda-filter-hook))))