A few comments that might help navigate the new parser code in
org-tag-query-parse.el. All diffs are relative to the 7.8.11 org.el.
Let me know if you have any questions.
* High Level Changes
Two existing org functions are altered:
1. org-make-tags-matcher
2. org-scan-tags
The changes to the latter are minor, only defining two new
let-bindings to capture information already grabbed, and a slightly
modified regex. A unified diff between the new and old org-scan-tags
is given in the comments preceding the function in the new code.
* Low Level Entry Points
1. org-tag-query-parse -- the workhorse function
2. org-todo-query-parse -- handles /!? style todo components
Tag style and /!? todo style queries are handled in a unified way;
org-tag-query-parse delegates the latter to org-todo-query-parse but
manages the overall parsing. Note that /!? style matches must either
end the query string or end the current parenthesized expression. For
instance, "-(foo+bar/!{^T}-TODO)|LEVEL==5" is a valid query.
* Utilities
1. org-match-cond
2. org-read-balanced-string
3. org-read-quoted-string-in-query
4. org-tquery-error
5. org-defhash-at-compile
The first is a macro that lets the parser be expressed in very
readable terms. It does much of its work at compile-time, and produces
code that is optimized in several ways. This makes it beneficial to
byte-compile org-tag-query-parse.el.
The second and third parse delimited strings, the first with
balanced delimiters and doubling for escape, the second using
standard string semantics.
The fourth handles errors, giving useful information in messages.
The fifth is a macro that makes it pleasant to define literal
hash tables that will be defined at both compile and load time.
See examples of use in the code.