|The Org Mode 7 Reference Manual
by Carsten Dominik and others
Paperback (6"x9"), 282 pages
RRP £9.95 ($14.95)
Sales of this book support the Org project! Get a printed copy>>>
16.17 Special agenda views
Org provides a special hook that can be used to narrow down the selection
made by these agenda views:
tags-tree. You may specify a function that is used at each match to verify
if the match should indeed be part of the agenda view, and if not, how
much should be skipped.
Let's say you want to produce a list of projects that contain a WAITING tag anywhere in the project tree. Let's further assume that you have marked all tree headings that define a project with the TODO keyword PROJECT. In this case you would run a TODO search for the keyword PROJECT, but skip the match unless there is a WAITING tag anywhere in the subtree belonging to the project line.
To achieve this, you must write a function that searches the subtree for
the tag. If the tag is found, the function must return
indicate that this match should not be skipped. If there is no such
tag, return the location of the end of the subtree, to indicate that
search should continue from there.
(defun my-skip-unless-waiting () "Skip trees that are not waiting" (let ((subtree-end (save-excursion (org-end-of-subtree t)))) (if (re-search-forward ":waiting:" subtree-end t) nil ; tag found, do not skip subtree-end))) ; tag not found, continue after end of subtree
Now you may use this function in an agenda custom command, for example like this:
(org-add-agenda-custom-command '("b" todo "PROJECT" ((org-agenda-skip-function 'my-skip-unless-waiting) (org-agenda-overriding-header "Projects waiting for something: "))))
Note that this also binds
org-agenda-overriding-header to get a
meaningful header in the agenda view.
A general way to create custom searches is to base them on a search for
entries with a certain level limit. If you want to study all entries with
your custom search function, simply do a search for
‘LEVEL>0’,(148) and then use
org-agenda-skip-function to select the entries
you really want to have.
You may also put a Lisp form into
particular, you may use the functions
org-agenda-skip-subtree-if in this form, for example:
- Skip current entry if it has been scheduled.
- Skip current entry if it has not been scheduled.
- Skip current entry if it has a deadline.
'(org-agenda-skip-entry-if 'scheduled 'deadline)
- Skip current entry if it has a deadline, or if it is scheduled.
'(org-agenda-skip-entry-if 'todo '("TODO" "WAITING"))
- Skip current entry if the TODO keyword is TODO or WAITING.
'(org-agenda-skip-entry-if 'todo 'done)
- Skip current entry if the TODO keyword marks a DONE state.
- Skip current entry if it has any timestamp, may also be deadline or scheduled.
'(org-agenda-skip-entry 'regexp "regular expression")
- Skip current entry if the regular expression matches in the entry.
'(org-agenda-skip-entry 'notregexp "regular expression")
- Skip current entry unless the regular expression matches.
'(org-agenda-skip-subtree-if 'regexp "regular expression")
- Same as above, but check and skip the entire subtree.
Therefore we could also have written the search for WAITING projects like this, even without defining a special function:
(org-add-agenda-custom-command '("b" todo "PROJECT" ((org-agenda-skip-function '(org-agenda-skip-subtree-if 'regexp ":waiting:")) (org-agenda-overriding-header "Projects waiting for something: "))))
|ISBN 9781906966089||The Org Mode 7 Reference Manual||See the print edition|